Docusaurus basics (#11752)

Not a lot of info here, but probably worth pushing out anyway  --- :books: Documentation previews :books: - User's documentation (`docs`): https://docs--11752.org.readthedocs.build/en/11752/   - Developer's documentation (`dev`): https://dev--11752.org.readthedocs.build/en/11752/  --------- Co-authored-by: Eric Holscher <[email protected]> Co-authored-by: Eric Holscher <[email protected]>
readthedocs · Nov 26, 2024 · 777eb1a · 777eb1a
1 parent 28d0f13
commit 777eb1a
Show file tree

Hide file tree

Showing 4 changed files with 109 additions and 12 deletions.
diff --git 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
@@ -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
@@ -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 <config-file/v2: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 </canonical-urls>` 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 <https://www.npmjs.com/package/dotenv>`__ and a
+:doc:`Read the Docs environment variable </reference/environment-variables>`:
+
+.. 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
@@ -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
 ---------------