Skip to content

Commit

Permalink
Add Markdoc to the doc tools (#11782)
Browse files Browse the repository at this point in the history
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.


<!-- readthedocs-preview docs start -->
---
:books: Documentation previews :books:

- User's documentation (`docs`):
https://docs--11782.org.readthedocs.build/en/11782/

<!-- readthedocs-preview docs end -->

<!-- readthedocs-preview dev start -->
- Developer's documentation (`dev`):
https://dev--11782.org.readthedocs.build/en/11782/

<!-- readthedocs-preview dev end -->

---------

Co-authored-by: Manuel Kaufmann <[email protected]>
Co-authored-by: Anthony <[email protected]>
  • Loading branch information
3 people authored Nov 25, 2024
1 parent 6711656 commit f0467df
Show file tree
Hide file tree
Showing 3 changed files with 108 additions and 0 deletions.
1 change: 1 addition & 0 deletions docs/user/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ Read the Docs: documentation simplified
/intro/doctools
/intro/mkdocs
/intro/sphinx
/intro/markdoc
/intro/add-project
/examples

Expand Down
10 changes: 10 additions & 0 deletions docs/user/intro/doctools.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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`
97 changes: 97 additions & 0 deletions docs/user/intro/markdoc.rst
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit f0467df

Please sign in to comment.