AsciiDoc-style example

This page mirrors MkDocs docs/asciidoc-example.adoc: same ideas in Markdown. The MkDocs POC uses AsciiDoc via mkdocs-asciidoctor-backend; Roq is Markdown/HTML-first, so this file stands in for that page for a fair comparison with the Docusaurus POC (which also uses a Markdown equivalent).

Why AsciiDoc (in MkDocs)?

In the MkDocs stack, AsciiDoc offers:

  • Strong semantics (sections, admonitions, cross-references)
  • Long-form technical docs and multi-output (HTML, PDF) via Asciidoctor

For Roq, you author in Markdown or HTML in content/; for AsciiDoc-native workflows, MkDocs + Asciidoctor or Antora may be a better fit.

Quick example

YAML snippet (same as MkDocs AsciiDoc sample):

site_name: MkDocs POC
docs_dir: docs
theme:
  name: material

Cross-references

See the repo README for how this POC maps to the MkDocs and Docusaurus checklists.