Use AsciiDoc content

Use the AsciiDoc plugin to render .adoc files as regular content pages in Realm.

The AsciiDoc plugin package is @redocly/realm-plugin-asciidoc. When enabled, it scans content files with the .adoc extension, creates pages, and includes content in:

• page search index
• AI search documents
• llm.txt generation

Install the package in your Realm project:

pnpm add @redocly/realm-plugin-asciidoc

Add the plugin to the plugins list in your redocly.yaml:

plugins:
  - '@redocly/realm-plugin-asciidoc/plugin.js'

Create AsciiDoc files in your content directory, for example:

= Getting started with AsciiDoc
:description: A short AsciiDoc example page.
:keywords: asciidoc, docs

AsciiDoc pages are rendered in Realm with search support.

== Features

- Lists
- Tables
- Code blocks
- Admonitions

[source,typescript]
----
console.log('Hello from AsciiDoc');
----

== Links

- xref:./another-page.adoc[Cross-file link]
- link:https://redocly.com/docs/realm[External link]

The AsciiDoc plugin supports rendering Mermaid, PlantUML, and Excalidraw diagrams. Use an open block whose style matches the diagram type:

[mermaid]
--
graph LR;
  Design --> Preview --> Publish
--

[plantuml, format="svg", id="request-flow"]
--
@startuml
Client -> Server: Request
Server --> Client: Response
@enduml
--

[excalidraw]
--
{ "elements": [ { "type": "rectangle", "x": 10, "y": 10, "width": 200, "height": 100 } ] }
--

Realm always renders diagrams as SVG. If you include a format attribute for compatibility with Asciidoctor diagram syntax, it is ignored.

See Add diagrams for more details on each diagram type.

Because this feature is experimental, expect gaps with advanced AsciiDoc syntax and extensions. If an unsupported pattern appears, simplify the markup or use Markdown/Markdoc for that section.

• Content types - Explore the different types of content you can use in your project
• Add diagrams - Learn how to enhance your project with diagrams