Skip to content

Commit 093a0ba

Browse files
xentixarxentixar
committed
Initial VitePress setup
0 parents  commit 093a0ba

File tree

11 files changed

+1124
-0
lines changed

11 files changed

+1124
-0
lines changed

‎.github/workflows/deploy.yml‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
pages: write
12+
id-token: write
13+
14+
concurrency:
15+
group: pages
16+
cancel-in-progress: false
17+
18+
jobs:
19+
build-and-deploy:
20+
runs-on: ubuntu-latest
21+
steps:
22+
- name: Checkout this repo
23+
uses: actions/checkout@v4
24+
with:
25+
fetch-depth: 0
26+
27+
- name: Checkout docs repo
28+
uses: actions/checkout@v4
29+
with:
30+
repository: diffyne/docs
31+
path: docs-source
32+
token: ${{ secrets.GITHUB_TOKEN }}
33+
34+
- name: Setup Node.js
35+
uses: actions/setup-node@v4
36+
with:
37+
node-version: 24
38+
cache: 'npm'
39+
40+
- name: Install dependencies
41+
run: npm ci
42+
43+
- name: Sync docs from docs repo
44+
run: npm run sync
45+
env:
46+
DOCS_SOURCE_PATH: ./docs-source
47+
48+
- name: Build documentation
49+
run: npm run build
50+
51+
- name: Setup Pages
52+
uses: actions/configure-pages@v4
53+
54+
- name: Upload artifact
55+
uses: actions/upload-pages-artifact@v3
56+
with:
57+
path: docs/.vitepress/dist
58+
59+
- name: Deploy to GitHub Pages
60+
id: deployment
61+
uses: actions/deploy-pages@v4
62+

‎.github/workflows/sync-docs.yml‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
name: Sync Documentation
2+
3+
on:
4+
workflow_dispatch:
5+
inputs:
6+
source_repo:
7+
description: 'Source repository (owner/repo)'
8+
required: true
9+
default: 'diffyne/docs'
10+
source_path:
11+
description: 'Path to docs in source repo (leave empty for root)'
12+
required: false
13+
default: ''
14+
schedule:
15+
# Run daily at 2 AM UTC
16+
- cron: '0 2 * * *'
17+
18+
jobs:
19+
sync:
20+
runs-on: ubuntu-latest
21+
steps:
22+
- name: Checkout this repo
23+
uses: actions/checkout@v4
24+
with:
25+
token: ${{ secrets.GITHUB_TOKEN }}
26+
27+
- name: Checkout source repo
28+
uses: actions/checkout@v4
29+
with:
30+
repository: ${{ github.event.inputs.source_repo || 'diffyne/docs' }}
31+
path: source-repo
32+
token: ${{ secrets.GITHUB_TOKEN }}
33+
34+
- name: Setup Node.js
35+
uses: actions/setup-node@v4
36+
with:
37+
node-version: 24
38+
cache: 'npm'
39+
40+
- name: Install dependencies
41+
run: npm ci
42+
43+
- name: Sync documentation
44+
run: npm run sync
45+
env:
46+
DOCS_SOURCE_PATH: ./source-repo/${{ github.event.inputs.source_path || '' }}
47+
48+
- name: Check for changes
49+
id: check
50+
run: |
51+
if [ -n "$(git status --porcelain)" ]; then
52+
echo "changed=true" >> $GITHUB_OUTPUT
53+
else
54+
echo "changed=false" >> $GITHUB_OUTPUT
55+
fi
56+
57+
- name: Commit and push changes
58+
if: steps.check.outputs.changed == 'true'
59+
run: |
60+
git config user.name "github-actions[bot]"
61+
git config user.email "github-actions[bot]@users.noreply.github.com"
62+
git add docs/
63+
git commit -m "docs: sync from main repository"
64+
git push
65+

‎.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
node_modules
2+
.DS_Store
3+
dist
4+
.cache
5+
.vitepress/cache
6+
.vitepress/dist
7+

‎ARCHITECTURE.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
# Documentation Architecture
2+
3+
This document explains the architecture and workflow of the Diffyne documentation system.
4+
5+
## Repository Structure
6+
7+
### Source Repository: `diffyne/docs`
8+
- **Purpose**: Source of truth for all documentation
9+
- **Location**: https://github.com/diffyne/docs
10+
- **Content**: Raw markdown files organized by topic
11+
- **Workflow**: Contributors edit documentation here
12+
13+
### Deployment Repository: `diffyne.github.io`
14+
- **Purpose**: GitHub Pages deployment site
15+
- **Location**: https://github.com/diffyne/diffyne.github.io
16+
- **Content**: VitePress site with synced documentation
17+
- **Workflow**: Automatically builds and deploys from source
18+
19+
## Data Flow
20+
21+
```
22+
┌─────────────────┐
23+
│ diffyne/docs │ (Source Repository)
24+
│ │
25+
│ - .md files │
26+
│ - Examples │
27+
│ - Guides │
28+
└────────┬────────┘
29+
│
30+
│ Sync (npm run sync)
31+
│
32+
▼
33+
┌────────────────────┐
34+
│ diffyne.github.io │ (Deployment Repository)
35+
│ │
36+
│ - VitePress │
37+
│ - Build config │
38+
│ - GitHub Actions │
39+
└────────────────────┘
40+
```
41+
42+
## Sync Process
43+
44+
### Manual Sync
45+
46+
1. Edit docs in `diffyne/docs`
47+
2. Run sync script:
48+
```bash
49+
cd diffyne.github.io
50+
DOCS_SOURCE_PATH=../docs npm run sync
51+
```
52+
3. Review changes
53+
4. Commit and push
54+
55+
### Automated Sync
56+
57+
GitHub Actions automatically:
58+
1. Checks out both repositories
59+
2. Syncs documentation
60+
3. Builds VitePress site
61+
4. Deploys to GitHub Pages
62+
63+
Triggered by:
64+
- Push to `main` branch
65+
- Manual workflow dispatch
66+
- Scheduled (daily sync)
67+
68+
## File Structure
69+
70+
### Source Repository (`diffyne/docs`)
71+
```
72+
docs/
73+
├── getting-started/
74+
│ ├── installation.md
75+
│ ├── quickstart.md
76+
│ └── first-component.md
77+
├── features/
78+
│ ├── directives.md
79+
│ ├── data-binding.md
80+
│ └── ...
81+
├── examples/
82+
│ ├── counter.md
83+
│ └── ...
84+
└── advanced/
85+
├── security.md
86+
└── ...
87+
```
88+
89+
### Deployment Repository (`diffyne.github.io`)
90+
```
91+
diffyne.github.io/
92+
├── docs/
93+
│ ├── .vitepress/
94+
│ │ └── config.js # VitePress configuration
95+
│ ├── guide/ # Synced from source (docs/guide/)
96+
│ │ ├── getting-started/
97+
│ │ ├── features/
98+
│ │ └── ...
99+
│ └── index.md # Homepage
100+
├── scripts/
101+
│ └── sync-docs.js # Sync script
102+
├── .github/
103+
│ └── workflows/
104+
│ ├── deploy.yml # Deployment workflow
105+
│ └── sync-docs.yml # Sync workflow
106+
└── package.json
107+
```
108+
109+
## Sync Script Features
110+
111+
The `sync-docs.js` script:
112+
1. **Copies** markdown files from source
113+
2. **Adds** VitePress frontmatter if missing
114+
3. **Fixes** relative links to work with VitePress routing
115+
4. **Preserves** directory structure
116+
5. **Logs** all synced files
117+
118+
## GitHub Actions Workflows
119+
120+
### `deploy.yml`
121+
- **Trigger**: Push to `main`
122+
- **Steps**:
123+
1. Checkout deployment repo
124+
2. Checkout docs source repo
125+
3. Install dependencies
126+
4. Sync documentation
127+
5. Build VitePress site
128+
6. Deploy to GitHub Pages
129+
130+
### `sync-docs.yml`
131+
- **Trigger**: Manual or scheduled
132+
- **Purpose**: Keep docs in sync
133+
- **Steps**:
134+
1. Checkout both repos
135+
2. Sync documentation
136+
3. Commit and push if changes detected
137+
138+
## Benefits of This Architecture
139+
140+
### Separation of Concerns
141+
- **Source repo**: Focus on content
142+
- **Deployment repo**: Focus on presentation
143+
144+
### Independent Versioning
145+
- Documentation changes don't affect deployment setup
146+
- Deployment improvements don't clutter docs history
147+
148+
### Automated Workflow
149+
- No manual deployment steps
150+
- Always in sync
151+
- Fast iteration
152+
153+
### Contributor-Friendly
154+
- Contributors only need to edit markdown
155+
- No need to understand VitePress
156+
- Simple pull request workflow
157+
158+
## Maintenance
159+
160+
### Adding New Documentation
161+
1. Add `.md` file to `diffyne/docs`
162+
2. Sync to deployment repo (automatic or manual)
163+
3. Update VitePress sidebar config if needed
164+
165+
### Updating VitePress Config
166+
1. Edit `docs/.vitepress/config.js`
167+
2. Commit and push to `diffyne.github.io`
168+
3. Site rebuilds automatically
169+
170+
### Troubleshooting
171+
- Check GitHub Actions logs
172+
- Verify sync script output
173+
- Test locally with `npm run dev`
174+
175+
## Future Improvements
176+
177+
- [ ] Automated link checking
178+
- [ ] Preview deployments for PRs
179+
- [ ] Documentation analytics
180+
- [ ] Search improvements
181+
- [ ] Multi-language support
182+

0 commit comments

Comments
 (0)