Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docusaurus basics #11752

Merged
merged 8 commits into from
Nov 26, 2024
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/user/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ Read the Docs: documentation simplified
/intro/doctools
/intro/mkdocs
/intro/sphinx
/intro/docusaurus
/intro/add-project
/examples

Expand Down
10 changes: 10 additions & 0 deletions docs/user/intro/doctools.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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`
97 changes: 97 additions & 0 deletions docs/user/intro/docusaurus.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@

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/
Comment on lines +22 to +33
Copy link
Member

@humitos humitos Nov 11, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Once we merge and deploy #11710 this would be as following:

build:
  install:
    - cd docs/ && npm install
  build:
    html:
      - cd docs/ && npm run build
  post_build:
    - mkdir --parents $READTHEDOCS_OUTPUT/html/
    - cp --recursive docs/build/* $READTHEDOCS_OUTPUT/html/


.. _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.", "❌"
ericholscher marked this conversation as resolved.
Show resolved Hide resolved
"Localization", "Supports multiple languages.", "❌"
ericholscher marked this conversation as resolved.
Show resolved Hide resolved


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/