From a82fe693111507cd66a50652f9150a7bb5c66ac0 Mon Sep 17 00:00:00 2001 From: Sam Wright Date: Thu, 7 Nov 2024 15:40:35 +0000 Subject: [PATCH 1/6] Docusaurus basics --- docs/user/index.rst | 1 + docs/user/intro/doctools.rst | 10 ++++ docs/user/intro/docusaurus.rst | 84 ++++++++++++++++++++++++++++++++++ 3 files changed, 95 insertions(+) create mode 100644 docs/user/intro/docusaurus.rst diff --git a/docs/user/index.rst b/docs/user/index.rst index bbc08655101..13a36d42891 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/add-project /examples diff --git a/docs/user/intro/doctools.rst b/docs/user/intro/doctools.rst index 5720a1483c9..df82e4cb2cc 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:: 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` diff --git a/docs/user/intro/docusaurus.rst b/docs/user/intro/docusaurus.rst new file mode 100644 index 00000000000..541a2ef1464 --- /dev/null +++ b/docs/user/intro/docusaurus.rst @@ -0,0 +1,84 @@ + +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/ + + +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/ From 75061d33728ce98569dfcfaae8f24600416883f9 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Thu, 21 Nov 2024 13:47:43 -0800 Subject: [PATCH 2/6] Add Supported Features --- docs/user/intro/docusaurus.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/user/intro/docusaurus.rst b/docs/user/intro/docusaurus.rst index 541a2ef1464..e0cd64b4a4f 100644 --- a/docs/user/intro/docusaurus.rst +++ b/docs/user/intro/docusaurus.rst @@ -34,6 +34,19 @@ build the site, and copy the output to $READTHEDOCS_OUTPUT: .. _Docusaurus: https://docusaurus.io/ +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.", "✅" + "Flyout menu", "Provides a flyout menu for navigation.", "✅" + "Search", "Provides full-text search capabilities.", "❌" + "Offline formats", "Generates PDF and ePub formats.", "❌" + "Localization", "Supports multiple languages.", "❌" + Quick start ----------- From cdfeb521415ee40687d8c70f5a6eb309a5f0b16d Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Mon, 25 Nov 2024 08:45:41 -0800 Subject: [PATCH 3/6] Update supported features --- docs/user/intro/docusaurus.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/user/intro/docusaurus.rst b/docs/user/intro/docusaurus.rst index e0cd64b4a4f..3a7a13a7267 100644 --- a/docs/user/intro/docusaurus.rst +++ b/docs/user/intro/docusaurus.rst @@ -34,18 +34,19 @@ build the site, and copy the output to $READTHEDOCS_OUTPUT: .. _Docusaurus: https://docusaurus.io/ -Supported Features +Supported features ------------------ -.. csv-table:: 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.", "✅" "Flyout menu", "Provides a flyout menu for navigation.", "✅" + "Offline formats", "Generates PDF and EPUB formats.", "✅" + "Localization", "Supports multiple languages.", "✅" "Search", "Provides full-text search capabilities.", "❌" - "Offline formats", "Generates PDF and ePub formats.", "❌" - "Localization", "Supports multiple languages.", "❌" + "Files changed", "Ability to see what HTML files changes in pull request previews", "❌" Quick start From 9e128a18960800468c83a27909cdd8730d5894b8 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Mon, 25 Nov 2024 10:17:42 -0800 Subject: [PATCH 4/6] Fix spacing --- docs/user/intro/doctools.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/intro/doctools.rst b/docs/user/intro/doctools.rst index e912919a5e5..6d70d7b9378 100644 --- a/docs/user/intro/doctools.rst +++ b/docs/user/intro/doctools.rst @@ -40,7 +40,7 @@ with more coming soon. Written in :bdg-info:`React` - .. grid-item-card:: Markdoc + .. 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. From 5dd2b42f444185b15479e137b4d5722f07668392 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Mon, 25 Nov 2024 13:53:33 -0800 Subject: [PATCH 5/6] Features -> limitations --- docs/user/intro/docusaurus.rst | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/docs/user/intro/docusaurus.rst b/docs/user/intro/docusaurus.rst index 3a7a13a7267..a994b878f01 100644 --- a/docs/user/intro/docusaurus.rst +++ b/docs/user/intro/docusaurus.rst @@ -34,19 +34,14 @@ build the site, and copy the output to $READTHEDOCS_OUTPUT: .. _Docusaurus: https://docusaurus.io/ -Supported features ------------------- +Limitations +----------- -.. csv-table:: Supported features +.. csv-table:: Limitations :header: "Feature", "Description", "Supported" - "Pull request previews", "Preview changes to your documentation before merging.", "✅" - "Versioning", "Supports multiple versions of your documentation.", "✅" - "Flyout menu", "Provides a flyout menu for navigation.", "✅" - "Offline formats", "Generates PDF and EPUB formats.", "✅" - "Localization", "Supports multiple languages.", "✅" - "Search", "Provides full-text search capabilities.", "❌" - "Files changed", "Ability to see what HTML files changes in pull request previews", "❌" + "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 From 8c43fd8b39e5776e2b1321b88670813d9a916168 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Tue, 26 Nov 2024 10:06:35 -0500 Subject: [PATCH 6/6] features -> limitations for Markdoc as well --- docs/user/intro/markdoc.rst | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) 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 ---------------