Skip to content

Commit 69ca536

Browse files
shouzeshouze
authored
Merge pull request #34 from fulll/docs/25-init-vitepress
docs: Initialize VitePress skeleton (#25)
2 parents 37afdce + 0377a94 commit 69ca536

16 files changed

Lines changed: 1019 additions & 3 deletions

‎.github/instructions/bug-fixing.instructions.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,8 @@ Add a one-line comment above the fix if the root cause is non-obvious:
7575

7676
- Branch name: `fix/<short-description>` (e.g. `fix/exclude-repos-with-org-prefix`).
7777
- Commit message: imperative mood, e.g. `Fix --exclude-repositories ignoring org-prefixed names`.
78+
- **All commits must be signed** (GPG or SSH). Configure once with `git config --global commit.gpgsign true`.
79+
Commits pushed via the GitHub API (Copilot Coding Agent, MCP tools) are automatically Verified by GitHub.
7880
- PR description:
7981
- Root cause explanation.
8082
- Steps to reproduce (before the fix).

‎.github/instructions/documentation.instructions.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
applyTo: "docs/**"
3+
---
4+
5+
# Documentation — instructions for Copilot coding agent
6+
7+
Follow these conventions when writing or editing pages in the `docs/` directory.
8+
9+
## 1. Tool & rendering pipeline
10+
11+
- **Generator**: [VitePress](https://vitepress.dev/) — pure Markdown/MDX, no Vue components needed.
12+
- **Build**: `bun run docs:build` → static output in `docs/.vitepress/dist/`
13+
- **Dev server**: `bun run docs:dev` → `http://localhost:5173/github-code-search/`
14+
- **Deploy**: GitHub Actions workflow `.github/workflows/docs.yml` → GitHub Pages.
15+
16+
## 2. Brand guidelines
17+
18+
### Typography
19+
20+
| Role | Font | Usage |
21+
| ------------------------------ | ------------------------------------------- | ---------------------------- |
22+
| Primary (headings, short text) | **Poppins** (Aestetico Informal substitute) | Titles, taglines, callouts |
23+
| Accompanying (body text) | **Poppins** | Paragraphs, tables, lists |
24+
| Monospace | VitePress default (`--vp-font-family-mono`) | All code blocks |
25+
| Bureautic fallback | **Arial** | Email / Office contexts only |
26+
27+
Poppins is loaded from Google Fonts in `docs/.vitepress/theme/custom.css`. Do not add additional font imports.
28+
29+
### Colour palette
30+
31+
| Name | Hex | Role |
32+
| ---------- | --------- | ------------------------------------------------------------- |
33+
| Violet | `#9933FF` | Primary — links, buttons, accents (9.1:1 on white ✓ WCAG AAA) |
34+
| Yellow | `#FFCC33` | Highlight / soft background tints |
35+
| Dark blue | `#0000CC` | Secondary / hover state |
36+
| Light blue | `#66CCFF` | Decorative only — **never for text** (insufficient contrast) |
37+
| Green | `#CCFF33` | Decorative only |
38+
| Orange | `#FF9933` | Decorative / warning callouts |
39+
40+
Only override CSS variables in `docs/.vitepress/theme/custom.css`. Do not hard-code colour values inside Markdown.
41+
42+
### Dark / light mode
43+
44+
`appearance: 'force-auto'` in the VitePress config means the site follows `prefers-color-scheme` by default; the user can toggle manually. All colour tokens have dark-mode variants defined in `custom.css`. Never use `@media (prefers-color-scheme)` directly — rely on the `.dark` class selector that VitePress manages.
45+
46+
## 3. File structure & naming
47+
48+
```
49+
docs/
50+
├── index.md # Landing page (layout: home)
51+
├── getting-started/ # Onboarding section
52+
├── usage/ # Use-case-driven guides
53+
├── reference/ # Reference tables (CLI, shortcuts, API, env)
54+
└── architecture/ # C4 diagrams (L1 → L3 in Mermaid)
55+
```
56+
57+
- Use **kebab-case** for file names: `team-grouping.md`, not `teamGrouping.md`.
58+
- Every section must have an `index.md` that serves as the landing page for that section.
59+
- All pages must have a `# Title` as the first heading — VitePress uses it for the sidebar and `<title>`.
60+
61+
## 4. Writing style
62+
63+
- Write in **English**.
64+
- Lead each page with a one-sentence description of what the feature does and **when to use it**.
65+
- Prefer **use-case-driven content**: show a realistic CLI example first, explain options after.
66+
- Every code block must declare its language: ` ```bash `, ` ```typescript `, ` ```json `, etc.
67+
- Use admonitions for important caveats:
68+
```markdown
69+
::: warning GitHub API limit
70+
Code search is capped at 1 000 results. See [GitHub API limits](/reference/github-api-limits).
71+
:::
72+
```
73+
- Cross-link liberally using root-relative paths: `[GitHub API limits](/reference/github-api-limits)`.
74+
75+
## 5. Mermaid / C4 diagrams
76+
77+
- Use `vitepress-plugin-mermaid` — wrap diagrams in ` ```mermaid ` fenced blocks.
78+
- C4 diagrams use `C4Context`, `C4Container`, `C4Component` diagram types.
79+
- Include a prose introduction **before** every diagram explaining what level it represents.
80+
- Keep diagrams self-contained: label every node and every arrow.
81+
- Do not add inline CSS to Mermaid diagrams — the plugin handles dark/light theming automatically via `mermaid.theme: 'default'` in the config.
82+
83+
## 6. Versioning
84+
85+
- `docs/public/versions.json` tracks published major versions.
86+
- Format: `[{ "text": "v1 (latest)", "link": "/" }]`
87+
- A new entry is appended automatically by CI when a `vX.0.0` tag is pushed.
88+
- Do **not** manually edit `versions.json` outside of the release workflow.
89+
- When updating docs for a new major version, update the nav `text` field in `docs/.vitepress/config.mts`.
90+
91+
## 7. Validation checklist
92+
93+
Before opening a PR for any docs change:
94+
95+
```bash
96+
bun run docs:build # must complete without errors
97+
bun run format:check # oxfmt — no formatting diff
98+
```
99+
100+
- All internal links must resolve (VitePress reports dead links on build).
101+
- No new `bun run knip` violations (docs/\*\* is excluded but `package.json` changes are not).

‎.github/instructions/implement-feature.instructions.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,4 +66,6 @@ bun run build.ts # binary compiles without errors
6666

6767
- Branch name: `feat/<short-description>` (e.g. `feat/json-output-type`).
6868
- Commit message: imperative mood, e.g. `Add --output-type flag for JSON format`.
69+
- **All commits must be signed** (GPG or SSH). Configure once with `git config --global commit.gpgsign true`.
70+
Commits pushed via the GitHub API (Copilot Coding Agent, MCP tools) are automatically Verified by GitHub.
6971
- PR description: motivation, what changed, how to test manually.

‎.github/instructions/refactoring.instructions.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,4 +75,6 @@ bun run build.ts # binary compiles without errors
7575

7676
- Branch name: `refactor/<short-description>` (e.g. `refactor/extract-filter-module`).
7777
- Commit message: imperative mood, e.g. `Extract FilterStats helpers into render/filter.ts`.
78+
- **All commits must be signed** (GPG or SSH). Configure once with `git config --global commit.gpgsign true`.
79+
Commits pushed via the GitHub API (Copilot Coding Agent, MCP tools) are automatically Verified by GitHub.
7880
- PR description: what was restructured, why, and a note confirming no behaviour change.

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,7 @@ dist/
33
coverage/
44
.env
55
*.local
6+
7+
# VitePress
8+
docs/.vitepress/cache
9+
docs/.vitepress/dist

‎AGENTS.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,45 @@ src/
112112
- When creating a new module that contains pure functions, create a companion `<module>.test.ts`.
113113
- Tests must be self-contained: no network calls, no filesystem side effects.
114114

115+
## Git conventions
116+
117+
### Signed commits (required)
118+
119+
All commits to this repository **must be cryptographically signed**. Unsigned commits will be rejected by branch protection rules.
120+
121+
**For local commits** — configure GPG or SSH signing once:
122+
123+
```bash
124+
# Recommended: sign every commit automatically
125+
git config --global commit.gpgsign true
126+
127+
# Or sign a single commit manually
128+
git commit -S -m "feat: my change"
129+
```
130+
131+
Verify your setup:
132+
133+
```bash
134+
git log --show-signature -1 # should show "Good signature from …"
135+
```
136+
137+
**For agent-created commits** — commits pushed via the GitHub REST API (e.g. by Copilot Coding Agent or any MCP tool) are automatically marked **Verified** by GitHub using its own key. No extra configuration is required for these.
138+
139+
### Branch & commit conventions
140+
141+
| Branch type | Pattern | Example |
142+
| ------------- | ------------------------------ | ----------------------------------- |
143+
| Feature | `feat/<short-description>` | `feat/json-output-type` |
144+
| Bug fix | `fix/<short-description>` | `fix/exclude-repos-with-org-prefix` |
145+
| Refactoring | `refactor/<short-description>` | `refactor/extract-filter-module` |
146+
| Documentation | `docs/<short-description>` | `docs/25-init-vitepress` |
147+
148+
Commit messages use **imperative mood**: `Add …`, `Fix …`, `Extract …`, not `Added` or `Fixing`.
149+
150+
For epics spanning multiple PRs, create a long-lived **feature branch** (`feat/<epic-name>`) and merge each sub-issue PR into it. Open a final PR from the feature branch into `main` when the epic is complete.
151+
152+
---
153+
115154
## Development notes
116155

117156
- **TypeScript throughout** — no `.js` files in `src/`.

0 commit comments

Comments
 (0)