Docs: Basic Antora page

docs/user/index.rst

@@ -10,6 +10,8 @@ Read the Docs: documentation simplified
    /intro/doctools
    /intro/mkdocs
    /intro/sphinx
+   /intro/markdoc
+   /intro/antora
    /intro/add-project
    /examples
 

docs/user/intro/antora.rst

@@ -0,0 +1,77 @@
+
+Antora
+======
+
+.. meta::
+   :description lang=en: Hosting Antora documentation on Read the Docs.
+
+`Antora`_ is a powerful documentation framework that allows you to write documentation in AsciiDoc.
+
+Minimal configuration is required to build an existing Antora project on Read the Docs.
+
+.. code-block:: yaml
+   :caption: .readthedocs.yaml
+
+    version: 2
+
+    build:
+        os: ubuntu-22.04
+        tools:
+            nodejs: "20"
+        commands:
+            - npm i -g -D -E antora
+            - antora -v
+            - antora --fetch antora-playbook.yml --to-dir $READTHEDOCS_OUTPUT/html
+
+.. _Antora: https://antora.org/
+
+Example configuration
+---------------------
+
+In order to build an Antora project on Read the Docs,
+you need a playbook file that specifies the sources and UI bundle to use:
+
+.. code-block:: yaml
+   :caption: antora-playbook.yml
+
+   site:
+     title: Antora Demo site on Read the Docs
+     start_page: component-b::index.adoc
+
+   content:
+     sources:
+     - url: https://gitlab.com/antora/demo/demo-component-a.git
+       branches: HEAD
+     - url: https://gitlab.com/antora/demo/demo-component-b.git
+       branches: [v2.0, v1.0]
+       start_path: docs
+
+   ui:
+     bundle:
+       url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
+       snapshot: true
+
+Quick start
+-----------
+
+- If you have an existing Antora project you want to host on Read the Docs, check out our :doc:`/intro/add-project` guide.
+
+- If you're new to Antora, check out the official `Install and Run Antora Quickstart`_ guide.
+
+.. _Install and Run Antora Quickstart: https://docs.antora.org/antora/latest/install-and-run-quickstart/
+
+Example repository and demo
+---------------------------
+
+Example repository
+    https://github.com/readthedocs/test-builds/tree/antora
+
+Demo
+    https://test-builds.readthedocs.io/en/antora/
+
+Further reading
+---------------
+
+* `Antora documentation`_
+
+.. _Antora documentation: https://docs.antora.org

docs/user/intro/doctools.rst

@@ -29,3 +29,23 @@ with more coming soon.
              :bdg-success:`rst` :bdg-success:`md`
         Written in
              :bdg-info:`python`
+
+    .. grid-item-card::  Markdoc
+        :link: markdoc.html
+
+        Markdoc is documentation tool developed by Stripe that allows you to write documentation in a custom Markdown flavor.
+
+        Supported formats
+             :bdg-success:`md`
+        Written in
+             :bdg-info:`javascript`
+
+    .. grid-item-card::  Antora
+        :link: antora.html
+
+        Antora is a powerful documentation framework that allows you to write documentation in AsciiDoc.
+
+        Supported formats
+             :bdg-success:`adoc`
+        Written in
+             :bdg-info:`javascript`

docs/user/intro/markdoc.rst

@@ -0,0 +1,87 @@
+Markdoc
+=======
+
+.. meta::
+   :description lang=en: Hosting Markdoc documentation on Read the Docs.
+
+`Markdoc`_ is a powerful documentation framework that allows you to write documentation in a flavor of Markdown.
+
+Minimal configuration is required to build an existing Markdoc project on Read the Docs.
+
+.. code-block:: yaml
+   :caption: .readthedocs.yaml
+
+    version: 2
+
+    build:
+        os: ubuntu-24.04
+        tools:
+            nodejs: "18"
+        commands:
+            # Install dependencies
+            - cd docs/ && npm install
+            # Build the site
+            - cd docs/ && npm run build
+            # Copy generated files into Read the Docs directory
+            - mkdir --parents $READTHEDOCS_OUTPUT/html/
+            - cp --verbose --recursive docs/out/* $READTHEDOCS_OUTPUT/html/
+
+.. _Markdoc: https://markdoc.io/
+
+Example configuration
+---------------------
+
+In order to build a Markdoc project on Read the Docs,
+you need to generate static HTML from the Next JS build:
+
+.. code-block:: js
+   :caption: next.config.js
+
+    const withMarkdoc = require('@markdoc/next.js');
+
+    const nextConfig = {
+        // Optional: Export HTML files instead of a Node.js server
+        output: 'export',
+
+        // Optional: Change links `/me` -> `/me/` and emit `/me.html` -> `/me/index.html`
+        trailingSlash: true,
+
+        // Ensure pages have relative asset URLs
+        assetPrefix: './',
+
+        // Ensure links are relative
+        // TODO: Make this dynamic with the Read the Docs base path,
+        // so PR builds work nicely
+        basePath: '/en/markdoc',
+    }
+
+    module.exports =
+        withMarkdoc({mode: 'static'})({
+            pageExtensions: ['js', 'jsx', 'ts', 'tsx', 'md', 'mdoc'],
+            ...nextConfig,
+    });
+
+Quick start
+-----------
+
+- If you have an existing Markdoc project you want to host on Read the Docs, check out our :doc:`/intro/add-project` guide.
+
+- If you're new to Markdoc, check out the official `Getting started with Markdoc`_ guide.
+
+.. _Getting started with Markdoc: https://markdoc.io/docs/getting-started
+
+Example repository and demo
+---------------------------
+
+Example repository
+    https://github.com/readthedocs/test-builds/tree/markdoc
+
+Demo
+    https://test-builds.readthedocs.io/en/markdoc/
+
+Further reading
+---------------
+
+* `Markdoc documentation`_
+
+.. _Markdoc documentation: https://markdoc.io/docs