Documentation
Contribute to improving the Pocket ID website or documentation
This guide explains how to add or edit documentation (SvelteKit + Velite + MDSX).
1. Where docs live
All markdown pages are under docs/. Velite (see velite.config.js) defines collections:
introduction.mdsetup/**/*.mdconfiguration/**/*.mdguides/**/*.mdadvanced/**/*.mdhelping-out/**/*.mdtroubleshooting/**/*.mdapi.mdclient-examples.md(overview)client-examples/**/*.md
Each file is parsed and exported via $docs/index.js. The dynamic loader: getDoc.
URL = /docs/ + file path without .md (e.g. setup/installation.md → /docs/setup/installation).
2. Adding a new page
- Pick the correct folder that matches a collection pattern (e.g.
guides/). - Create
docs/<section>/<slug>.md. - Add frontmatter:
- Run
pnpm dev– Velite auto-detects the file. No manual array updates needed.
3. Frontmatter & generated metadata
Velite schema (see config):
| Field | Source | Notes |
|---|---|---|
| title | frontmatter | required |
| description | frontmatter | required |
| path | derived | relative path without .md |
| slug | derived | joins segments (path) |
| section | derived | first segment |
| segments | derived | path split on / |
| order | frontmatter | optional numeric sort hint |
| published | frontmatter | default true |
| toc | generated | auto table of contents |
toc is injected automatically (used for page outline).
4. Navigation
Sidebar & neighbor links are generated from the Velite collections (see docs.ts). Ordering inside a section:
order(ascending) if presenttitlealphabetical
Client examples are excluded from the sidebar but have their own overview page and grid.
External static links (Demo / Discord) are appended as a Resources group (see same config file).
5. Hiding a page (draft)
Set published: false. The file remains buildable but can be filtered from listings (logic may hide unpublished).
6. Callouts (Admonitions)
Supported: NOTE, TIP, IMPORTANT, WARNING, CAUTION.
7. Code blocks
```bash
docker compose up -d
```8. Images
Place under static/img/...:
Always provide alt.
9. Tables
GitHub‑Flavored Markdown is enabled; just write pipe tables.
10. Search / TOC
TOC is auto; search features (where implemented) index headings & content—no manual config.
11. Common issues
| Issue | Fix |
|---|---|
| 404 | File path mismatch; confirm filename and collection pattern |
| Missing title | Add title frontmatter |
| Wrong sidebar order | Add / adjust order |
| TOC empty | Add at least one level-2 ## Heading |
| Hidden page | Remove or set published: true |
12. Checklist for a new page
- File created in correct folder
- Frontmatter with title & description
- Optional
orderset (if ordering matters) - Page builds (
pnpm dev) - Headings structured (
##,###) for TOC - Images (if any) in
static/img/...with alt text
13. Submitting changes
- Branch & make your changes.
- Commit using Conventional Commits (
doc: update guides). - Open PR.
The preview workflow will build docs automatically.
Happy documenting!