Markdown Twin

Usage

Publish a Markdown twin of every page, built from the source at build time, so AI agents can read your content without parsing HTML. A page at /docs/basics/ gets its twin at /docs/basics/index.md; a page with a file name, such as /404.html, gets /404.html.md.

• Markdown pages: the Markdown source, with the front matter title as its heading.
• AsciiDoc pages: converted in-process to GitHub-Flavored Markdown, includes and attributes resolved.
• HTML pages and paginated listing pages: no twin.

Nothing to configure: add the dependency and every page gets a twin. Use mdtwin: false in the FM data to keep a page out:

---
title: My page
mdtwin: false
---

no-index-all: true keeps a page out of the twins too, as it does for the sitemap, llms.txt and search. Set mdtwin: true on the same page to publish its twin anyway.

A page the converter cannot handle gets no twin and a warning in the build log; the build never fails because of a twin. Twins are static files, so with the hybrid plugin a page scheduled for a later date gets its twin at the first build after that date. The twins resolve the same quarkus.asciidoc.attributes.* and asciidoc-attributes front matter as the rendered pages, and an include:: may only read files outside the site directory when quarkus.asciidoc.safe-mode is UNSAFE, as for the pages themselves.