@docsector/docsector-reader 4.1.0 → 4.3.0

package/README.md

@@ -30,6 +30,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🤖 **AI-Friendly robots.txt** — Scaffold includes a `robots.txt` explicitly allowing 23 AI crawlers (GPTBot, ClaudeBot, PerplexityBot, GrokBot, etc.)
 - 🧭 **Content Signals** — Optional `Content-Signal` directive for declaring AI usage policy (`ai-train`, `search`, `ai-input`) in `robots.txt`
 - 🧩 **Agent Skills Discovery Index** — Optional `/.well-known/agent-skills/index.json` with RFC v0.2.0 schema and SHA-256 digests
+- ✍️ **Docsector Authoring Skill** — Publishable `SKILL.md` that teaches agents Docsector blocks, page patterns, MCP lookup, and WebMCP tools
 - 🪪 **MCP Server Card** — Optional `/.well-known/mcp/server-card.json` for MCP server discovery before connection
 - 🌐 **WebMCP Browser Tools** — Optional registration of in-page tools via `navigator.modelContext` for browser agents
 - 🔗 **Homepage Link Headers** — Auto-generated `Link` response headers for agent discovery (`api-catalog`, `service-doc`, `service-desc`, `describedby`) per RFC 8288 / RFC 9727
@@ -75,11 +76,14 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🌐 **Embedded URL Blocks** — Use `<d-block-embedded-url url="https://...">...</d-block-embedded-url>` to render curated embeds for YouTube, Vimeo, Spotify, and CodePen with a safe link-card fallback for unsupported URLs
 - 🧭 **Quick Links Custom Element** — Use `<d-block-quick-links>` and `<d-block-quick-link>` in Markdown to render rich home navigation cards
 - 🗂️ **Cards Custom Element** — Use `<d-block-cards>` and `<d-block-card>` in Markdown to render linked content cards with optional cover images
+- 🧾 **API JSON Reference Block** — Use `<d-block-api src="..." />` in Markdown to render Quasar-compatible API reference UIs from public JSON assets without inventing a new schema
 - 🗂️ **API Catalog Well-Known** — Auto-generates `/.well-known/api-catalog` as Linkset JSON for machine-readable API discovery
+- 🧠 **Docsector Authoring Skill Docs** — Documents the built-in `SKILL.md` and reference files so agents can learn Docsector blocks, page patterns, MCP lookup, and WebMCP tools from a public manual page
 - 🗃️ **Multi-Version History** — Archive older major versions under `src/pages/.old/<version>/` and expose them at prefixed routes (e.g. `/v0.x/guide/...`) while keeping the current docs at unprefixed routes
 - 🏷️ **Version Selector Badges** — Every version in the sidebar selector displays a color-coded badge: green for released, orange for draft, red for deprecated; fully customizable via `badge: { label, color, textColor }`
 - 📂 **Tabbed Code Blocks** — Group consecutive fenced code blocks into tabs using the `group` and `tab` attributes in the fence info line
 - 🧪 **Live Code Example Blocks** — Use `<d-block-code-example src="..." />` to render bundled Vue SFC examples with a live preview, GitHub source link, source toggle, and CodePen export for compatible examples
+- 📏 **Accurate Source Code Line Counts** — Code example headers count visible lines correctly across LF, CRLF, and terminal newlines without inflating the total
 - 🍞 **Breadcrumb Path Display** — Show a file path breadcrumb above code blocks with the `breadcrumb` attribute; renders as clickable path segments
 - 🎨 **File Type Icons** — Automatically resolves file extension or filename to a Material Icon Theme SVG icon, shown inline in tabs and beside the last breadcrumb segment
 - ⚙️ **Single Config File** — Customize branding, links, and languages via `docsector.config.js`
@@ -525,6 +529,12 @@ The generated payload follows Agent Skills Discovery RFC v0.2.0 and includes:
 - `$schema`
 - `skills[]` entries with `name`, `type`, `description`, `url`, `digest`
 
+This repository publishes the built-in Docsector authoring skill at:
+
+- `/.well-known/agent-skills/docsector-documentation-authoring/SKILL.md`
+
+The skill teaches agents Docsector Markdown authoring, all documented blocks, page/source conventions, MCP lookup, and WebMCP browser tools.
+
 When `digest` is omitted in config, Docsector computes it automatically from the referenced local artifact and writes it as:
 
 - `sha256:{hex}`
@@ -541,10 +551,10 @@ export default {
     schema: 'https://schemas.agentskills.io/discovery/0.2.0/schema.json',
     skills: [
       {
-        name: 'my-docs-mcp',
+        name: 'docsector-documentation-authoring',
         type: 'skill-md',
-        description: 'Search and fetch docs pages via MCP.',
-        url: '/.well-known/agent-skills/my-docs-mcp/SKILL.md'
+        description: 'Author Docsector documentation with Markdown, custom blocks, MCP, and WebMCP.',
+        url: '/.well-known/agent-skills/docsector-documentation-authoring/SKILL.md'
       }
     ]
   }
@@ -755,10 +765,10 @@ export default {
     schema: 'https://schemas.agentskills.io/discovery/0.2.0/schema.json',
     skills: [
       {
-        name: 'my-docs-mcp',
+        name: 'docsector-documentation-authoring',
         type: 'skill-md',
-        description: 'Search and fetch docs pages via MCP.',
-        url: '/.well-known/agent-skills/my-docs-mcp/SKILL.md'
+        description: 'Author Docsector documentation with Markdown, custom blocks, MCP, and WebMCP.',
+        url: '/.well-known/agent-skills/docsector-documentation-authoring/SKILL.md'
       }
     ]
   },

package/bin/docsector.js

@@ -23,7 +23,7 @@ const packageRoot = resolve(__dirname, '..')
 const args = process.argv.slice(2)
 const command = args[0]
 
-const VERSION = '4.1.0'
+const VERSION = '4.3.0'
 
 const HELP = `
   Docsector Reader v${VERSION}

package/docsector.config.js

@@ -55,6 +55,21 @@ export default {
     toolSuffix: 'docsector'
   },
 
+  // @ Agent Skills
+  agentSkills: {
+    enabled: true,
+    path: '/.well-known/agent-skills/index.json',
+    schema: 'https://schemas.agentskills.io/discovery/0.2.0/schema.json',
+    skills: [
+      {
+        name: 'docsector-documentation-authoring',
+        type: 'skill-md',
+        description: 'Author Docsector documentation with Markdown, custom blocks, MCP, and WebMCP.',
+        url: '/.well-known/agent-skills/docsector-documentation-authoring/SKILL.md'
+      }
+    ]
+  },
+
   // @ Home page source
   homePage: {
     source: 'remote-readme',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docsector/docsector-reader",
-  "version": "4.1.0",
+  "version": "4.3.0",
   "description": "A documentation rendering engine built with Vue 3, Quasar v2 and Vite. Transform Markdown into beautiful, navigable documentation sites.",
   "productName": "Docsector Reader",
   "author": "Rodrigo de Araujo Vieira",

package/public/.well-known/agent-skills/docsector-documentation-authoring/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: docsector-documentation-authoring
+description: "Author Docsector documentation with Markdown, d-block custom elements, page structures, blocks, MCP, WebMCP, and agent-readable docs. Use when writing or editing Docsector pages, choosing content blocks, creating examples, documenting APIs, or helping an AI understand Docsector authoring syntax."
+argument-hint: "Describe the Docsector page, block, or documentation task"
+user-invocable: true
+---
+
+# Docsector Documentation Authoring
+
+## When to Use
+
+Use this skill when creating, reviewing, or editing documentation for a site built with Docsector Reader.
+
+Use it for:
+
+- Choosing the right Docsector block for a content need.
+- Writing Markdown pages with Docsector custom elements.
+- Creating overview, showcase, guide, API reference, changelog, or landing content.
+- Finding live Docsector docs through MCP, WebMCP, Markdown negotiation, or `llms.txt`.
+- Teaching an AI assistant how Docsector pages, blocks, and examples are authored.
+
+## Expected Outcome
+
+- The page uses standard Markdown where Markdown is enough.
+- Rich interactions use the appropriate Docsector custom element.
+- Links, assets, examples, and API JSON use Docsector conventions.
+- The result is easy to scan, accessible, and friendly to both humans and agents.
+- When MCP or WebMCP is available, current Docsector documentation is queried instead of relying only on memory.
+
+## Authoring Workflow
+
+1. Identify the page purpose: concept, tutorial, API reference, release note, navigation hub, example showcase, or troubleshooting guide.
+2. Use headings to shape the reading path. In normal page content, start with `##` because the page title is supplied by metadata.
+3. Pick the simplest block that communicates the content. Prefer Markdown first, then Docsector custom elements when the layout or interaction needs it.
+4. Keep custom element attributes short and explicit. Use `to` for internal navigation and `href` for external URLs.
+5. Put reusable assets in stable public paths such as `/images/...`, `/files/...`, `/api/...`, or `/quasar-api/...`.
+6. For live examples, place Vue SFCs under `src/examples/**/*.vue` and reference them with `<d-block-code-example>`.
+7. For API references, serve JSON from a same-origin public asset and reference it with `<d-block-api>`.
+8. Validate links, anchors, code fences, and custom element closing tags before finishing.
+
+## Quick Block Selection
+
+| Need                            | Use                      |
+| ------------------------------- | ------------------------ |
+| Narrative text                  | Paragraphs               |
+| Page sections and anchors       | Headings                 |
+| Features or requirements        | Unordered lists          |
+| Sequential instructions         | Ordered lists or Stepper |
+| Progress states                 | Task lists               |
+| Notes, tips, warnings           | Hints                    |
+| Quoted text                     | Quotes                   |
+| Commands or source snippets     | Code blocks              |
+| Live Vue demos                  | Code examples            |
+| Flowcharts or diagrams          | Mermaid diagrams         |
+| Screenshots or diagrams         | Images                   |
+| Downloads                       | Files                    |
+| Videos, audio, or pens          | Embedded URLs            |
+| Equations                       | Math and TeX             |
+| Optional detail                 | Expandable               |
+| Guided sequence with navigation | Stepper                  |
+| Changelog or release log        | Timeline                 |
+| Comparisons or matrices         | Tables                   |
+| Custom structure                | Raw HTML                 |
+| Small navigation sets           | Quick Links              |
+| Visual navigation grids         | Cards                    |
+| Structured API docs             | API Reference            |
+
+For the complete syntax and guidance, read [the block catalog](./references/block-catalog.md).
+
+## MCP and WebMCP
+
+When a Docsector site exposes MCP, prefer live lookup for exact syntax and current examples.
+
+Typical MCP tools are named with the configured suffix:
+
+- `search_{suffix}` searches documentation pages.
+- `get_page_{suffix}` returns raw Markdown for a documentation page.
+
+This repository uses the suffix `docsector`, so the local docs tools are expected to be `search_docsector` and `get_page_docsector` when the MCP server is connected.
+
+Use known paths such as:
+
+- `manual/content/blocks/cards/overview`
+- `manual/content/blocks/quick-links/overview`
+- `manual/content/blocks/api-reference/overview`
+- `manual/content/blocks/timeline/showcase`
+
+Browser agents may also see WebMCP tools such as `docs.search_docs`, `docs.get_page`, `docs.navigate_to`, and `docs.copy_current_page`.
+
+Read [MCP and WebMCP reference](./references/mcp-webmcp.md) for details and caveats.
+
+## Page and Asset Conventions
+
+Read [page structure reference](./references/page-structure.md) before changing page layout, localization, examples, or public assets.
+
+Key conventions:
+
+- Manual block docs live under `src/pages/manual/content/blocks/`.
+- Block pages usually have `overview` and `showcase` subpages.
+- Localized source files use suffixes such as `.en-US.md` and `.pt-BR.md`.
+- Downloadable files should use `/files/...` paths backed by `public/files/...`.
+- Images should use `/images/...` paths backed by `public/images/...`.
+- API JSON should use same-origin public paths such as `/api/...` or `/quasar-api/...`.
+
+## Authoring Patterns
+
+Read [authoring patterns](./references/authoring-patterns.md) for common page recipes such as tutorials, changelogs, navigation hubs, API reference pages, and example showcases.
+
+## Quality Checklist
+
+- The page has a clear first section and predictable heading hierarchy.
+- Every custom element has required attributes and matching closing tags unless it is intentionally self-closing.
+- Internal links use route paths and external links use absolute URLs.
+- Images, files, examples, and API JSON point to assets that exist or are intentionally external.
+- Hints are reserved for semantic callouts, not general decoration.
+- Tables are not overloaded with prose that would read better as sections or lists.
+- Nested custom blocks are used conservatively; avoid unsupported nested Expandable and Stepper patterns.
+- MCP or WebMCP was used for current docs when available.

package/public/.well-known/agent-skills/docsector-documentation-authoring/references/authoring-patterns.md

@@ -0,0 +1,98 @@
+# Docsector Authoring Patterns
+
+Use these patterns to choose a page shape before writing detailed content.
+
+## Tutorial or Setup Guide
+
+Use when readers must follow a sequence.
+
+Recommended blocks:
+
+- Headings for major phases.
+- Stepper for guided, interactive sequences.
+- Code blocks for commands and configuration.
+- Hints for warnings or best practices.
+- Files for downloadable checklists or templates.
+
+Start with a short outcome statement, then move into steps. Keep each step focused on one action and one result.
+
+## Concept or Overview Page
+
+Use when readers need understanding before action.
+
+Recommended blocks:
+
+- Paragraphs for explanation.
+- Headings for scannable sections.
+- Unordered lists for capabilities and constraints.
+- Images or Mermaid diagrams for mental models.
+- Quick Links or Cards for next steps.
+
+Avoid heavy custom blocks if a simple section and list are clearer.
+
+## Navigation Hub
+
+Use when a page primarily routes readers to other content.
+
+Recommended blocks:
+
+- Quick Links for compact next steps.
+- Cards for visual destinations.
+- Short paragraphs for framing.
+- Headings only when the hub has multiple groups.
+
+Use `to` for Docsector routes and `href` for external URLs.
+
+## Changelog or Release Notes
+
+Use when content is chronological.
+
+Recommended blocks:
+
+- Timeline for dated entries.
+- Timeline tags for release channels, categories, or status.
+- Hints for breaking changes or migration warnings.
+- Code blocks for commands that users must run.
+- Quick Links for related upgrade docs.
+
+Give timeline items stable `anchor` values for important releases and migration entries.
+
+## API Reference Page
+
+Use when structured API data is available.
+
+Recommended blocks:
+
+- API Reference for Quasar-compatible JSON.
+- Code blocks for quick usage examples.
+- Hints for compatibility or deprecation notes.
+- Tables only for small summaries not already covered by the API block.
+
+Keep JSON assets under same-origin public paths such as `/api/manual/...` or `/quasar-api/...`.
+
+## Example Showcase
+
+Use when readers need to inspect behavior and source.
+
+Recommended blocks:
+
+- Code Examples for live Vue SFC previews.
+- Code blocks for smaller standalone snippets.
+- Expandable for optional implementation notes.
+- Cards or Quick Links for related examples.
+
+Use `expanded="true"` when source inspection is the main value. Set `codepen="false"` when an example cannot be exported safely.
+
+## Troubleshooting Page
+
+Use when readers need to diagnose and resolve problems.
+
+Recommended blocks:
+
+- Headings for symptoms or error messages.
+- Hints for warnings and high-risk operations.
+- Ordered lists for resolution steps.
+- Code blocks for commands and logs.
+- Expandable for verbose logs or advanced diagnostics.
+
+Keep the shortest successful path visible and move rare details into Expandable blocks.

package/public/.well-known/agent-skills/docsector-documentation-authoring/references/block-catalog.md

@@ -0,0 +1,321 @@
+# Docsector Block Catalog
+
+This catalog summarizes the Docsector authoring blocks that an agent should know before writing documentation. Each block has live manual pages at `manual/content/blocks/{slug}/overview` and usually `manual/content/blocks/{slug}/showcase`.
+
+## Custom Element Blocks
+
+| Block         | Syntax                                              | Use For                                                  | Manual Path                                    |
+| ------------- | --------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------- |
+| Quick Links   | `<d-block-quick-links>` with `<d-block-quick-link>` | Small sets of next-step links                            | `manual/content/blocks/quick-links/overview`   |
+| Cards         | `<d-block-cards>` with `<d-block-card>`             | Visual navigation grids and landing sections             | `manual/content/blocks/cards/overview`         |
+| Timeline      | `<d-block-timeline>` with `<d-block-timeline-item>` | Changelogs, release notes, rollout logs                  | `manual/content/blocks/timeline/overview`      |
+| Stepper       | `<d-block-stepper>` with `<d-block-step>`           | Guided multi-step flows with navigation                  | `manual/content/blocks/stepper/overview`       |
+| Expandable    | `<d-block-expandable>`                              | Optional details, appendices, longer examples            | `manual/content/blocks/expandable/overview`    |
+| Files         | `<d-block-file>`                                    | Download cards for attachments                           | `manual/content/blocks/files/overview`         |
+| Embedded URLs | `<d-block-embedded-url>`                            | YouTube, Vimeo, Spotify, CodePen, or link-card fallbacks | `manual/content/blocks/embedded-urls/overview` |
+| Code Examples | `<d-block-code-example>`                            | Live Vue SFC previews with source inspection             | `manual/content/blocks/code-examples/overview` |
+| API Reference | `<d-block-api>`                                     | Quasar-compatible JSON API reference UIs                 | `manual/content/blocks/api-reference/overview` |
+
+### Quick Links
+
+Use Quick Links when a page needs a compact group of destinations without a long prose list.
+
+```html
+<d-block-quick-links title="Get started">
+  <d-block-quick-link
+    title="Install"
+    description="Set up the project"
+    to="/guide/getting-started"
+  />
+  <d-block-quick-link
+    title="GitHub"
+    description="Open the repository"
+    href="https://github.com/docsector/docsector-reader"
+  />
+</d-block-quick-links>
+```
+
+Use `to` for internal navigation and `href` for external URLs. Keep descriptions short.
+
+### Cards
+
+Use Cards for landing sections, curated resource grids, and visual navigation.
+
+```html
+<d-block-cards title="Explore more">
+  <d-block-card
+    title="Install"
+    description="Set up the project"
+    to="/guide/getting-started"
+    image="/images/cards/getting-started-cover.svg"
+  />
+  <d-block-card
+    title="GitHub"
+    description="Open the repository"
+    href="https://github.com/docsector/docsector-reader"
+    icon="launch"
+  />
+</d-block-cards>
+```
+
+Prefer `image` for landing-page tiles and `icon` for lighter cards without covers.
+
+### Timeline
+
+Use Timeline for chronological entries such as changelogs, release notes, migrations, and rollout journals.
+
+```html
+<d-block-timeline>
+  <d-block-timeline-item date="2025-12-25" anchor="brand-new-update">
+    <d-block-timeline-tag color="warning" icon="rocket_launch"
+      >beta</d-block-timeline-tag
+    >
+    <d-block-timeline-tag color="secondary" text-color="white"
+      >docs</d-block-timeline-tag
+    >
+
+    ## A brand new update Use this block for release notes, product
+    announcements, migration notices, or operational updates.
+  </d-block-timeline-item>
+</d-block-timeline>
+```
+
+Every item needs `date`. Tags are optional and support text content or `label`, plus `color`, `text-color`, and `icon`. `anchor` is optional; Docsector can generate one from the date and first visible text. Headings inside timeline items are flattened so the page ToC stays stable.
+
+### Stepper
+
+Use Stepper when the reader should move through a guided sequence.
+
+```html
+<d-block-stepper>
+  <d-block-step title="Install dependencies">
+    Run `npm install` in the project root.
+  </d-block-step>
+
+  <d-block-step
+    title="Ship the release"
+    icon="rocket_launch"
+    active-icon="rocket_launch"
+    done-icon="task_alt"
+  >
+    Use icon attributes when a numbered prefix is not expressive enough.
+  </d-block-step>
+</d-block-stepper>
+```
+
+Every step needs `title`. Step bodies support common Markdown such as paragraphs, lists, hints, code fences, images, tables, and math. Avoid nested Stepper blocks and other custom Docsector blocks inside steps in the current version.
+
+### Expandable
+
+Use Expandable for optional material that should not interrupt the main reading path.
+
+```html
+<d-block-expandable title="Release checklist" open="true">
+  - Review breaking changes - Update screenshots - Run smoke tests
+</d-block-expandable>
+```
+
+Use `open="true"` to start expanded. Keep page headings outside expandable bodies because inner headings are flattened. Avoid nesting one expandable inside another.
+
+### Files
+
+Use Files for attachments such as checklists, PDFs, sample bundles, and release assets.
+
+```html
+<d-block-file
+  src="/files/manual/release-checklist.txt"
+  title="Release checklist"
+  size="1 KB"
+>
+  Download the example attachment used in this manual.
+</d-block-file>
+```
+
+`src` is required. `title` and `size` are optional. When `title` is omitted, Docsector falls back to the file name from `src`. Store repo-tracked attachments under `public/files/` and reference them as `/files/...`.
+
+### Embedded URLs
+
+Use Embedded URLs for curated public embeds while keeping Docsector's consistent card and preview treatment.
+
+```html
+<d-block-embedded-url
+  url="https://www.youtube.com/watch?v=M7lc1UVf-VE"
+  title="YouTube player demo"
+>
+  Optional caption rendered as inline Markdown.
+</d-block-embedded-url>
+```
+
+`url` is required and `title` is optional. Supported providers are YouTube, Vimeo, Spotify, and CodePen. Unsupported or private URLs render as safe external-link cards.
+
+### Code Examples
+
+Use Code Examples to render project Vue SFCs as live previews with source inspection.
+
+```html
+<d-block-code-example
+  src="manual/code-examples/basic-counter"
+  title="Basic counter"
+/>
+```
+
+Place examples under `src/examples/**/*.vue`. The `src` value is normalized to kebab-case, so `manual/code-examples/basic-counter` resolves to `src/examples/manual/code-examples/BasicCounter.vue`. `file` is an alias for `src`.
+
+Common attributes:
+
+| Attribute    | Purpose                                        |
+| ------------ | ---------------------------------------------- |
+| `src`        | Example id under `src/examples/**/*.vue`       |
+| `file`       | Alias for `src`                                |
+| `title`      | Header title above the preview                 |
+| `expanded`   | Opens the source panel by default when `true`  |
+| `codepen`    | Shows the CodePen action unless set to `false` |
+| `scrollable` | Gives the preview a fixed scrollable height    |
+| `overflow`   | Allows horizontal and vertical overflow        |
+| `height`     | Sets a preview height such as `360` or `420px` |
+
+### API Reference
+
+Use API Reference blocks to render Quasar-compatible JSON API documentation.
+
+```html
+<d-block-api src="/quasar-api/QSeparator.json" />
+
+<d-block-api
+  src="/api/manual/http-client.json"
+  title="HTTP Client API"
+  page-link="true"
+/>
+```
+
+`src` is required and should point to same-origin JSON. `title` overrides the header. `page-link="true"` shows a Docs button when the JSON includes `meta.docsUrl`. Useful JSON sections include `props`, `methods`, `events`, `value`, `arg`, and `quasarConfOptions`; entries with `internal: true` are hidden.
+
+## Markdown and Native Blocks
+
+| Block            | Syntax                     | Use For                         | Manual Path                                       |
+| ---------------- | -------------------------- | ------------------------------- | ------------------------------------------------- |
+| Paragraphs       | Plain Markdown text        | Explanations and transitions    | `manual/content/blocks/paragraphs/overview`       |
+| Headings         | `##`, `###`, `####`        | Sections, anchors, page ToC     | `manual/content/blocks/headings/overview`         |
+| Unordered Lists  | `- item`                   | Feature sets and requirements   | `manual/content/blocks/unordered-lists/overview`  |
+| Ordered Lists    | `1. item`                  | Sequential procedures           | `manual/content/blocks/ordered-lists/overview`    |
+| Task Lists       | `- [ ] item`, `- [x] item` | Static checklists               | `manual/content/blocks/task-lists/overview`       |
+| Hints            | `> [!WARNING]`             | Semantic notes and warnings     | `manual/content/blocks/hints/overview`            |
+| Quotes           | `> text`                   | Neutral quoted text             | `manual/content/blocks/quotes/overview`           |
+| Code Blocks      | Fenced code                | Commands and snippets           | `manual/content/blocks/code-blocks/overview`      |
+| Mermaid Diagrams | Fenced `mermaid` code      | Flowcharts and diagrams         | `manual/content/blocks/mermaid-diagrams/overview` |
+| Images           | `![caption](/path.png)`    | Screenshots and illustrations   | `manual/content/blocks/images/overview`           |
+| Math and TeX     | `$...$`, `$$...$$`         | Inline and display equations    | `manual/content/blocks/math-and-tex/overview`     |
+| Tables           | Markdown tables            | Comparisons and matrices        | `manual/content/blocks/tables/overview`           |
+| Raw HTML         | HTML tags                  | Custom structure and attributes | `manual/content/blocks/raw-html/overview`         |
+
+### Paragraphs
+
+Use paragraphs for narrative copy. Separate paragraphs with a blank line. Inline emphasis, links, inline code, and math work inside normal paragraphs.
+
+### Headings
+
+Use headings to organize the page and feed the right-side table of contents. In page content, start with `##` because the page title is generated from page metadata. Keep heading levels in order and use headings for sections that readers may bookmark or deep-link.
+
+### Lists
+
+Use unordered lists when order does not matter. Use ordered lists when sequence matters. Use task lists when each item should show a done or not-done state. Published task-list checkboxes are static and cannot be toggled by readers.
+
+### Hints
+
+Use GitHub-style alert markers in blockquotes:
+
+```markdown
+> [!WARNING]
+> This operation may interrupt workers.
+```
+
+Supported markers are `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, and `CAUTION`. Unknown markers fall back to regular quotes.
+
+### Quotes
+
+Use regular blockquotes for cited text or neutral notes that should stand apart from the main flow without semantic alert styling.
+
+```markdown
+> This is a regular quote.
+```
+
+### Code Blocks
+
+Use fenced code blocks for commands and snippets. Docsector renders syntax highlighting, line numbers, copy support, grouped tabs, breadcrumbs, and file metadata.
+
+````markdown
+```bash :filename="install.sh";
+npm install
+npm run dev
+```
+````
+
+Useful metadata attributes are `filename`, `group`, `tab`, and `breadcrumb` using `:attr;` syntax.
+
+### Mermaid Diagrams
+
+Use a fenced `mermaid` block for diagrams.
+
+````markdown
+```mermaid
+flowchart TD
+  A[Start] --> B[Finish]
+```
+````
+
+Docsector lazy-loads Mermaid, renders responsive SVG, adapts to light and dark mode, and shows a safe error state for invalid Mermaid syntax.
+
+### Images
+
+Use standard Markdown images for screenshots, illustrations, diagrams, and product UI.
+
+```markdown
+![Dashboard overview](/images/example-dashboard.png)
+```
+
+Standalone Markdown images render as block figures with click-to-zoom. The label is used as both caption and alt text. Use raw `<figure>` and `<picture>` markup when alt text and visible caption need to differ.
+
+### Math and TeX
+
+Use single dollar delimiters for inline math and double dollar delimiters for display math.
+
+```markdown
+Use $E = mc^2$ inside a sentence.
+
+$$
+\int_0^1 x^2 dx
+$$
+```
+
+Math works in paragraphs, hints, and expandable blocks. Delimiters remain literal inside inline code and fenced code blocks.
+
+### Tables
+
+Use tables for comparisons, option matrices, compatibility notes, and scannable row-column content.
+
+```markdown
+| Feature | Status | Notes                    |
+| ------- | ------ | ------------------------ |
+| Search  | Done   | Available in the sidebar |
+```
+
+Keep column labels short. Split very dense tables into smaller sections.
+
+### Raw HTML
+
+Use raw HTML only when Markdown is not expressive enough or when authoring Docsector custom elements.
+
+```html
+<div data-kind="secondary-note">
+  This block uses raw HTML inside the page source.
+</div>
+```
+
+Prefer plain Markdown first. Keep raw markup readable because documentation content still needs maintenance.
+
+## Renderer and Parser References
+
+- `src/components/page-section-tokens.js` parses custom elements and Markdown tokens.
+- `src/components/DPageTokens.vue` dispatches tokens to block components.
+- `src/components/DBlockCards.vue`, `DBlockQuickLinks.vue`, `DBlockTimeline.vue`, `DBlockStepper.vue`, `DBlockExpandable.vue`, `DBlockFile.vue`, `DBlockEmbeddedUrl.vue`, `DBlockCodeExample.vue`, and `DBlockApi.vue` render custom element blocks.
+- `src/components/DBlockSourceCode.vue`, `DBlockMermaidDiagram.vue`, `DBlockBlockquote.vue`, and `DBlockImage.vue` render richer Markdown blocks.