Markdown files

Grapharch supports GitHub-flavoured Markdown (GFM) for authored documentation, including tables, task-list checkboxes, strikethrough, and GitHub-style callouts. Headings, paragraphs, links, emphasis, lists, and fenced code blocks are supported as well. The same parser configuration is used for collection and rendering.

Each Markdown-file collector reads one source. YAML frontmatter supplies a title, a stable logical identity, and publication hints. Sections become topics and ordered documentation fragments in the KG; fenced code blocks also become queryable examples. Renderers publish those collected fragments from a pinned revision.

Task lists

Use - [ ] for an incomplete task and - [x] for a completed task:

• Collect Markdown and frontmatter into the documentation KG.
• Render checked and unchecked task states.
• Add more examples to your documentation.
  • Include a nested task when useful.

The generated website preserves the completion state and uses the checkbox as the list marker.

Tables and strikethrough

Callouts

Start a blockquote with [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], or [!CAUTION]. Grapharch renders the type as a labelled callout rather than printing the marker.

Note

This page is collected into the KG and rendered by Grapharch itself.

Tip

Give documents stable identities in frontmatter so files can move without changing their logical identity.

Important

Local links and heading references must resolve in the selected publication.

Warning

A failed build preserves the previous complete publication.

Caution

Removing a topic can invalidate links from other documentation fragments.

Markers inside inline code or fenced code blocks remain literal source text:

> [!NOTE]
> Write the note here.

Frontmatter

---
title: Example topic
parent: Usage
nav_order: 2
permalink: /usage/example/
grapharch:
  subject: urn:example:documentation:topic
---

See Self-hosted documentation for a complete website build and the relationship between source files, logical topics, and publication pages.

Images

PNG, JPEG, and SVG images at HTTPS URLs are collected into the documentation graph. Shared URLs create one image input per project batch. The website, specification, and PDF use those retained bytes, so rendering an exported graph does not contact the image host or reopen the original Markdown files.

Images need alternative text. Active SVG content, unsafe URLs, oversized images, and content that disagrees with its declared format are rejected. Repository sources also resolve relative images against the selected Git revision.

Current boundaries

The current pipeline does not execute MDX or embedded scripts. Raw HTML in Markdown and uncollected local images are rejected. Ordinary Markdown-file images require HTTPS URLs; relative images need a repository source. These boundaries are explicit; unsupported content fails the build.