-
-
Notifications
You must be signed in to change notification settings - Fork 3.6k
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
Docusaurus basics #11752
Changes from 2 commits
Commits
Show all changes
8 commits
Select commit
Hold shift + click to select a range
a82fe69
Docusaurus basics
plaindocs 75061d3
Add Supported Features
ericholscher cdfeb52
Update supported features
ericholscher 239240a
Merge branch 'main' into sam/docusaurus
ericholscher 9e128a1
Fix spacing
ericholscher 5dd2b42
Features -> limitations
ericholscher fced4f1
Merge branch 'main' of github.com:readthedocs/readthedocs.org into sa…
ericholscher 8c43fd8
features -> limitations for Markdoc as well
ericholscher File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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/ | ||
|
||
.. _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/ |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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: