From b6254f71a194846fec98a87f252d3062f9be5815 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Wed, 20 Nov 2024 15:36:12 -0800 Subject: [PATCH 1/4] Add Markdoc to the doc tools This highlights the test-builds repo, and contains the basic config to make it build on RTD. This doesn't address any integration info, but I wanted to get a basic page up to start getting SEO. --- docs/user/intro/doctools.rst | 10 ++++ docs/user/intro/markdoc.rst | 90 ++++++++++++++++++++++++++++++++++++ 2 files changed, 100 insertions(+) create mode 100644 docs/user/intro/markdoc.rst diff --git a/docs/user/intro/doctools.rst b/docs/user/intro/doctools.rst index 5720a1483c9..4ad5ddabad5 100644 --- a/docs/user/intro/doctools.rst +++ b/docs/user/intro/doctools.rst @@ -29,3 +29,13 @@ 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` diff --git a/docs/user/intro/markdoc.rst b/docs/user/intro/markdoc.rst new file mode 100644 index 00000000000..00c268f18f7 --- /dev/null +++ b/docs/user/intro/markdoc.rst @@ -0,0 +1,90 @@ + +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:: yaml + :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 From 0f184f9a005ada076dddebe9e03e66f360bf5019 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Wed, 20 Nov 2024 15:40:11 -0800 Subject: [PATCH 2/4] Add to toctree --- docs/user/index.rst | 1 + docs/user/intro/markdoc.rst | 5 +---- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/user/index.rst b/docs/user/index.rst index f2f6fd5141d..19d27abd0b0 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -10,6 +10,7 @@ Read the Docs: documentation simplified /intro/doctools /intro/mkdocs /intro/sphinx + /intro/markdoc /intro/add-project /examples diff --git a/docs/user/intro/markdoc.rst b/docs/user/intro/markdoc.rst index 00c268f18f7..aae91ae493a 100644 --- a/docs/user/intro/markdoc.rst +++ b/docs/user/intro/markdoc.rst @@ -1,4 +1,3 @@ - Markdoc ======= @@ -35,7 +34,7 @@ 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:: yaml +.. code-block:: js :caption: next.config.js const withMarkdoc = require('@markdoc/next.js'); @@ -62,8 +61,6 @@ you need to generate static HTML from the Next JS build: ...nextConfig, }); - - Quick start ----------- From f8190203caa3c41a16d550a0e1cb8837be6ed2c0 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Wed, 20 Nov 2024 15:51:52 -0800 Subject: [PATCH 3/4] Add Antora docs This is just a basic outline pointing at our existing test-builds content. --- docs/user/intro/antora.rst | 77 ++++++++++++++++++++++++++++++++++++ docs/user/intro/doctools.rst | 10 +++++ 2 files changed, 87 insertions(+) create mode 100644 docs/user/intro/antora.rst 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 4ad5ddabad5..87b24bb384e 100644 --- a/docs/user/intro/doctools.rst +++ b/docs/user/intro/doctools.rst @@ -39,3 +39,13 @@ with more coming soon. :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` `ruby` From 5fe5335b8380e00b2cef42bb3c98ff88c31302be Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Wed, 20 Nov 2024 15:54:13 -0800 Subject: [PATCH 4/4] Add toctree --- docs/user/index.rst | 1 + docs/user/intro/doctools.rst | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/user/index.rst b/docs/user/index.rst index 19d27abd0b0..953e5b21a61 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -11,6 +11,7 @@ Read the Docs: documentation simplified /intro/mkdocs /intro/sphinx /intro/markdoc + /intro/antora /intro/add-project /examples diff --git a/docs/user/intro/doctools.rst b/docs/user/intro/doctools.rst index 87b24bb384e..8a83f4f8539 100644 --- a/docs/user/intro/doctools.rst +++ b/docs/user/intro/doctools.rst @@ -48,4 +48,4 @@ with more coming soon. Supported formats :bdg-success:`adoc` Written in - :bdg-info:`javascript` `ruby` + :bdg-info:`javascript`