docmd-docs

name	docmd-docs
description	Use whenever working in docs-site/, adding or editing public documentation pages, changing docmd navigation, plugins, semantic search, branding, Cloudflare Pages deployment, or keeping docs synchronized with user-facing package features.

docmd Docs Skill

Use this skill for the public documentation site in docs-site/.

Layout

• docmd.config.json is the source for metadata, URL, navigation, theme, footer, and plugins.
• docs/ contains every Markdown page. docs/index.md is the root route /.
• Routes mirror the file tree: docs/guides/foo.md becomes /guides/foo.
• navigation[] is the only sidebar source. Every new page must be added there.
• assets/custom.css owns brand overrides.
• .docmd-search/config.json is committed to avoid the interactive semantic-search wizard.

Commands

Run from docs-site/:

npm run dev
npm run check
npm run build

npm run check rejects raw JSX/MDX-style component tags in Markdown. npm run build must pass before closing documentation work.

Markdown Syntax

Use Markdown plus docmd containers only. Do not use MDX, JSX, or raw component tags.

Need	Syntax
Callout	::: callout info ... :::; types: info, tip, warning, danger, success
Tabs	::: tabs, then == tab "Label", close with :::
Steps	::: steps, numbered list, body indented three spaces, close with :::
Collapsible	::: collapsible "Title" ... :::; use open prefix for default-open
Cards	::: grids > ::: grid > ::: card "Title" icon:lucide-name > body > Markdown link > close each container
Diagrams	fenced mermaid blocks
Math	KaTeX inline $...$ and block $$...$$

Icons are Lucide icon names in kebab-case.

Plugins

Keep these plugins active unless a build-proven incompatibility is documented: search, git, seo, sitemap, mermaid, math, llms, analytics disabled. url must be set because sitemap, SEO, and llms need absolute context.

Semantic Search

Semantic search uses docmd-search at build time. Dependencies are docmd-search, @huggingface/transformers, and onnxruntime-node. The browser receives a static client-side index, not a server or model runtime.

The file .docmd-search/config.json must remain committed with the pinned model:

{ "model": "Xenova/all-MiniLM-L6-v2", "chunkSize": 512, "chunkOverlap": 64, "incremental": true, "topK": 10 }

.gitignore must ignore generated search cache while keeping this config.

Footer And Branding

Footer content must credit Lorenzo Padovani, Padosoft, GitHub, and Apache-2.0. Brand color is #0d9488 in assets/custom.css through docmd primary/link variables.

Cloudflare Pages

Primary deploy path is Cloudflare Pages Git integration, no API key in the repo:

Field	Value
Production branch	main
Root directory	docs-site
Build command	npm run build
Build output directory	_site
Node	.node-version pinned to 20

Fallback only if Cloudflare build breaks on native ONNX dependencies: a manual workflow_dispatch GitHub Actions workflow may run wrangler pages deploy _site --project-name=laravel-evidence-risk-review with Cloudflare secrets.

Page Standard

Deep pages should include motivation, theory with formulas when useful, Mermaid design diagram, data model or contract, ADR collapsibles, a worked example, and gotchas in a warning callout.

Gotchas

• docs/index.md is mandatory or _site/index.html is missing.
• Do not use paired ::: button; use a Markdown link inside cards.
• Steps need careful indentation: body lines three spaces under the numbered item.
• KaTeX must not render $variables inside code fences; inspect output when adding shell-heavy pages.
• Keep the lockfile cross-platform and do not commit generated _site/, node_modules/, or search cache batches.