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