diff --git a/docs/user/index.rst b/docs/user/index.rst index f2f6fd5141d..953e5b21a61 100644 --- a/docs/user/index.rst +++ b/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 diff --git a/docs/user/intro/antora.rst b/docs/user/intro/antora.rst new file mode 100644 index 00000000000..9442c71486c --- /dev/null +++ b/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 diff --git a/docs/user/intro/doctools.rst b/docs/user/intro/doctools.rst index 5720a1483c9..8a83f4f8539 100644 --- a/docs/user/intro/doctools.rst +++ b/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` diff --git a/docs/user/intro/markdoc.rst b/docs/user/intro/markdoc.rst new file mode 100644 index 00000000000..aae91ae493a --- /dev/null +++ b/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