From f0467dfe9e74f3f4a4a8ddc66acb2d8d6c1a9a90 Mon Sep 17 00:00:00 2001
From: Eric Holscher <25510+ericholscher@users.noreply.github.com>
Date: Mon, 25 Nov 2024 08:51:06 -0800
Subject: [PATCH] Add Markdoc to the doc tools (#11782)

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 <humitos@gmail.com>
Co-authored-by: Anthony <aj@ohess.org>
---
 docs/user/index.rst          |  1 +
 docs/user/intro/doctools.rst | 10 ++++
 docs/user/intro/markdoc.rst  | 97 ++++++++++++++++++++++++++++++++++++
 3 files changed, 108 insertions(+)
 create mode 100644 docs/user/intro/markdoc.rst

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