Skip to main content

Documentation

The documentation is a Docusaurus site in apps/docs; pages live in apps/docs/docs/. This page covers where content goes, which parts are generated from code, the checks a change must pass and how the site is deployed.

Run it locally​

pnpm --filter @eudiplo/config-format build # the generators import backend code
pnpm --filter @eudiplo/docs run prebuild # generate docs/_generated/ (once, and after schema changes)
pnpm --filter @eudiplo/docs start # live reload on http://127.0.0.1:3003
CommandPurpose
pnpm --filter @eudiplo/docs buildRuns prebuild, then a production build. Broken links and anchors fail the build.
pnpm --filter @eudiplo/docs serveServes the last build on port 3003
pnpm --filter @eudiplo/docs lintmarkdownlint (apps/docs/.markdownlint.json); lint:fix fixes what it can
pnpm --filter @eudiplo/docs testSidebar orphan check and the schema and roles generator tests
pnpm --filter @eudiplo/docs typecheck:scriptsType-checks the generator scripts

The search widget reads ALGOLIA_APP_ID, ALGOLIA_SEARCH_API_KEY, ALGOLIA_INDEX_NAME and DOCSEARCH_AGENT_ID; local builds work without them.

The build also writes llms.txt (an index of all pages) and llms-full.txt (every page in one file) for coding assistants, following llmstxt.org. docusaurus-plugin-llms reads the Markdown sources, so content rendered by components such as SchemaReference is not included; link to the published page for those tables.

Where content goes​

The sidebar order is Start, Cookbooks, Issuance, Presentation, Trust, Operate, Reference, Concepts, Contributing, Upgrade, then the project pages.

FolderContentPage type
cookbooks/End-to-end recipes that end in a working resultCookbook
issuance/, presentation/, trust/One task per page for issuers, verifiers and trust setupHow-to
operate/Deploying and running EUDIPLO: Compose, Kubernetes, TLS, database, KMS, monitoringHow-to
reference/Exact facts: API, environment variables, CLI, payloads, field referencesReference
concepts/How EUDIPLO works; no configuration stepsConcept
contributing/Working on EUDIPLO itselfHow-to
upgrade/Upgrade procedure and one guide per major versionHow-to
troubleshooting.mdSymptoms shared by several pagesReference
showcase.md, brand.mdProject pages: who uses EUDIPLO, logo files and colorsReference

Page types:

  • Cookbook: title "Cookbook: …"; sections What you will build (one paragraph, optional diagram), Before you start (prerequisites, the recipe it starts from), numbered steps that each end with a Checkpoint, Troubleshooting (symptom → cause → fix), Next steps (2–4 links). Reuse the values of the issue-and-verify recipe where possible (membership-demo, membership, urn:example:membership:1, membership-check). Chapters 2 and 3 of that recipe are walked by apps/client/e2e/cookbook.spec.ts; change it together with their steps.
  • How-to: the goal in one sentence, prerequisites, steps, a minimal example, links to the reference.
  • Reference: tables and generated components, no tutorials.
  • Concept: explanation and diagrams, links to the how-tos.

Rules for every page:

  • One owner per topic. Every fact lives on one page; other pages link to it in one sentence. Before you write a table or payload, check whether a page already owns it.
  • Code is the truth. Check every field, endpoint, default and behavior against the code of the version you document.
  • Paths: management endpoints with the /api prefix (POST /api/issuer/offer), wallet-facing endpoints without it (see GLOBAL_PREFIX_EXCLUSIONS in apps/backend/src/main.helpers.ts).
  • Short. Lead with the task; at most three sentences of introduction; aim for under 250 lines and split a page that serves two tasks. No marketing, no textbook material, no "future work" or TODOs.
  • Use mermaid only where a flow really needs it, and give every code block a language (markdownlint MD040).
  • Every published page must be listed in apps/docs/sidebars.ts. Files and folders starting with _ are not published; use them for partials and generated content.
  • When you move or delete a page, add a client redirect in docusaurus.config.ts and point existing redirects at the final target (no chains).

Generated content​

Prefer a reference generated from code over a hand-written table. prebuild writes the generated files to docs/_generated/ (git-ignored, not published as pages).

ContentSource of truthGeneratorUse on a page
Environment variablesJoi schemas combined in apps/backend/src/platform/config/combined.schema.tsscripts/generate-config-docs.ts → _generated/config-model.json<ConfigTable group="…" /> (src/components/ConfigTable)
CLI command referenceThe commander program of apps/cliscripts/generate-cli-reference.ts → _generated/cli-reference.mdImported as an MDX partial in reference/cli.md
Request bodies and configuration fieldsZod schemas registered in scripts/schema-docs/registry.tsscripts/generate-schema-docs.ts → _generated/schemas/<SchemaReference name="…" mode="table" /> (field table) or mode="body" (annotated JSON sample)
Roles and the endpoints that accept themapps/backend/src/auth/roles/role.enum.ts (member comments are the descriptions) and the @Secured decorators of the controllersscripts/generate-roles-docs.ts → _generated/roles.json<RoleReference table="roles" /> or table="endpoints" (src/components/RoleReference)

To document a new Zod schema, add { name, schema } to registry.ts, run prebuild, import SchemaReference from @site/src/components/SchemaReference and place the component. Field descriptions come from the schema's .describe(…) texts, so improve the description in the backend schema instead of the page. An unknown name fails the build. Descriptions that are part of a published configuration file format can't change without a new format version (pnpm schemas:check-contract fails); correct those with the entry's descriptions overrides in registry.ts until the next format version. Text in backticks renders as inline code in the generated tables.

Generate other references that can be derived from code too, instead of writing a table by hand. The published JSON schemas for configuration files are a separate pipeline: Configuration schemas.

Checks​

CI runs on every pull request:

  • pnpm --filter @eudiplo/docs lint (markdownlint) in the Lint job,
  • pnpm --filter @eudiplo/docs test, typecheck:scripts and build in the Build Documentation job.

The build is configured with onBrokenLinks: 'throw' and onBrokenAnchors: 'throw', so a link to a missing page or heading fails it. The sidebar orphan check (scripts/check-sidebar-orphans.ts) fails when a page is missing from sidebars.ts or the sidebar references a page that does not exist.

Deployment and versions​

Both workflows deploy the documentation with .github/workflows/deploy-site.yml and then ask EUDIPLO/website to deploy eudiplo.dev to the same environment, built with the schemas of the same commit (production takes the CLI installer from the latest release). The dispatch uses a short-lived token of the org-owned GitHub App eudiplo-website-deploy (installed on EUDIPLO/website only, Contents: write), whose private key is the secret WEBSITE_APP_PRIVATE_KEY of the GitHub environment website-deploy; only main may deploy to that environment.

TriggerBuilt fromDeployed to
Push to main (CI job Deploy Preview Website & Documentation)mainCloudflare Pages project eudiplo-docs, branch preview
Release (Versioned Release workflow)The release commitCloudflare Pages project eudiplo-docs, branch production, served at docs.eudiplo.dev
Versioned Release with deploy_site_onlymain, only when no release is pendingSame as a release

So docs.eudiplo.dev describes the latest release, and the preview describes main. A docs: commit triggers no release, so documentation-only changes reach production by running Versioned Release with deploy_site_only. It refuses to deploy while a release is pending, because main could then document unreleased behavior; release first in that case.

The website publishes eudiplo.dev/.well-known/security.txt (RFC 9116) from security.txt in EUDIPLO/website. Its build adds the Expires field, 360 days after the build date, and fails when a Contact value is missing from SECURITY.md in this repository. Production checks against SECURITY.md of the latest release, so a new contact can go into security.txt only once a release has shipped it. The website repository redeploys production once a month, so Expires does not lapse. docs.eudiplo.dev/.well-known/security.txt redirects to that file.

The site has no per-version copies (versioned_docs/ does not exist). Documentation of an older release is the apps/docs/docs folder at its git tag, which is how the upgrade overview links to old upgrade guides.

Document the behavior of main. A change that breaks existing setups also needs an entry in the upgrade guide of the next major (see Releases).