Skip to content

Commit 9945f66

Browse files
belenweiclaude
belenwei
and
claude
committed
Add documentation sync and deploy skill
Features: - Created automation script for syncing Lark docs and deploying - Added comprehensive skill documentation (SKILL-sync-deploy.md) - Added quick reference card for users (docs/.claude/sync-deploy-skill.md) - Updated README with workflow documentation - Script supports both manual and Claude Code automation Usage: - Tell Claude: "同步 <Lark_URL> 并部署到远程" - Or run: ./scripts/sync-lark-and-deploy.sh --url <url> --token <token> Benefits: - Automated documentation synchronization workflow - Quality assurance with deep comparison - One-command deployment to GitHub Pages - Preserves local corrections when source has errors Co-Authored-By: Claude (global.anthropic.claude-sonnet-4-5-20250929-v1:0) <[email protected]>
1 parent 2b8ce37 commit 9945f66

File tree

4 files changed

+733
-0
lines changed

4 files changed

+733
-0
lines changed

‎README.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,4 +86,44 @@ Ensure you have set the `GIT_USER` environment variable before trying to deploy.
8686
yarn deploy
8787
```
8888

89+
### Documentation Sync Workflow
90+
91+
This project includes an automated workflow for syncing documentation from Lark wiki and deploying to GitHub Pages.
92+
93+
#### Using Claude Code (Recommended)
94+
95+
Tell Claude Code to sync and deploy:
96+
97+
```
98+
同步 <Lark_URL> 并部署到远程
99+
```
100+
101+
Claude will automatically:
102+
1. Fetch the latest documentation from Lark
103+
2. Compare with local files and identify differences
104+
3. Update all changed files
105+
4. Commit and push to GitHub
106+
5. Deploy to GitHub Pages (if token provided)
107+
108+
See [SKILL-sync-deploy.md](./SKILL-sync-deploy.md) for detailed workflow documentation.
109+
110+
#### Using the Script Manually
111+
112+
```bash
113+
# Basic sync (no deploy)
114+
./scripts/sync-lark-and-deploy.sh --url "<lark_url>"
115+
116+
# Sync and deploy
117+
./scripts/sync-lark-and-deploy.sh --url "<lark_url>" --token "<github_token>"
118+
119+
# Custom documentation path
120+
./scripts/sync-lark-and-deploy.sh --url "<lark_url>" --path "./docs/custom-path"
121+
```
122+
123+
#### GitHub Actions Auto-Deployment
124+
125+
Every push to `master` branch automatically deploys to GitHub Pages via GitHub Actions.
126+
127+
Configuration: [.github/workflows/deploy.yml](./.github/workflows/deploy.yml)
128+
89129

‎SKILL-sync-deploy.md‎

Lines changed: 292 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,292 @@
1+
---
2+
name: sync-lark-and-deploy
3+
description: Sync documentation from Lark wiki and deploy to GitHub Pages
4+
version: 1.0.0
5+
allowed-tools:
6+
- bash
7+
- read
8+
- write
9+
- edit
10+
- glob
11+
- grep
12+
- task
13+
---
14+
15+
# Sync Lark Documentation and Deploy
16+
17+
Automatically synchronize documentation from Lark wiki, update local files, and deploy to GitHub Pages.
18+
19+
## When to Use
20+
21+
**Trigger Keywords** (Claude Code should activate this skill when user mentions):
22+
- **同步** Lark 文档并 **部署**
23+
- **Sync** Lark documentation and **deploy**
24+
- **更新**文档到远程 / **Update** docs to remote
25+
- **发布**文档 / **Publish** documentation
26+
- From Lark to GitHub Pages
27+
28+
This skill activates when the user:
29+
- Wants to sync documentation from Lark wiki to local repository
30+
- Needs to deploy updated documentation to GitHub Pages
31+
- Requests automatic documentation update workflow
32+
- Mentions both Lark URL and deployment in the same request
33+
34+
## Core Workflow
35+
36+
### Full Automated Flow (Recommended)
37+
38+
When user provides:
39+
- Lark document URL (starting with `https://uponly.larksuite.com/wiki/`)
40+
- Request to sync and deploy
41+
- Optional: GitHub token for deployment
42+
43+
Execute the following steps:
44+
45+
#### Step 1: Fetch Lark Document
46+
```bash
47+
# Use lark-doc skill to fetch the document
48+
node ~/.claude/plugins/cache/ai-coding-marketplace/lark-doc-skills/*/skills/lark-doc/scripts/fetch-lark-doc.mjs "<lark_url>"
49+
```
50+
51+
Save the output to a temporary file for comparison.
52+
53+
#### Step 2: Deep Comparison
54+
Use Task tool with `subagent_type=Explore` to compare:
55+
- Lark document content vs local documentation
56+
- Identify all differences (version history, API changes, field names, examples, etc.)
57+
- Create a comprehensive list of changes needed
58+
59+
**Important**:
60+
- Compare data models and examples for consistency
61+
- Verify field naming conventions (camelCase vs snake_case)
62+
- Check timestamp formats (number vs string)
63+
- Note any contradictions in the source document
64+
65+
#### Step 3: Update Local Documentation
66+
Create tasks for each identified difference:
67+
```javascript
68+
// Example tasks:
69+
1. Update version history in introduction.mdx
70+
2. Add missing API headers in guide.mdx
71+
3. Update field names in API documentation
72+
4. Add/update webhook parameters
73+
5. Update flowcharts (ASCII to Mermaid)
74+
6. Mark deprecated APIs
75+
7. Verify data models
76+
8. Update error codes
77+
```
78+
79+
Execute each task systematically:
80+
- Read existing files
81+
- Make precise edits using Edit tool
82+
- Preserve correct content (don't blindly copy errors from source)
83+
- Verify consistency across related files
84+
85+
#### Step 4: Git Commit
86+
```bash
87+
git add docs/
88+
git commit -m "$(cat <<'EOF'
89+
Sync documentation from Lark
90+
91+
Source: <lark_url>
92+
Changes:
93+
- [List major changes]
94+
- [List major changes]
95+
96+
Co-Authored-By: Claude (global.anthropic.claude-sonnet-4-5-20250929-v1:0) <[email protected]>
97+
EOF
98+
)"
99+
```
100+
101+
#### Step 5: Push to Remote
102+
```bash
103+
git push origin master
104+
```
105+
106+
#### Step 6: Deploy to GitHub Pages (if token provided)
107+
```bash
108+
# Temporarily update remote URL with token
109+
ORIGINAL_REMOTE=$(git remote get-url origin)
110+
git remote set-url origin "https://${GITHUB_TOKEN}@github.com/<org>/<repo>.git"
111+
112+
# Build and deploy
113+
npm run build
114+
npm run deploy
115+
116+
# Restore original remote
117+
git remote set-url origin "$ORIGINAL_REMOTE"
118+
```
119+
120+
### Quality Assurance
121+
122+
**Before finalizing updates:**
123+
1. **Cross-reference**: Compare API documentation with data models
124+
2. **Consistency check**: Verify naming conventions across all files
125+
3. **Format validation**: Ensure timestamp types, currency formats are consistent
126+
4. **Source validation**: If source document contains contradictions, prefer local correctness
127+
5. **User confirmation**: Report any ambiguities to user before proceeding
128+
129+
### Script Usage (Alternative)
130+
131+
For manual or semi-automated workflow:
132+
133+
```bash
134+
# Basic usage (no auto-deploy)
135+
./scripts/sync-lark-and-deploy.sh --url "<lark_url>"
136+
137+
# With auto-deploy
138+
./scripts/sync-lark-and-deploy.sh --url "<lark_url>" --token "<github_token>"
139+
140+
# Custom documentation path
141+
./scripts/sync-lark-and-deploy.sh --url "<lark_url>" --path "./docs/custom-path"
142+
143+
# Skip git commit
144+
./scripts/sync-lark-and-deploy.sh --url "<lark_url>" --no-commit
145+
```
146+
147+
## Configuration
148+
149+
### Prerequisites
150+
- Node.js installed
151+
- lark-doc-skills plugin installed
152+
- Git repository with proper remote setup
153+
- npm packages installed (`npm ci`)
154+
- GitHub Pages configured (for deployment)
155+
156+
### Environment
157+
- **Repository**: Should be a Docusaurus project
158+
- **Build command**: `npm run build`
159+
- **Deploy command**: `npm run deploy` (configured for GitHub Pages)
160+
- **Main branch**: `master` or `main`
161+
162+
## Examples
163+
164+
### Example 1: Quick Sync and Deploy
165+
**User**: "同步 https://uponly.larksuite.com/wiki/StZZwcTsniQD2OkIZ0vu59dHsxd 并部署到远程"
166+
167+
**Claude Code Actions**:
168+
1. Fetch Lark document using lark-doc skill
169+
2. Compare with local docs at `./docs/scan-payment`
170+
3. Update all identified differences
171+
4. Commit with message: "Sync documentation from Lark"
172+
5. Push to GitHub
173+
6. Ask for GitHub token if deployment needed
174+
7. Build and deploy to GitHub Pages
175+
176+
### Example 2: Sync Without Deploy
177+
**User**: "更新文档从 Lark: https://uponly.larksuite.com/wiki/xxx"
178+
179+
**Claude Code Actions**:
180+
1. Fetch Lark document
181+
2. Compare and update local files
182+
3. Commit changes
183+
4. Push to remote
184+
5. Skip deployment (no token provided)
185+
186+
### Example 3: Deploy After Manual Changes
187+
**User**: "直接帮我 deploy"
188+
189+
**Claude Code Actions**:
190+
1. Ask for GitHub token
191+
2. Build project: `npm run build`
192+
3. Deploy to GitHub Pages: `npm run deploy`
193+
4. Restore git remote URL
194+
5. Confirm deployment URL
195+
196+
## Error Handling
197+
198+
| Error | Cause | Solution |
199+
|-------|-------|----------|
200+
| Lark auth failed | Token expired | Re-authenticate using lark-doc skill |
201+
| Build failed | npm dependencies | Run `npm ci` to reinstall |
202+
| Deploy failed | Invalid token | Check GitHub token permissions (repo, pages) |
203+
| Git push failed | No remote access | Verify git remote URL and credentials |
204+
| Merge conflict | Concurrent changes | Resolve conflicts manually |
205+
206+
## Best Practices
207+
208+
1. **Always compare before updating**: Don't blindly copy content
209+
2. **Preserve local corrections**: If local docs are more accurate, keep them
210+
3. **Verify data consistency**: Check that examples match data model definitions
211+
4. **Test build locally**: Run `npm run build` before deploying
212+
5. **Review git diff**: Check changes before committing
213+
6. **Secure tokens**: Never commit tokens, remove from git remote after use
214+
215+
## Related Skills
216+
217+
- `lark-doc`: Fetch Lark documents with authentication
218+
- Task tool with `Explore` agent: Deep codebase comparison
219+
- Git commit workflow: Proper commit message formatting
220+
221+
## References
222+
223+
### Files Modified in Typical Sync
224+
```
225+
docs/scan-payment/
226+
├── introduction.mdx # Version history, overview
227+
├── guide.mdx # Authentication, API basics
228+
├── flow.mdx # Flowcharts, state machines
229+
├── payment-notify.mdx # Webhook documentation
230+
├── create-payment.mdx # Payment creation API
231+
├── payment-result.mdx # Query payment API
232+
├── refund.mdx # Refund API
233+
├── payout.mdx # Payout API
234+
└── settlement.mdx # Settlement API
235+
```
236+
237+
### GitHub Pages Deployment
238+
- **Branch**: `gh-pages`
239+
- **Directory**: `/` (root)
240+
- **Build output**: `./build`
241+
- **Typical URL**: `https://<org>.github.io/<repo>/`
242+
243+
### Workflow Files
244+
- `.github/workflows/deploy.yml`: GitHub Actions auto-deployment
245+
- `scripts/sync-lark-and-deploy.sh`: Manual sync script
246+
- `package.json`: Build and deploy scripts
247+
- `docusaurus.config.js`: Site configuration
248+
249+
## Troubleshooting
250+
251+
### Issue: Local docs are more accurate than Lark
252+
**Solution**: Prefer local correctness. Inform user about discrepancies.
253+
254+
Example from previous sync:
255+
- Lark had `refund_amount` (snake_case) in examples
256+
- Data model showed `refundAmount` (camelCase)
257+
- Local docs correctly used `refundAmount` throughout
258+
- Decision: Keep local docs, report issue to user
259+
260+
### Issue: Large documentation set
261+
**Solution**: Use Task tool to parallelize updates
262+
- Create separate tasks for each file
263+
- Update tasks as you progress
264+
- Mark completed when done
265+
266+
### Issue: Deployment fails with 403
267+
**Solution**: Check GitHub token permissions
268+
- Required scopes: `repo`, `workflow`, `pages`
269+
- Generate new token from GitHub settings if needed
270+
271+
## Version History
272+
273+
| Version | Date | Changes |
274+
|:--------|:-----|:--------|
275+
| 1.0.0 | 2026-01-28 | Initial release with full automation support |
276+
277+
---
278+
279+
## Quick Reference Card
280+
281+
**User says**: "同步 Lark 并部署"
282+
283+
**You should**:
284+
1. ✅ Fetch Lark document (lark-doc skill)
285+
2. ✅ Deep compare with local (Task/Explore agent)
286+
3. ✅ Update all differences systematically
287+
4. ✅ Commit with descriptive message
288+
5. ✅ Push to remote
289+
6. ✅ Deploy to GitHub Pages (if token provided)
290+
7. ✅ Confirm deployment URL
291+
292+
**Key principle**: Compare carefully, preserve correctness, automate fearlessly.

0 commit comments

Comments
 (0)