AsciiDoc to Markdown

downdoc: Down-convert AsciiDoc to Markdown

The downdoc package provides both a CLI (command: downdoc) and a JavaScript function (downdoc) to down-convert AsciiDoc to Markdown.

• https://github.com/opendevise/downdoc
• https://app.mdedit.ai/tools/converter/asciidoc-to-markdown

for file in *.adoc; do npx downdoc "$file"; done

for file in *.adoc; do npx downdoc "$file" -o "${file%.adoc}.mdx"; done

Migrating

Migrating from Antora (which uses AsciiDoc and a multi-repo/component structure) to Docusaurus (which uses Markdown/MDX and a React-based single-repo architecture) requires handling three main differences:

1. Markup Language: Converting .adoc (AsciiDoc) files to .md or .mdx (Markdown).
2. Navigation & Structure: Translating Antora's nav.adoc files and antora.yml component descriptors into Docusaurus's sidebar configurations (sidebars.ts) and flat/nested folder hierarchies.
3. Cross-References & Attributes: Replacing Antora-specific macros (xref, include, block attributes) with standard Markdown equivalents or Docusaurus plugins.

---

Step 1: Initialize a New Docusaurus Project

If you haven't already set up your Docusaurus site, create one using the classic template:

npx create-docusaurus@latest my-docs classic --typescript
cd my-docs
npm start

---

Step 2: Convert AsciiDoc (.adoc) to Markdown (.md / .mdx)

Because syntax differs, you need to translate your source files. For small to medium sites, an automated script (using Python or Node.js with regex) or manual conversion works best. For large enterprise codebases, tools like pandoc can assist with the bulk syntax translation.

Syntax Mapping Quick Reference:

Element	Antora (AsciiDoc)	Docusaurus (Markdown / MDX)
Page Title	= Document Title	# Document Title (or via Front Matter title:)
Headings	== Section Title	## Section Title
Bold / Italic	*bold*, _italic_	**bold**, *italic*
Links	[https://example.com](https://example.com)[Link Text]	[Link Text](https://example.com)
Cross-References	xref:page-name.adoc[Link Text]	[Link Text](./page-name.md)

---

Step 3: Reorganize Directory Structure

Antora structures content by components and modules (modules/ROOT/pages/). Docusaurus relies directly on a centralized docs/ folder hierarchy.

Antora structure:

my-component/
├── antora.yml
└── modules/
    └── ROOT/
        ├── nav.adoc
        └── pages/
            ├── index.adoc
            └── guide/
                └── intro.adoc

Target Docusaurus structure:

my-docs/
└── docs/
    ├── index.md
    └── guide/
        └── intro.md

Tip: Flatten your Antora module directories (modules/ROOT/pages/) directly into the Docusaurus docs/ folder tree.

---

Step 4: Map Navigation (nav.adoc to sidebars.ts)

Antora uses an AsciiDoc list inside nav.adoc to build menus. Docusaurus manages this via sidebars.ts in the root directory.

Example conversion:

Antora (nav.adoc):

* xref:index.adoc[Home]
* Getting Started
** xref:guide/intro.adoc[Introduction]

Docusaurus (sidebars.ts):

import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";

const sidebars: SidebarsConfig = {
  tutorialSidebar: [
    "index",
    {
      type: "category",
      label: "Getting Started",
      items: ["guide/intro"],
    },
  ],
};

export default sidebars;

(Alternatively, you can enable auto-generated sidebar panels in Docusaurus by setting type: 'autogenerated', dirName: '.' to automatically mirror your folder structure).

---