Skip to content

Commit c172736

Browse files
crupcrup
committed
docs(docs): switch to docusaurus recipe playgrounds
1 parent f12c3a6 commit c172736

43 files changed

Lines changed: 12132 additions & 4217 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 31 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -13,34 +13,56 @@ jobs:
1313
verify:
1414
runs-on: ubuntu-latest
1515
steps:
16-
- name: Checkout
16+
- name: 1. Checkout source
1717
uses: actions/checkout@v4
1818

19-
- name: Setup pnpm
19+
- name: 2. Setup pnpm
2020
uses: pnpm/action-setup@v4
2121
with:
2222
version: 10.30.2
2323

24-
- name: Setup Node
24+
- name: 3. Setup Node 25
2525
uses: actions/setup-node@v4
2626
with:
2727
node-version: 25
2828
cache: pnpm
2929

30-
- name: Install
30+
- name: 4. Install dependencies
31+
id: install
3132
run: pnpm install --frozen-lockfile
3233

33-
- name: Typecheck
34+
- name: 5. Typecheck library
35+
id: typecheck
3436
run: pnpm typecheck
3537

36-
- name: Test
38+
- name: 6. Run tests
39+
id: test
3740
run: pnpm test
3841

39-
- name: Build
42+
- name: 7. Build package
43+
id: build
4044
run: pnpm build
4145

42-
- name: Build docs
46+
- name: 8. Build Docusaurus docs
47+
id: docs
4348
run: pnpm docs:build
4449

45-
- name: Check README
50+
- name: 9. Check README
51+
id: readme
4652
run: pnpm readme:check
53+
54+
- name: CI summary
55+
if: always()
56+
run: |
57+
{
58+
echo "## CI pipeline"
59+
echo
60+
echo "| Stage | Result |"
61+
echo "| --- | --- |"
62+
echo "| Install | ${{ steps.install.outcome }} |"
63+
echo "| Typecheck | ${{ steps.typecheck.outcome }} |"
64+
echo "| Tests | ${{ steps.test.outcome }} |"
65+
echo "| Package build | ${{ steps.build.outcome }} |"
66+
echo "| Docs build | ${{ steps.docs.outcome }} |"
67+
echo "| README check | ${{ steps.readme.outcome }} |"
68+
} >> "$GITHUB_STEP_SUMMARY"

‎.github/workflows/docs.yml‎

Lines changed: 31 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -22,37 +22,58 @@ jobs:
2222
url: ${{ steps.deployment.outputs.page_url }}
2323
runs-on: ubuntu-latest
2424
steps:
25-
- name: Checkout
25+
- name: 1. Checkout source
2626
uses: actions/checkout@v4
2727

28-
- name: Setup pnpm
28+
- name: 2. Setup pnpm
2929
uses: pnpm/action-setup@v4
3030
with:
3131
version: 10.30.2
3232

33-
- name: Setup Node
33+
- name: 3. Setup Node 25
3434
uses: actions/setup-node@v4
3535
with:
3636
node-version: 25
3737
cache: pnpm
3838

39-
- name: Install
39+
- name: 4. Install dependencies
4040
run: pnpm install --frozen-lockfile
4141

42-
- name: Build package
42+
- name: 5. Build package
43+
id: package
4344
run: pnpm build
4445

45-
- name: Build docs
46+
- name: 6. Build Docusaurus docs
47+
id: docs
4648
run: pnpm docs:build
4749

48-
- name: Configure Pages
50+
- name: 7. Configure GitHub Pages
51+
id: pages
4952
uses: actions/configure-pages@v5
5053

51-
- name: Upload Pages artifact
54+
- name: 8. Upload Pages artifact
55+
id: artifact
5256
uses: actions/upload-pages-artifact@v3
5357
with:
54-
path: docs-dist
58+
path: docs-site/build
5559

56-
- name: Deploy Pages
60+
- name: 9. Deploy GitHub Pages
5761
id: deployment
5862
uses: actions/deploy-pages@v4
63+
64+
- name: Docs summary
65+
if: always()
66+
run: |
67+
{
68+
echo "## Docs pipeline"
69+
echo
70+
echo "| Stage | Result |"
71+
echo "| --- | --- |"
72+
echo "| Build package | ${{ steps.package.outcome }} |"
73+
echo "| Build Docusaurus docs | ${{ steps.docs.outcome }} |"
74+
echo "| Configure Pages | ${{ steps.pages.outcome }} |"
75+
echo "| Upload artifact | ${{ steps.artifact.outcome }} |"
76+
echo "| Deploy Pages | ${{ steps.deployment.outcome }} |"
77+
echo
78+
echo "Docs URL: https://crup.github.io/react-timer-hook/"
79+
} >> "$GITHUB_STEP_SUMMARY"

‎.github/workflows/prerelease.yml‎

Lines changed: 32 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -17,52 +17,75 @@ jobs:
1717
if: github.ref_name == 'next'
1818
runs-on: ubuntu-latest
1919
steps:
20-
- name: Checkout
20+
- name: 1. Checkout next
2121
uses: actions/checkout@v4
2222

23-
- name: Setup pnpm
23+
- name: 2. Setup pnpm
2424
uses: pnpm/action-setup@v4
2525
with:
2626
version: 10.30.2
2727

28-
- name: Setup Node
28+
- name: 3. Setup Node 25
2929
uses: actions/setup-node@v4
3030
with:
3131
node-version: 25
3232
cache: pnpm
3333
registry-url: https://registry.npmjs.org
3434

35-
- name: Install
35+
- name: 4. Install dependencies
36+
id: install
3637
run: pnpm install --frozen-lockfile
3738

38-
- name: Verify
39+
- name: 5. Verify package
40+
id: verify
3941
run: |
4042
pnpm typecheck
4143
pnpm test
4244
43-
- name: Set prerelease version
45+
- name: 6. Set alpha version
46+
id: version
4447
env:
4548
PACKAGE_VERSION: ${{ inputs.version_base }}-alpha.${{ github.run_number }}
4649
run: |
4750
node -e "const fs = require('node:fs'); const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8')); pkg.version = process.env.PACKAGE_VERSION; fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');"
4851
node -e "const pkg = require('./package.json'); console.log(pkg.name + '@' + pkg.version);"
52+
node -e "const pkg = require('./package.json'); require('node:fs').appendFileSync(process.env.GITHUB_OUTPUT, 'package=' + pkg.name + '@' + pkg.version + '\n');"
4953
50-
- name: Build package
54+
- name: 7. Build and measure package
55+
id: build
5156
run: |
5257
pnpm build
5358
pnpm size
5459
55-
- name: Publish prerelease
60+
- name: 8. Publish alpha
61+
id: publish
5662
run: pnpm publish --tag alpha --access public --no-git-checks
5763
env:
5864
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
5965
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
6066

61-
- name: Keep npm latest on current alpha
67+
- name: 9. Keep npm latest on current alpha
68+
id: tag
6269
run: |
6370
PACKAGE_NAME=$(node -p "require('./package.json').name")
6471
PACKAGE_VERSION=$(node -p "require('./package.json').version")
6572
npm dist-tag add "$PACKAGE_NAME@$PACKAGE_VERSION" latest
6673
env:
6774
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
6875
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
76+
77+
- name: Prerelease summary
78+
if: always()
79+
run: |
80+
{
81+
echo "## Alpha prerelease"
82+
echo
83+
echo "| Stage | Result |"
84+
echo "| --- | --- |"
85+
echo "| Install | ${{ steps.install.outcome }} |"
86+
echo "| Verify | ${{ steps.verify.outcome }} |"
87+
echo "| Version | ${{ steps.version.outputs.package }} |"
88+
echo "| Build and size | ${{ steps.build.outcome }} |"
89+
echo "| Publish alpha | ${{ steps.publish.outcome }} |"
90+
echo "| Sync npm latest tag | ${{ steps.tag.outcome }} |"
91+
} >> "$GITHUB_STEP_SUMMARY"

‎.github/workflows/size.yml‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -14,43 +14,43 @@ jobs:
1414
compare:
1515
runs-on: ubuntu-latest
1616
steps:
17-
- name: Checkout head
17+
- name: 1. Checkout head
1818
uses: actions/checkout@v4
1919
with:
2020
path: head
2121

22-
- name: Checkout main
22+
- name: 2. Checkout main baseline
2323
uses: actions/checkout@v4
2424
with:
2525
ref: main
2626
path: base
2727

28-
- name: Setup pnpm
28+
- name: 3. Setup pnpm
2929
uses: pnpm/action-setup@v4
3030
with:
3131
version: 10.30.2
3232

33-
- name: Setup Node
33+
- name: 4. Setup Node 25
3434
uses: actions/setup-node@v4
3535
with:
3636
node-version: 25
3737

38-
- name: Build head
38+
- name: 5. Build head package
3939
working-directory: head
4040
run: |
4141
pnpm install --frozen-lockfile
4242
pnpm build
4343
node scripts/size-report.mjs --json > ../head-size.json
4444
45-
- name: Build base
45+
- name: 6. Build main baseline
4646
working-directory: base
4747
continue-on-error: true
4848
run: |
4949
pnpm install --frozen-lockfile
5050
pnpm build
5151
node scripts/size-report.mjs --json > ../base-size.json
5252
53-
- name: Compare size
53+
- name: 7. Compare bundle size
5454
id: compare
5555
run: |
5656
if [ -f base-size.json ]; then
@@ -64,15 +64,15 @@ jobs:
6464
} > size-summary.md
6565
fi
6666
67-
- name: Comment size report
67+
- name: 8. Comment size report
6868
if: github.event_name == 'pull_request'
6969
uses: actions/github-script@v7
7070
with:
7171
script: |
7272
const fs = require('node:fs');
7373
const marker = '<!-- react-timer-hook-size-report -->';
7474
const body = `${marker}
75-
## Bundle size
75+
## Bundle size report
7676
7777
${fs.readFileSync('size-summary.md', 'utf8')}`;
7878
const { owner, repo } = context.repo;

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -131,6 +131,8 @@ dist
131131
docs-api
132132
docs-dist
133133
.astro
134+
docs-site/.docusaurus
135+
docs-site/build
134136

135137
# Gatsby files
136138
.cache/

‎README.md‎

Lines changed: 43 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,16 @@
1212

1313
📚 Docs: https://crup.github.io/react-timer-hook/
1414

15+
## Docs and live examples
16+
17+
The documentation site is built with Docusaurus and includes live React playgrounds for 15 recipes:
18+
19+
- Basic: clock, stopwatch, absolute countdown, pausable countdown, manual controls
20+
- Intermediate: once-only `onEnd`, polling, poll-and-cancel, backend events, debug logs
21+
- Advanced: many display timers, timer groups, global controls, per-item polling, dynamic items
22+
23+
Open: https://crup.github.io/react-timer-hook/
24+
1525
## Why it is different
1626

1727
Most timer libraries mix scheduling, lifecycle, formatting, and app behavior. This package keeps the core small:
@@ -136,12 +146,43 @@ CI writes a size summary to the GitHub Actions UI and posts a bundle-size commen
136146

137147
## AI-friendly
138148

139-
Agents can start with:
149+
End users do not need these files. They are for coding agents, docs-aware IDEs, and MCP clients.
150+
151+
### MCP setup
152+
153+
Clone the repo, install dependencies, and point your MCP client at the local stdio server:
154+
155+
```sh
156+
git clone https://github.com/crup/react-timer-hook.git
157+
cd react-timer-hook
158+
pnpm install
159+
```
160+
161+
```json
162+
{
163+
"mcpServers": {
164+
"react-timer-hook-docs": {
165+
"command": "node",
166+
"args": ["/absolute/path/to/react-timer-hook/mcp/server.mjs"]
167+
}
168+
}
169+
}
170+
```
171+
172+
The MCP server exposes:
173+
174+
```txt
175+
react-timer-hook://package
176+
react-timer-hook://api
177+
react-timer-hook://recipes
178+
```
179+
180+
Agents can use hosted context:
140181

141182
- https://crup.github.io/react-timer-hook/llms.txt
142183
- https://crup.github.io/react-timer-hook/llms-full.txt
143184

144-
Local helpers:
185+
Local MCP/docs helpers:
145186

146187
```sh
147188
pnpm ai:context

0 commit comments

Comments
 (0)