Skip to content

Commit e738356

Browse files
vib-toolsvib-tools
committed
docs: bootstrap YGIT public documentation platform
0 parents  commit e738356

106 files changed

Lines changed: 2544 additions & 0 deletions

File tree

Some content is hidden

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

‎.editorconfig‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
root = true
2+
3+
[*]
4+
charset = utf-8
5+
end_of_line = lf
6+
insert_final_newline = true
7+
indent_style = space
8+
indent_size = 2
9+
trim_trailing_whitespace = true
10+
11+
[*.md]
12+
trim_trailing_whitespace = false

‎.env.example‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Canonical documentation site URL.
2+
SITE_URL=https://ygit.dev
3+
BASE_URL=/
4+
5+
# Optional Algolia DocSearch integration.
6+
ALGOLIA_APP_ID=
7+
ALGOLIA_API_KEY=
8+
ALGOLIA_INDEX_NAME=

‎.github/ISSUE_TEMPLATE/docs-bug.yml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
name: Documentation problem
2+
description: Report incorrect, missing, or unclear public documentation.
3+
title: "docs: "
4+
labels: [documentation]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: Do not include tokens, private logs, personal data, or security vulnerability details.
9+
- type: input
10+
id: page
11+
attributes:
12+
label: Documentation page
13+
placeholder: /docs/...
14+
validations:
15+
required: true
16+
- type: textarea
17+
id: problem
18+
attributes:
19+
label: What is incorrect or unclear?
20+
validations:
21+
required: true
22+
- type: textarea
23+
id: expected
24+
attributes:
25+
label: Expected documentation
26+
validations:
27+
required: true

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
## Summary
2+
3+
Describe the public documentation change.
4+
5+
## Public content review
6+
7+
- [ ] Product behavior was verified against the current release.
8+
- [ ] No private platform source or internal engineering document was copied directly.
9+
- [ ] No secrets, private URLs, account identifiers, exact internal commit IDs, or CI run IDs are present.
10+
- [ ] Screenshots are sanitized and include descriptive alt text.
11+
- [ ] Preview or planned functionality is labeled clearly.
12+
- [ ] `npm run validate` passes.

‎.github/dependabot.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
version: 2
2+
updates:
3+
- package-ecosystem: npm
4+
directory: /
5+
schedule:
6+
interval: weekly
7+
open-pull-requests-limit: 5
8+
- package-ecosystem: github-actions
9+
directory: /
10+
schedule:
11+
interval: monthly

‎.github/workflows/ci.yml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
name: Documentation CI
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches: [main]
7+
8+
permissions:
9+
contents: read
10+
11+
jobs:
12+
validate:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- name: Checkout
16+
uses: actions/checkout@v4
17+
- name: Setup Node.js
18+
uses: actions/setup-node@v4
19+
with:
20+
node-version: 22
21+
- name: Install dependencies
22+
run: npm install
23+
- name: Validate public content and build
24+
run: npm run validate

‎.gitignore‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
node_modules/
2+
build/
3+
.docusaurus/
4+
.cache-loader/
5+
.env
6+
.env.*
7+
!.env.example
8+
.DS_Store
9+
npm-debug.log*
10+
yarn-debug.log*
11+
yarn-error.log*
12+
pnpm-debug.log*

‎.node-version‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
22

‎.nvmrc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
22

‎ARCHITECTURE.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# YGIT Public Documentation Architecture
2+
3+
**Version:** 1.0
4+
**Status:** Ready to Use
5+
**Repository:** `vibtools/ygit-platform`
6+
**Default public domain:** `ygit.dev`
7+
**Framework:** Docusaurus 3.10.2
8+
9+
## 1. Purpose
10+
11+
This repository is the complete public-information layer for YGIT. It is not a copy of the private platform codebase and it is not an internal engineering archive.
12+
13+
It has four responsibilities:
14+
15+
1. Explain YGIT to users and search engines.
16+
2. Provide complete user guidance.
17+
3. Publish stable CLI, SDK, and API contracts.
18+
4. Build a static documentation website deployable to Cloudflare Pages or any static host.
19+
20+
## 2. Content architecture
21+
22+
```text
23+
YGIT Public Documentation Platform
24+
├── Product landing pages
25+
├── User documentation
26+
├── CLI documentation
27+
├── SDK documentation
28+
├── API documentation
29+
└── Public updates and release notes
30+
```
31+
32+
Each documentation family uses an independent Docusaurus docs plugin instance.
33+
34+
| Surface | Source | Public route | Sidebar | Version lifecycle |
35+
|---|---|---|---|---|
36+
| User Docs | `docs/` | `/docs/` | `sidebars.ts` | Product/user documentation |
37+
| CLI | `cli/` | `/cli/` | `sidebars.cli.ts` | CLI releases |
38+
| SDK | `sdk/` | `/sdk/` | `sidebars.sdk.ts` | SDK package releases |
39+
| API | `api/` | `/api/` | `sidebars.api.ts` | Public API contract |
40+
| Updates | `updates/` | `/updates/` | Blog index | Announcements and changelog |
41+
42+
This prevents unrelated version histories from becoming coupled. A CLI release does not require versioning the user guide, and an SDK release does not require a second documentation site.
43+
44+
## 3. Repository structure
45+
46+
```text
47+
ygit-platform/
48+
├── .github/
49+
│ ├── workflows/ci.yml
50+
│ ├── ISSUE_TEMPLATE/
51+
│ └── PULL_REQUEST_TEMPLATE.md
52+
├── api/
53+
├── cli/
54+
├── docs/
55+
├── sdk/
56+
├── updates/
57+
├── scripts/
58+
│ └── validate-public-content.mjs
59+
├── src/
60+
│ ├── css/custom.css
61+
│ └── pages/
62+
├── static/
63+
│ ├── img/
64+
│ ├── _headers
65+
│ └── robots.txt
66+
├── docusaurus.config.ts
67+
├── sidebars.ts
68+
├── sidebars.cli.ts
69+
├── sidebars.sdk.ts
70+
├── sidebars.api.ts
71+
├── CONTENT_POLICY.md
72+
├── CONTRIBUTING.md
73+
├── DEPLOYMENT.md
74+
└── README.md
75+
```
76+
77+
## 4. Product-boundary rule
78+
79+
YGIT remains a deployment automation platform. Public documentation must not redefine it as a website builder, hosting company, CMS, or general-purpose control panel.
80+
81+
The public flow is:
82+
83+
```text
84+
Import Repository
85+
→ Analyze Repository
86+
→ Connect Accounts
87+
→ Review Configuration
88+
→ Deploy
89+
→ Website Live
90+
```
91+
92+
Public documentation should reinforce user ownership of the repository, Cloudflare account, domain, code, and infrastructure.
93+
94+
## 5. Content lifecycle
95+
96+
```text
97+
Internal product evidence
98+
→ Public-content rewrite
99+
→ Technical verification
100+
→ Security/privacy review
101+
→ SEO and accessibility review
102+
→ Pull request
103+
→ CI validation
104+
→ Preview deployment
105+
→ Merge
106+
→ Production deployment
107+
```
108+
109+
Internal documents are inputs, not publishable artifacts. They must be rewritten for the intended audience.
110+
111+
## 6. Future feature expansion
112+
113+
A new public feature normally requires only content changes:
114+
115+
```text
116+
docs/<feature>/
117+
├── _category_.json
118+
├── overview.md
119+
├── setup.md
120+
├── usage.md
121+
├── limitations.md
122+
└── troubleshooting.md
123+
```
124+
125+
A new framework plugin or top-level documentation surface is justified only when the feature has an independent release/version lifecycle comparable to CLI, SDK, or API.
126+
127+
## 7. Versioning policy
128+
129+
Do not version documentation prematurely. Docusaurus version snapshots increase maintenance and build cost. Enable versioning when a stable public contract must remain available after breaking changes.
130+
131+
```bash
132+
npm run version:docs -- 1.0.0
133+
npm run version:cli -- 1.0.0
134+
npm run version:sdk -- 1.0.0
135+
npm run version:api -- 1.0.0
136+
```
137+
138+
Version only the affected surface.
139+
140+
## 8. SEO architecture
141+
142+
- One canonical domain through `SITE_URL`
143+
- Human-readable routes
144+
- Unique title and description front matter on every content page
145+
- Automatic sitemap generation from the classic preset
146+
- `robots.txt` and social-preview image
147+
- SoftwareApplication structured data
148+
- Semantic headings and descriptive link text
149+
- Separate landing pages for user, CLI, SDK, and API search intent
150+
- Public updates feed for fresh crawlable content
151+
152+
See `SEO_GUIDE.md`.
153+
154+
## 9. Security boundary
155+
156+
The public-content validator blocks common credential values, private key material, exact internal commit hashes, and references to the private platform repository. CI must run it before every production build.
157+
158+
The validator complements review; it does not replace it. Screenshots, diagrams, logs, and copied examples require manual privacy review.
159+
160+
## 10. Deployment architecture
161+
162+
Docusaurus emits static files to `build/`. The repository has no hosting-provider business logic.
163+
164+
```text
165+
GitHub commit
166+
→ CI validation
167+
→ Docusaurus build
168+
→ build/
169+
→ Cloudflare Pages or another static host
170+
```
171+
172+
For Cloudflare Pages:
173+
174+
```text
175+
Build command: npm run build
176+
Output directory: build
177+
Production branch: main
178+
Node.js: 22
179+
```
180+
181+
## 11. Architecture gate
182+
183+
A structural change requires documentation when it changes one of these:
184+
185+
- Public route families
186+
- Documentation plugin instances
187+
- Versioning strategy
188+
- Search provider
189+
- Content security policy
190+
- Deployment output contract
191+
- Localization architecture
192+
193+
Normal documentation additions do not require an architecture revision.

0 commit comments

Comments
 (0)