CINXE.COM

<!DOCTYPE html> <html class="writer-html5" lang="en" data-content_root="../"> <head> <meta charset="utf-8" /> <meta name="readthedocs-addons-api-version" content="1"><meta name="viewport" content="width=device-width, initial-scale=1" /> <meta content="Hosting Markdoc documentation on Read the Docs." lang="en" name="description" xml:lang="en" /> <meta property="og:title" content="Markdoc" /> <meta property="og:type" content="website" /> <meta property="og:url" content="https://docs.readthedocs.io/en/stable/intro/markdoc.html" /> <meta property="og:site_name" content="Read the Docs Documentation" /> <meta property="og:description" content="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..readthedocs.yaml, Example configuration: In order to build a Markdoc project on Read the Docs, you..." /> <meta property="og:image" content="https://docs.readthedocs.io/en/latest/_static/img/logo-opengraph.png" /> <meta property="og:image:alt" content="Read the Docs Documentation" /> <meta name="twitter:card" content="summary_large_image" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Markdoc — Read the Docs user documentation</title> <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" /> <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=e59714d7" /> <link rel="stylesheet" type="text/css" href="../_static/copybutton.css?v=76b2166b" /> <link rel="stylesheet" type="text/css" href="../_static/sphinx-design.min.css?v=95c83b7e" /> <link rel="stylesheet" type="text/css" href="../_static/css/custom.css?v=da32ccdd" /> <link rel="stylesheet" type="text/css" href="../_static/css/sphinx_prompt_css.css?v=351d85e3" /> <link rel="canonical" href="https://docs.readthedocs.io/en/stable/intro/markdoc.html" /> <script src="../_static/jquery.js?v=5d32c60e"></script> <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script> <script src="../_static/documentation_options.js?v=604cd17f"></script> <script src="../_static/doctools.js?v=9bcbadda"></script> <script src="../_static/sphinx_highlight.js?v=dc90522c"></script> <script src="../_static/clipboard.min.js?v=a7894cd8"></script> <script src="../_static/copybutton.js?v=f281be69"></script> <script src="../_static/design-tabs.js?v=f930bc37"></script> <script src="../_static/js/expand_tabs.js?v=1e151f68"></script> <script src="../_static/js/theme.js"></script> <script src="../_static/js/versions.js"></script> <link rel="index" title="Index" href="../genindex.html" /> <link rel="search" title="Search" href="../search.html" /> <link rel="next" title="Adding a documentation project" href="add-project.html" /> <link rel="prev" title="Sphinx" href="sphinx.html" /> <script defer data-domain="docs.readthedocs.io" src="https://plausible.io/js/script.js"></script> <script async type="text/javascript" src="/_/static/javascript/readthedocs-addons.js"></script><meta name="readthedocs-project-slug" content="docs" /><meta name="readthedocs-version-slug" content="stable" /><meta name="readthedocs-resolver-filename" content="/intro/markdoc.html" /><meta name="readthedocs-http-status" content="200" /></head> <body class="wy-body-for-nav"> <div class="wy-grid-for-nav"> <nav data-toggle="wy-nav-shift" class="wy-nav-side"> <div class="wy-side-scroll"> <div class="wy-side-nav-search" > <a href="../index.html"> <img src="../_static/logo.svg" class="logo" alt="Logo"/> </a> <div class="switch-menus"> <div class="version-switch"></div> <div class="language-switch"></div> </div> <div role="search"> <form id="rtd-search-form" class="wy-form" action="../search.html" method="get"> <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu"> <p class="caption" role="heading"><span class="caption-text">Getting started</span></p> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Read the Docs tutorial</a></li> <li class="toctree-l1"><a class="reference internal" href="doctools.html">Supported tools</a></li> <li class="toctree-l1"><a class="reference internal" href="mkdocs.html">Material for MkDocs</a></li> <li class="toctree-l1"><a class="reference internal" href="sphinx.html">Sphinx</a></li> <li class="toctree-l1 current"><a class="current reference internal" href="#">Markdoc</a><ul> <li class="toctree-l2"><a class="reference internal" href="#example-configuration">Example configuration</a></li> <li class="toctree-l2"><a class="reference internal" href="#supported-features">Supported features</a></li> <li class="toctree-l2"><a class="reference internal" href="#getting-started">Getting started</a></li> <li class="toctree-l2"><a class="reference internal" href="#example-repository-and-demo">Example repository and demo</a></li> <li class="toctree-l2"><a class="reference internal" href="#further-reading">Further reading</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="add-project.html">Adding a documentation project</a></li> <li class="toctree-l1"><a class="reference internal" href="../examples.html">Example projects</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Project setup and configuration</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="../config-file/index.html">Configuration file overview</a></li> <li class="toctree-l1"><a class="reference internal" href="../config-file/v2.html">Configuration file reference</a></li> <li class="toctree-l1"><a class="reference internal" href="../addons.html">Read the Docs Addons</a></li> <li class="toctree-l1"><a class="reference internal" href="../automation-rules.html">Automation rules</a></li> <li class="toctree-l1"><a class="reference internal" href="../guides/reproducible-builds.html">How to create reproducible builds</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Build process</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="../builds.html">Build process overview</a></li> <li class="toctree-l1"><a class="reference internal" href="../build-customization.html">Build process customization</a></li> <li class="toctree-l1"><a class="reference internal" href="../reference/git-integration.html">Git integration (GitHub, GitLab, Bitbucket)</a></li> <li class="toctree-l1"><a class="reference internal" href="../pull-requests.html">Pull request previews</a></li> <li class="toctree-l1"><a class="reference internal" href="../build-notifications.html">Build failure notifications</a></li> <li class="toctree-l1"><a class="reference internal" href="../environment-variables.html">Environment variable overview</a></li> <li class="toctree-l1"><a class="reference internal" href="../reference/environment-variables.html">Environment variable reference</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Hosting documentation</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="../versions.html">Versions</a></li> <li class="toctree-l1"><a class="reference internal" href="../subprojects.html">Subprojects</a></li> <li class="toctree-l1"><a class="reference internal" href="../localization.html">Localization and Internationalization</a></li> <li class="toctree-l1"><a class="reference internal" href="../versioning-schemes.html">URL versioning schemes</a></li> <li class="toctree-l1"><a class="reference internal" href="../custom-domains.html">Custom domains</a></li> <li class="toctree-l1"><a class="reference internal" href="../doc-notifications.html">Documentation notifications</a></li> <li class="toctree-l1"><a class="reference internal" href="../canonical-urls.html">Canonical URLs</a></li> <li class="toctree-l1"><a class="reference internal" href="../reference/cdn.html">Content Delivery Network (CDN) and caching</a></li> <li class="toctree-l1"><a class="reference internal" href="../reference/sitemaps.html">Sitemap support</a></li> <li class="toctree-l1"><a class="reference internal" href="../reference/404-not-found.html"><code class="docutils literal notranslate"><span class="pre">404</span> <span class="pre">Not</span> <span class="pre">Found</span></code> pages</a></li> <li class="toctree-l1"><a class="reference internal" href="../reference/robots.html"><code class="docutils literal notranslate"><span class="pre">robots.txt</span></code> support</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Reading documentation</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="../downloadable-documentation.html">Offline formats (PDF, ePub, HTML)</a></li> <li class="toctree-l1"><a class="reference internal" href="../doc-diff.html">DocDiff</a></li> <li class="toctree-l1"><a class="reference internal" href="../guides/embedding-content.html">How to embed content from your documentation</a></li> <li class="toctree-l1"><a class="reference internal" href="../server-side-search/index.html">Server side search</a></li> <li class="toctree-l1"><a class="reference internal" href="../server-side-search/syntax.html">Search query syntax</a></li> <li class="toctree-l1"><a class="reference internal" href="../flyout-menu.html">Flyout menu</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Maintaining projects</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="../user-defined-redirects.html">Redirects</a></li> <li class="toctree-l1"><a class="reference internal" href="../traffic-analytics.html">Traffic analytics</a></li> <li class="toctree-l1"><a class="reference internal" href="../search-analytics.html">Search analytics</a></li> <li class="toctree-l1"><a class="reference internal" href="../security-log.html">Security logs</a></li> <li class="toctree-l1"><a class="reference internal" href="../badges.html">Status badges</a></li> <li class="toctree-l1"><a class="reference internal" href="../explanation/documentation-structure.html">How to structure your documentation</a></li> <li class="toctree-l1"><a class="reference internal" href="../guides/best-practice/links.html">Best practices for linking to your documentation</a></li> <li class="toctree-l1"><a class="reference internal" href="../security-implications.html">Security considerations for documentation pages</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Business features</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="../commercial/index.html">Business hosting</a></li> <li class="toctree-l1"><a class="reference internal" href="../commercial/organizations.html">Organizations</a></li> <li class="toctree-l1"><a class="reference internal" href="../commercial/single-sign-on.html">Single Sign-On (SSO)</a></li> <li class="toctree-l1"><a class="reference internal" href="../commercial/sharing.html">Sharing private documentation</a></li> <li class="toctree-l1"><a class="reference internal" href="../commercial/subscriptions.html">How to manage your subscription</a></li> <li class="toctree-l1"><a class="reference internal" href="../commercial/privacy-level.html">Privacy Levels</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">How-to guides</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="../guides/setup/index.html">Project setup and configuration</a></li> <li class="toctree-l1"><a class="reference internal" href="../guides/build/index.html">Build process</a></li> <li class="toctree-l1"><a class="reference internal" href="../guides/maintenance/index.html">Upgrading and maintaining projects</a></li> <li class="toctree-l1"><a class="reference internal" href="../guides/content/index.html">Content, themes and SEO</a></li> <li class="toctree-l1"><a class="reference internal" href="../guides/access/index.html">Security and access</a></li> <li class="toctree-l1"><a class="reference internal" href="../guides/management/index.html">Account management</a></li> <li class="toctree-l1"><a class="reference internal" href="../guides/best-practice/index.html">Best practice</a></li> <li class="toctree-l1"><a class="reference internal" href="../guides/troubleshooting/index.html">Troubleshooting problems</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Reference</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="../api/index.html">Public REST API</a></li> <li class="toctree-l1"><a class="reference internal" href="../faq.html">Frequently asked questions</a></li> <li class="toctree-l1"><a class="reference internal" href="../changelog.html">Changelog</a></li> <li class="toctree-l1"><a class="reference internal" href="../about/index.html">About Read the Docs</a></li> <li class="toctree-l1"><a class="reference external" href="https://dev.readthedocs.io">Developer Documentation</a></li> <li class="toctree-l1"><a class="reference external" href="https://about.readthedocs.com">Read the Docs website</a></li> </ul> </div> </div> </nav> <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" > <i data-toggle="wy-nav-top" class="fa fa-bars"></i> <a href="../index.html">Read the Docs user documentation</a> </nav> <div class="wy-nav-content"> <div class="rst-content"> <div role="navigation" aria-label="Page navigation"> <ul class="wy-breadcrumbs"> <li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li> <li class="breadcrumb-item active">Markdoc</li> <li class="wy-breadcrumbs-aside"> <a href="https://github.com/readthedocs/readthedocs.org/blob/main/docs/user/intro/markdoc.rst" class="fa fa-github"> Edit on GitHub</a> </li> </ul> <hr/> </div> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> <div itemprop="articleBody"> <section id="markdoc"> <h1>Markdoc<a class="headerlink" href="#markdoc" title="Link to this heading"></a></h1> <p><a class="reference external" href="https://markdoc.io/">Markdoc</a> is a powerful documentation framework that allows you to write documentation in a flavor of Markdown.</p> <p>Minimal configuration is required to build an existing Markdoc project on Read the Docs.</p> <div class="literal-block-wrapper docutils container" id="id2"> <div class="code-block-caption"><span class="caption-text">.readthedocs.yaml</span><a class="headerlink" href="#id2" title="Link to this code"></a></div> <div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="w"> </span><span class="nt">version</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">2</span> <span class="w"> </span><span class="nt">build</span><span class="p">:</span> <span class="w"> </span><span class="nt">os</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ubuntu-24.04</span> <span class="w"> </span><span class="nt">tools</span><span class="p">:</span> <span class="w"> </span><span class="nt">nodejs</span><span class="p">:</span><span class="w"> </span><span class="s">"22"</span> <span class="w"> </span><span class="nt">commands</span><span class="p">:</span> <span class="w"> </span><span class="c1"># Install dependencies</span> <span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">cd docs/ && npm install</span> <span class="w"> </span><span class="c1"># Build the site</span> <span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">cd docs/ && npm run build</span> <span class="w"> </span><span class="c1"># Copy generated files into Read the Docs directory</span> <span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">mkdir --parents $READTHEDOCS_OUTPUT/html/</span> <span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">cp --verbose --recursive docs/out/* $READTHEDOCS_OUTPUT/html/</span> </pre></div> </div> </div> <section id="example-configuration"> <h2>Example configuration<a class="headerlink" href="#example-configuration" title="Link to this heading"></a></h2> <p>In order to build a Markdoc project on Read the Docs, you need to generate static HTML from the Next JS build:</p> <div class="literal-block-wrapper docutils container" id="id3"> <div class="code-block-caption"><span class="caption-text">next.config.js</span><a class="headerlink" href="#id3" title="Link to this code"></a></div> <div class="highlight-js notranslate"><div class="highlight"><pre><span></span><span class="w"> </span><span class="kd">const</span><span class="w"> </span><span class="nx">withMarkdoc</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">require</span><span class="p">(</span><span class="s1">'@markdoc/next.js'</span><span class="p">);</span> <span class="w"> </span><span class="kd">const</span><span class="w"> </span><span class="nx">nextConfig</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span> <span class="w"> </span><span class="c1">// Optional: Export HTML files instead of a Node.js server</span> <span class="w"> </span><span class="nx">output</span><span class="o">:</span><span class="w"> </span><span class="s1">'export'</span><span class="p">,</span> <span class="w"> </span><span class="c1">// Optional: Change links `/me` -> `/me/` and emit `/me.html` -> `/me/index.html`</span> <span class="w"> </span><span class="nx">trailingSlash</span><span class="o">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span> <span class="w"> </span><span class="c1">// Use Canonical URL, but only the path and with no trailing /</span> <span class="w"> </span><span class="c1">// End result is like: `/en/latest`</span> <span class="w"> </span><span class="nx">basePath</span><span class="o">:</span><span class="w"> </span><span class="nx">process</span><span class="p">.</span><span class="nx">env</span><span class="p">.</span><span class="nx">READTHEDOCS_CANONICAL_URL</span> <span class="w"> </span><span class="o">?</span><span class="w"> </span><span class="ow">new</span><span class="w"> </span><span class="nx">URL</span><span class="p">(</span><span class="nx">process</span><span class="p">.</span><span class="nx">env</span><span class="p">.</span><span class="nx">READTHEDOCS_CANONICAL_URL</span><span class="p">).</span><span class="nx">pathname</span><span class="p">.</span><span class="nx">replace</span><span class="p">(</span><span class="sr">/\/$/</span><span class="p">,</span><span class="w"> </span><span class="s2">""</span><span class="p">)</span> <span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span> <span class="w"> </span><span class="p">}</span> <span class="w"> </span><span class="nx">module</span><span class="p">.</span><span class="nx">exports</span><span class="w"> </span><span class="o">=</span> <span class="w"> </span><span class="nx">withMarkdoc</span><span class="p">({</span><span class="nx">mode</span><span class="o">:</span><span class="w"> </span><span class="s1">'static'</span><span class="p">})({</span> <span class="w"> </span><span class="nx">pageExtensions</span><span class="o">:</span><span class="w"> </span><span class="p">[</span><span class="s1">'js'</span><span class="p">,</span><span class="w"> </span><span class="s1">'jsx'</span><span class="p">,</span><span class="w"> </span><span class="s1">'ts'</span><span class="p">,</span><span class="w"> </span><span class="s1">'tsx'</span><span class="p">,</span><span class="w"> </span><span class="s1">'md'</span><span class="p">,</span><span class="w"> </span><span class="s1">'mdoc'</span><span class="p">],</span> <span class="w"> </span><span class="p">...</span><span class="nx">nextConfig</span><span class="p">,</span> <span class="w"> </span><span class="p">});</span> </pre></div> </div> </div> </section> <section id="supported-features"> <h2>Supported features<a class="headerlink" href="#supported-features" title="Link to this heading"></a></h2> <table class="docutils align-default" id="id4"> <caption><span class="caption-text">Supported features</span><a class="headerlink" href="#id4" title="Link to this table"></a></caption> <thead> <tr class="row-odd"><th class="head"><p>Feature</p></th> <th class="head"><p>Description</p></th> <th class="head"><p>Supported</p></th> </tr> </thead> <tbody> <tr class="row-even"><td><p>Pull request previews</p></td> <td><p>Preview changes to your documentation before merging.</p></td> <td><p>✅</p></td> </tr> <tr class="row-odd"><td><p>Versioning</p></td> <td><p>Supports multiple versions of your documentation.</p></td> <td><p>✅</p></td> </tr> <tr class="row-even"><td><p>Search</p></td> <td><p>Provides full-text search capabilities.</p></td> <td><p>✅</p></td> </tr> <tr class="row-odd"><td><p>Flyout menu</p></td> <td><p>Provides a flyout menu for navigation.</p></td> <td><p>✅</p></td> </tr> <tr class="row-even"><td><p>Offline formats</p></td> <td><p>Generates PDF and EPUB formats.</p></td> <td><p>✅</p></td> </tr> <tr class="row-odd"><td><p>Localization</p></td> <td><p>Supports multiple languages.</p></td> <td><p>✅</p></td> </tr> </tbody> </table> </section> <section id="getting-started"> <h2>Getting started<a class="headerlink" href="#getting-started" title="Link to this heading"></a></h2> <ul class="simple"> <li><p>If you have an existing Markdoc project you want to host on Read the Docs, check out our <a class="reference internal" href="add-project.html"><span class="doc">Adding a documentation project</span></a> guide.</p></li> <li><p>If you’re new to Markdoc, check out the official <a class="reference external" href="https://markdoc.io/docs/getting-started">Getting started with Markdoc</a> guide.</p></li> </ul> </section> <section id="example-repository-and-demo"> <h2>Example repository and demo<a class="headerlink" href="#example-repository-and-demo" title="Link to this heading"></a></h2> <dl class="simple"> <dt>Example repository</dt><dd><p><a class="reference external" href="https://github.com/readthedocs/test-builds/tree/markdoc">https://github.com/readthedocs/test-builds/tree/markdoc</a></p> </dd> <dt>Demo</dt><dd><p><a class="reference external" href="https://test-builds.readthedocs.io/en/markdoc/">https://test-builds.readthedocs.io/en/markdoc/</a></p> </dd> </dl> </section> <section id="further-reading"> <h2>Further reading<a class="headerlink" href="#further-reading" title="Link to this heading"></a></h2> <ul class="simple"> <li><p><a class="reference external" href="https://markdoc.io/docs">Markdoc documentation</a></p></li> </ul> </section> </section> </div> </div> <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> <a href="sphinx.html" class="btn btn-neutral float-left" title="Sphinx" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> <a href="add-project.html" class="btn btn-neutral float-right" title="Adding a documentation project" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> </div> <hr/> <div role="contentinfo"> <p>© Copyright Read the Docs, Inc & contributors.</p> </div> Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. </footer> </div> </div> </section> </div> <script> jQuery(function () { SphinxRtdTheme.Navigation.enable(true); }); </script> </body> </html>