From b6254f71a194846fec98a87f252d3062f9be5815 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Wed, 20 Nov 2024 15:36:12 -0800 Subject: [PATCH 01/12] 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 02/12] 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 671dc0871bc2979fb82548f1274d430be5e1481d Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Thu, 21 Nov 2024 09:13:31 -0800 Subject: [PATCH 03/12] Apply suggestions from code review Co-authored-by: Manuel Kaufmann --- docs/user/intro/doctools.rst | 2 +- docs/user/intro/markdoc.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user/intro/doctools.rst b/docs/user/intro/doctools.rst index 4ad5ddabad5..6937548c509 100644 --- a/docs/user/intro/doctools.rst +++ b/docs/user/intro/doctools.rst @@ -33,7 +33,7 @@ with more coming soon. .. 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. + Markdoc is a documentation tool developed by Stripe that allows you to write documentation in a custom Markdown flavor. Supported formats :bdg-success:`md` diff --git a/docs/user/intro/markdoc.rst b/docs/user/intro/markdoc.rst index aae91ae493a..acfba6e7a4f 100644 --- a/docs/user/intro/markdoc.rst +++ b/docs/user/intro/markdoc.rst @@ -16,7 +16,7 @@ Minimal configuration is required to build an existing Markdoc project on Read t build: os: ubuntu-24.04 tools: - nodejs: "18" + nodejs: "22" commands: # Install dependencies - cd docs/ && npm install From 7f67d214d35d2ef28344f9adbc0f4e3d8878432b Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Thu, 21 Nov 2024 09:48:52 -0800 Subject: [PATCH 04/12] Update docs/user/intro/markdoc.rst --- docs/user/intro/markdoc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/intro/markdoc.rst b/docs/user/intro/markdoc.rst index acfba6e7a4f..596afa83863 100644 --- a/docs/user/intro/markdoc.rst +++ b/docs/user/intro/markdoc.rst @@ -52,7 +52,7 @@ you need to generate static HTML from the Next JS build: // Ensure links are relative // TODO: Make this dynamic with the Read the Docs base path, // so PR builds work nicely - basePath: '/en/markdoc', + basePath: process.env.READTHEDOCS_CANONICAL_URL || '',``` } module.exports = From 6be07b538d1e7aeeeefe634f2358f2b4d9955a62 Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Thu, 21 Nov 2024 10:30:58 -0800 Subject: [PATCH 05/12] Update docs/user/intro/markdoc.rst --- docs/user/intro/markdoc.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/user/intro/markdoc.rst b/docs/user/intro/markdoc.rst index 596afa83863..cf6499f1acb 100644 --- a/docs/user/intro/markdoc.rst +++ b/docs/user/intro/markdoc.rst @@ -45,11 +45,6 @@ you need to generate static HTML from the Next JS build: // 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: process.env.READTHEDOCS_CANONICAL_URL || '',``` From 31732c17aa598d147bca50a32b2f4cadc1cb3d82 Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Thu, 21 Nov 2024 10:31:13 -0800 Subject: [PATCH 06/12] Update docs/user/intro/markdoc.rst --- docs/user/intro/markdoc.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/user/intro/markdoc.rst b/docs/user/intro/markdoc.rst index cf6499f1acb..f702d7babac 100644 --- a/docs/user/intro/markdoc.rst +++ b/docs/user/intro/markdoc.rst @@ -45,6 +45,7 @@ you need to generate static HTML from the Next JS build: // Optional: Change links `/me` -> `/me/` and emit `/me.html` -> `/me/index.html` trailingSlash: true, + // TODO: Make this dynamic with the Read the Docs base path, // so PR builds work nicely basePath: process.env.READTHEDOCS_CANONICAL_URL || '',``` From 2d1df1302c4a611385fa79d835f9b2e24ae3cbe8 Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Thu, 21 Nov 2024 10:31:40 -0800 Subject: [PATCH 07/12] Update docs/user/intro/markdoc.rst --- docs/user/intro/markdoc.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/user/intro/markdoc.rst b/docs/user/intro/markdoc.rst index f702d7babac..c75f906d61d 100644 --- a/docs/user/intro/markdoc.rst +++ b/docs/user/intro/markdoc.rst @@ -46,8 +46,7 @@ you need to generate static HTML from the Next JS build: // Optional: Change links `/me` -> `/me/` and emit `/me.html` -> `/me/index.html` trailingSlash: true, - // TODO: Make this dynamic with the Read the Docs base path, - // so PR builds work nicely + // Use the proper base path for prod and PR builds. basePath: process.env.READTHEDOCS_CANONICAL_URL || '',``` } From 12bb32bf7c76f62834f12237a8cd3e4f46ef02e0 Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Thu, 21 Nov 2024 11:12:40 -0800 Subject: [PATCH 08/12] Update docs/user/intro/markdoc.rst --- docs/user/intro/markdoc.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/user/intro/markdoc.rst b/docs/user/intro/markdoc.rst index c75f906d61d..a136430ab99 100644 --- a/docs/user/intro/markdoc.rst +++ b/docs/user/intro/markdoc.rst @@ -46,8 +46,10 @@ you need to generate static HTML from the Next JS build: // Optional: Change links `/me` -> `/me/` and emit `/me.html` -> `/me/index.html` trailingSlash: true, - // Use the proper base path for prod and PR builds. - basePath: process.env.READTHEDOCS_CANONICAL_URL || '',``` + // Use Canonical URL, but only the path and with no trailing / + basePath: process.env.READTHEDOCS_CANONICAL_URL + ? new URL(process.env.READTHEDOCS_CANONICAL_URL).pathname.replace(/\/$/, "") + : "", } module.exports = From e016dd95b49c32c668567df9d669c4ac0bdaa07b Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Thu, 21 Nov 2024 13:45:57 -0800 Subject: [PATCH 09/12] Add Supported Features --- docs/user/intro/markdoc.rst | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/docs/user/intro/markdoc.rst b/docs/user/intro/markdoc.rst index a136430ab99..ea03261e164 100644 --- a/docs/user/intro/markdoc.rst +++ b/docs/user/intro/markdoc.rst @@ -58,11 +58,23 @@ you need to generate static HTML from the Next JS build: ...nextConfig, }); -Quick start ------------ +Supported Features +------------------ -- If you have an existing Markdoc project you want to host on Read the Docs, check out our :doc:`/intro/add-project` guide. +.. csv-table:: Supported Features + :header: "Feature", "Description", "Supported" + + "Pull request previews", "Preview changes to your documentation before merging.", "✅" + "Versioning", "Supports multiple versions of your documentation.", "✅" + "Search", "Provides full-text search capabilities.", "✅" + "Flyout menu", "Provides a flyout menu for navigation.", "✅" + "Offline formats", "Generates PDF and ePub formats.", "❌" + "Localization", "Supports multiple languages.", "❌" +Getting started +--------------- + +- 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 From 023460817ae662b0f4e21e48b3bfff8bb7664325 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Thu, 21 Nov 2024 13:49:39 -0800 Subject: [PATCH 10/12] Fix whitespace --- docs/user/intro/markdoc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/intro/markdoc.rst b/docs/user/intro/markdoc.rst index ea03261e164..d519bbbdc86 100644 --- a/docs/user/intro/markdoc.rst +++ b/docs/user/intro/markdoc.rst @@ -45,7 +45,7 @@ you need to generate static HTML from the Next JS build: // Optional: Change links `/me` -> `/me/` and emit `/me.html` -> `/me/index.html` trailingSlash: true, - + // Use Canonical URL, but only the path and with no trailing / basePath: process.env.READTHEDOCS_CANONICAL_URL ? new URL(process.env.READTHEDOCS_CANONICAL_URL).pathname.replace(/\/$/, "") From a729ada1d970754dcec3dfeb0ff5f3addfac04a3 Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Mon, 25 Nov 2024 08:41:53 -0800 Subject: [PATCH 11/12] Apply suggestions from code review Co-authored-by: Anthony --- docs/user/intro/markdoc.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/user/intro/markdoc.rst b/docs/user/intro/markdoc.rst index d519bbbdc86..a1668ff7dd1 100644 --- a/docs/user/intro/markdoc.rst +++ b/docs/user/intro/markdoc.rst @@ -58,17 +58,17 @@ you need to generate static HTML from the Next JS build: ...nextConfig, }); -Supported Features +Supported features ------------------ -.. csv-table:: Supported Features +.. csv-table:: Supported features :header: "Feature", "Description", "Supported" "Pull request previews", "Preview changes to your documentation before merging.", "✅" "Versioning", "Supports multiple versions of your documentation.", "✅" "Search", "Provides full-text search capabilities.", "✅" "Flyout menu", "Provides a flyout menu for navigation.", "✅" - "Offline formats", "Generates PDF and ePub formats.", "❌" + "Offline formats", "Generates PDF and EPUB formats.", "❌" "Localization", "Supports multiple languages.", "❌" Getting started From 7bb66e4f830c900146a50d45e24414f7798e9f80 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Mon, 25 Nov 2024 08:43:16 -0800 Subject: [PATCH 12/12] Review feedback --- docs/user/intro/markdoc.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/user/intro/markdoc.rst b/docs/user/intro/markdoc.rst index a1668ff7dd1..85a86bc76fe 100644 --- a/docs/user/intro/markdoc.rst +++ b/docs/user/intro/markdoc.rst @@ -47,6 +47,7 @@ you need to generate static HTML from the Next JS build: trailingSlash: true, // Use Canonical URL, but only the path and with no trailing / + // End result is like: `/en/latest` basePath: process.env.READTHEDOCS_CANONICAL_URL ? new URL(process.env.READTHEDOCS_CANONICAL_URL).pathname.replace(/\/$/, "") : "", @@ -68,8 +69,8 @@ Supported features "Versioning", "Supports multiple versions of your documentation.", "✅" "Search", "Provides full-text search capabilities.", "✅" "Flyout menu", "Provides a flyout menu for navigation.", "✅" - "Offline formats", "Generates PDF and EPUB formats.", "❌" - "Localization", "Supports multiple languages.", "❌" + "Offline formats", "Generates PDF and EPUB formats.", "✅" + "Localization", "Supports multiple languages.", "✅" Getting started ---------------