diff --git a/docs/user/index.rst b/docs/user/index.rst index 19d27abd0b0..3a7f1857b32 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/docusaurus /intro/markdoc /intro/add-project /examples diff --git a/docs/user/intro/doctools.rst b/docs/user/intro/doctools.rst index 6937548c509..6d70d7b9378 100644 --- a/docs/user/intro/doctools.rst +++ b/docs/user/intro/doctools.rst @@ -30,6 +30,16 @@ with more coming soon. Written in :bdg-info:`python` + .. grid-item-card:: Docusarus + :link: docusaurus.html + + Docusaurus is a static-site generator that builds a single-page application with fast client-side navigation and out-of-the-box documentation features. + + Supported formats + :bdg-success:`mdx` :bdg-success:`md` + Written in + :bdg-info:`React` + .. grid-item-card:: Markdoc :link: markdoc.html diff --git a/docs/user/intro/docusaurus.rst b/docs/user/intro/docusaurus.rst new file mode 100644 index 00000000000..a994b878f01 --- /dev/null +++ b/docs/user/intro/docusaurus.rst @@ -0,0 +1,93 @@ + +Docusarus +========= + +.. meta:: + :description lang=en: Hosting Docusaurus sites on Read the Docs. + +`Docusaurus`_ is a static-site generator that builds a single-page application with fast client-side navigation and out-of-the-box documentation features. + +Minimal configuration required to build a Docusaurus project on Read the Docs looks like this, +specifying a nodejs toolchain on Ubuntu, using multiple :ref:`build ` commands to install the requirements, +build the site, and copy the output to $READTHEDOCS_OUTPUT: + +.. code-block:: yaml + :caption: .readthedocs.yaml + + version: 2 + build: + os: "ubuntu-22.04" + tools: + nodejs: "18" + commands: + # "docs/" was created following the Docusaurus tutorial: + # npx create-docusaurus@latest docs classic + # but you can just use your existing Docusaurus site + # + # Install Docusaurus 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 --recursive docs/build/* $READTHEDOCS_OUTPUT/html/ + +.. _Docusaurus: https://docusaurus.io/ + +Limitations +----------- + +.. csv-table:: Limitations + :header: "Feature", "Description", "Supported" + + "Search", "Provides full-text search capabilities.", "Not supported" + "Files changed", "Ability to see what HTML files changes in pull request previews", "Not supported" + + +Quick start +----------- + +- If you have an existing Docusaurus project you want to host on Read the Docs, check out our :doc:`/intro/add-project` guide. + +- If you're new to Docusaurus, check out the official `Fast Track`_ guide. + +.. _Fast Track: https://docusaurus.io/docs#fast-track + +Configuring Docusaurus and Read the Docs addons +----------------------------------------------- + +For optimal integration with Read the Docs, make the optional following configuration changes to your Docusaurus config. + +.. contents:: + :depth: 1 + :local: + :backlinks: none + +Set the canonical URL +~~~~~~~~~~~~~~~~~~~~~ + +A :doc:`canonical URL ` allows you to specify the preferred version of a web page +to prevent duplicated content. + +Set your Docusaurus `url`_ to your Read the Docs canonical URL using `dotenv `__ and a +:doc:`Read the Docs environment variable `: + +.. code-block:: js + :caption: docusaurus.config.js + + import 'dotenv/config'; + + export default { + url: process.env.READTHEDOCS_CANONICAL_URL, + }; + +.. _url: https://docusaurus.io/docs/configuration#syntax-to-declare-docusaurus-config + +Example repository and demo +--------------------------- + +Example repository + https://github.com/readthedocs/test-builds/tree/docusaurus + +Demo + https://test-builds.readthedocs.io/en/docusaurus/ diff --git a/docs/user/intro/markdoc.rst b/docs/user/intro/markdoc.rst index 85a86bc76fe..42ef5f3654d 100644 --- a/docs/user/intro/markdoc.rst +++ b/docs/user/intro/markdoc.rst @@ -59,18 +59,11 @@ you need to generate static HTML from the Next JS build: ...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.", "✅" +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 ---------------