Deploying Markdoc 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.
.readthedocs.yaml
version: 2
build:
os: ubuntu-24.04
tools:
nodejs: "22"
jobs:
install:
# Install dependencies
- cd docs/ && npm install
build:
# 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/
範例組態
In order to build a Markdoc project on Read the Docs, you need to generate static HTML from the Next.js build:
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,
});
Limitations
All Read the Docs features are supported for Markdoc projects. There may be some Markdoc features that depend on server-side rendering that are not supported.
Getting started
If you have an existing Markdoc project you want to host on Read the Docs, check out our 增添文件專案 guide.
If you're new to Markdoc, check out the official Getting started with Markdoc guide.