Markdown documentation for your existing Angular and Analog.js app — your header, footer, routes, theme and components stay yours.
SSR/SSG, sidebar, table of contents, optional static search and live Angular components inside Markdown.
📦 npm package · 📖 Integration guide · 📝 Changelog · 🧭 Specifications · 🤝 Contributing
What is Doqs?
Doqs (@doqs/analog) adds a Markdown-driven documentation region to an Angular and Analog.js application you already have. It owns documentation routing, navigation, the table of contents, the index, code blocks and optional full-text search, and nothing else: no global html/body styles, no router takeover, no theme of its own. Your product keeps its shell.
- Native Angular and Analog.js. Routes come from
doqRoutes(), content from Analog's own content files, prerendering from doqPrerenderRoutes().
- Markdown-driven.
title, group, order and slug in frontmatter, nested folders, custom public URLs.
- SSR and SSG. Every page ships as static HTML and hydrates cleanly.
- Angular components inside Markdown. Register your own standalone components once, then place them between paragraphs with a one-line
::demo[id] directive. Not MDX: no JavaScript in Markdown and no template compilation.
- Interactive playgrounds. Register a component with a few typed controls (
boolean, string, number, select) and place it with ::playground[id]: readers change its inputs, watch selected outputs, resize the preview, expand it, reset it and copy usage code. Server-rendered, hydrated, keyboard-operable.
- Rich Markdown, built in (0.4).
> [!NOTE] callouts, accessible :::tabs and code groups, :::steps guides and titled code blocks, with no component to write. They are server-rendered, searchable and themed by the same --host-docs-* tokens. See Rich Markdown authoring.
- API reference from source (0.5).
doq-api generate reads your library's public TypeScript API (components, directives, signal inputs, outputs, models, JSDoc, stability tags) and writes ordinary Markdown pages; doq-api check fails CI when they are stale. Build-time only, with your own TypeScript. See API reference from source.
- Content authoring (0.10).
doq content generate resolves ::source{file="…" region="…"} (code read from your real files), ::include{file="…"} (shared Markdown fragments) and [[api:Name]] (links to the generated API reference, version-aware) into ordinary Markdown before Analog renders it. Build-time and Node-only, opt-in, with ownership of generated files and located diagnostics. See Content authoring.
- Adoption in existing sites (0.11).
landmark decides who owns the page's main, unmatched: 'continue' lets host pages keep their URLs below the Doqs prefix, and @doqs/analog/config is a configuration-only entry point. Proven by building the real Angular Movement and Volt UI sites with Doqs pages at their original URLs (parity, findings).
- Versioned documentation (0.6). Keep older releases readable: archived snapshots at stable
/v/<id> URLs, an accessible version selector, context-preserving switching, per-version prerendering and Pagefind filtering. Optional; without versioning nothing changes. See Versioned documentation.
- Static search. Optional Pagefind index built from your prerendered output. No backend, off by default.
- Host-owned look. Restyle with
--host-docs-* CSS tokens and add your own components through composition slots.
Quick start
pnpm add @doqs/analog @analogjs/content @analogjs/router prismjs
pnpm exec doq init # scaffolds src/doq.paths.ts and two Markdown pages; never overwrites; --dry-run previews
pnpm exec doq doctor # reports what is connected and what is missing
doq init prints the exact edits that remain for your vite.config.ts, Angular providers and global stylesheet. They are the same four connections described in the Analog configuration guide; the rest of the documentation (installation, Markdown, search, versions, API reference, deployment, troubleshooting) is in apps/site/src/content/docs, which the official site renders with Doqs itself.
Two ways to use it
Both are real applications in this repository, built and tested in CI.
以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗
