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/doctools.rst b/docs/user/intro/doctools.rst index 5720a1483c9..6937548c509 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 a 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..85a86bc76fe --- /dev/null +++ b/docs/user/intro/markdoc.rst @@ -0,0 +1,97 @@ +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: "22" + 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, + + // 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(/\/$/, "") + : "", + } + + module.exports = + withMarkdoc({mode: 'static'})({ + pageExtensions: ['js', 'jsx', 'ts', 'tsx', 'md', 'mdoc'], + ...nextConfig, + }); + +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.", "✅" + "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 + +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