piighost-docs

The documentation site of piighost, docs.piighost.dev: the technical guide and the business wiki in one place, in the piighost identity.

The site holds no copy of the documentation. It reads a checkout of the piighost repository at build time:

The pages stay written in the Zensical dialect (admonitions, tabs, cards, { .pii } chips): frontend/src/lib/server/content/preprocess.ts turns it into standard directives, and the components come from @piighost/ui.

What the build checks

The build fails rather than ship a broken page:

• a link to a page or an anchor that does not exist,

• an identifier (DPO-9, BR-MSG-05, AT-OPS-2-1, ECART-09) that the wiki does not define, or that it defines twice,

• a missing image.

Every identifier is a link with a hover card. Its card, /fr/ids/<ID>/ and /en/ids/<ID>/, is the stable URL to cite from code, issues and the chatbot: /ids/<ID>/ leads to the reader's language. A rule's card lists the code the wiki locates and the tests the code graph reaches, directly or through its module.

Related MCP server: docusaurus-plugin-mcp

Develop

just install
PIIGHOST_CONTENT=~/piighost-besoins just content-check   # read the content, report problems
PIIGHOST_CONTENT=~/piighost-besoins just build           # prerender into frontend/build, then Pagefind

Diagrams are rendered once per source with mermaid-cli and the local Chromium (CHROMIUM_PATH), cached in frontend/static/diagrams/.

Deploy

One Dockerfile builds the site and its two MCP servers from one build of the content: it clones piighost at PIIGHOST_REF, builds the code graph with graphify, renders the diagrams with Chromium, prerenders the pages and indexes them with Pagefind. @piighost/ui is not published: its packed build sits in frontend/vendor/, refreshed with pnpm pack in piighost-ui.

compose.prod.yml is the Coolify stack. Its build variables are PIIGHOST_REF and PUBLIC_CHAT_URL, the chatbot's server, baked into the pages and their content policy. Only web gets a domain.

To run the same stack from a local piighost commit:

git -C ../piighost archive HEAD | tar -x -C /tmp/piighost-content
docker compose up --build        # http://localhost:8080

The Deploy workflow checks the content of piighost's master, then calls the Coolify webhook, on a push here. piighost's own Documentation workflow calls the same webhook when docs/ or openwiki/ change on master, and the image build stops on a broken page. Both repositories hold COOLIFY_DEPLOY_WEBHOOK and COOLIFY_TOKEN.

Each page carries its own content policy as a meta tag, with the hash of its inline bootstrap script, and nginx sends the rest of the policy as a header. An unknown path gets the bilingual 404 page.

Not done yet

• The backend (backend/, Dockerfile.api, from template-litestar-svelte) is not part of the stack any more: the MCP servers live in mcp/ and graphify, the chatbot in piighost-docs-chainlit. It is to be removed.