Documentation that belongs in your app.

What Doqs 0.5 does

• Angular components inside Markdown

  New in 0.3

  Register your own standalone components once, then place them between paragraphs with a one-line ::demo[id] directive. Interactive, server-rendered and hydrated.

  ## Try it
  
  ::demo[enter-animation]

• Native Angular and Analog.js

  Routes come from doqRoutes() and content from Analog’s own content files. Your router and providers stay yours.

• Rich Markdown pages

  Frontmatter, nested folders and custom slugs, plus built-in callouts, accessible tabs, step guides and titled code, all in plain Markdown.

• SSR and SSG

  doqPrerenderRoutes() feeds Analog’s prerenderer, so every page ships as static HTML and hydrates cleanly.

• Sidebar and table of contents

  Grouped navigation, an “On this page” index, previous and next links and a mobile drawer.

• Pagefind full-text search

  Optional and static: an index built from your prerendered output. No backend, off by default.

• Host-owned themes and layout

  Restyle with --host-docs-* CSS tokens. Doqs sets no global html or body styles.

• API reference from source

  doq-api reads your library’s public TypeScript API, with signal inputs, outputs, models and JSDoc, and writes ordinary Markdown pages. A check command fails CI when they are stale.

• Composition slots

  Add your own standalone components after the docs index intro or after every document.

Getting started

Doqs plugs into an Analog app. Analog keeps its own configuration; Doqs adds its own. The two are separate on purpose.

// shared by vite.config.ts, so no Angular components here
export const doqPaths = { contentDirectory: 'docs', basePath: '/docs' } as const;

// Analog configuration: prerender routes
import { doqPrerenderRoutes } from '@doqs/analog';
import { doqPaths } from './src/doq.paths';

analog({
  ssr: true,
  static: true,
  content: { highlighter: 'prism' },
  prerender: { routes: async () => ['/', ...doqPrerenderRoutes(doqPaths)] },
});

// Doqs configuration next to Analog's providers
import { provideContent, withMarkdownRenderer } from '@analogjs/content';
import { provideFileRouter, withExtraRoutes } from '@analogjs/router';
import { defineDoqConfig, doqRoutes, provideDoq } from '@doqs/analog';
import { doqPaths } from '../doq.paths';

const doqConfig = defineDoqConfig({ ...doqPaths, sidebar: 'left', showTableOfContents: true });

export const appConfig: ApplicationConfig = {
  providers: [
    provideFileRouter(withExtraRoutes(doqRoutes(doqConfig))),
    provideContent(withMarkdownRenderer()),
    provideDoq(doqConfig),
  ],
};

// optional: reference pages generated from your public TypeScript API
"scripts": {
  "api": "doq-api generate --entry src/public-api.ts",
  "api:check": "doq-api check --entry src/public-api.ts"
}

// one registry for inline and frontmatter demos
const doqConfig = defineDoqConfig({
  ...doqPaths,
  demos: {
    'install-command': InstallCommandComponent,
    'enter-animation': EnterAnimationDemoComponent,
  },
});

Import @doqs/analog/styles.css once in your global stylesheet. The complete guide lives in the package README.

How it works

1. 1

   Install Doqs

   Add the package next to Analog’s content packages.

2. 2

   Configure the documentation region

   Share the paths, prerender with Analog and register Doqs in your app config.

3. 3

   Write Markdown

   Drop files into src/content/docs. Routes, sidebar and table of contents follow. Add ::demo[id] lines where a live component belongs.

4. 4

   Build and deploy

   vite build prerenders everything to static files you can host anywhere.

Doqs is not MDX: there is no JavaScript in Markdown and no template compilation. A directive only names a component your application registered.

Interactive components in Markdown

Put a line containing only ::demo[id] where a live Angular component belongs. Directives inside code fences, lists and quotes stay literal text, an unknown id shows a short notice instead of breaking the page, and headings, the table of contents and search keep working around every component. The component is yours: you register it, Doqs only places it.

---
title: Getting started
---

## Installation

Pick a package manager and copy the command:

::demo[install-command]

## Try it

::demo[enter-animation]

The text after a demo is still ordinary, searchable Markdown.