Contributing to documentation

Repository norms

Follow the root Contributing guide: Conventional Commits with scope = top-level folder (for docs-only changes, docs or ci is appropriate).

Local documentation development

npm install
npm start

With the default config, the dev server uses baseUrl: '/zkID/'. Open:

http://localhost:3000/zkID/

(not the site root — you will get a 404 at http://localhost:3000/).

Build production output (runs TypeDoc first):

npm run build
npm run serve

Then open http://localhost:3000/zkID/ again to preview the production bundle.

GitHub Pages preview (zulu0echo/zkID)

After you enable Settings → Pages → GitHub Actions and push to main, the published site is:

https://zulu0echo.github.io/zkID/

Building with another GitHub owner

To point edit links and url at a different org while testing locally (for example upstream):

ZKID_DOCS_GITHUB_OWNER=privacy-ethereum npm start

On GitHub Actions, GITHUB_REPOSITORY_OWNER is set automatically, so builds use the owner of the repository running the workflow.

Editing

Documentation lives in docs/; the landing page is src/pages/index.tsx. Use repo-verified snippets—cite sources in HTML comments above code blocks.

Publishing to GitHub Pages

1. In the GitHub repo: Settings → Pages → Build and deployment.
2. Set Source to GitHub Actions (not “Deploy from a branch”).
3. Merge to main; the workflow .github/workflows/docs.yml builds and uploads the build/ artifact, then Deploy to GitHub Pages runs.
4. First run: approve the github-pages environment if your org requires deployment reviews.

The site uses baseUrl: '/zkID/' (see docusaurus.config.js). If you rename the repository, change projectName / baseUrl there, and update any hard-coded /zkID/ examples in this doc.

Algolia DocSearch (optional)

DocSearch is wired via environment variables at build time. If all three are set, docusaurus.config.js enables themeConfig.algolia:

Variable	Example source
ALGOLIA_APP_ID	DocSearch application
ALGOLIA_SEARCH_API_KEY	Search-only API key (safe for baked builds)
ALGOLIA_INDEX_NAME	Crawler index name

GitHub Actions: add the same names as repository secrets; the docs workflow passes them into npm run build.

Local: ALGOLIA_APP_ID=… ALGOLIA_SEARCH_API_KEY=… ALGOLIA_INDEX_NAME=… npm run build.

Apply for the programme: Algolia DocSearch.