Introducing Docusaurus
Introducing Docusaurus
We are very happy to introduce Docusaurus to help you manage one or many open source websites.
We created Docusaurus for the following reasons:
-
@@ -125,7 +125,7 @@
/docs/en/installation.html">Getting StartedVersioningLocalizationAdding Search
Introducing Docusaurus
Introducing Docusaurus
We are very happy to introduce Docusaurus to help you manage one or many open source websites.
We created Docusaurus for the following reasons:
-
@@ -17,7 +17,7 @@
/docs/en/installation.html">Getting StartedVersioningLocalizationAdding Search
Pages and Styles
Docusaurus provides support for writing pages as React components inside the website/pages folder which will share the same header, footer, and styles as the rest of the site.
Pages and Styles
Docusaurus provides support for writing pages as React components inside the website/pages folder which will share the same header, footer, and styles as the rest of the site.
Urls for Pages
Any .js files in website/pages will be rendered to static html using the path of the file after "pages". Files in website/pages/en will also get copied out into pages and will OVERRIDE any files of the same name in pages. For example, the page for the website/pages/en/help.js file will be found at the url ${baseUrl}en/help.js as well as the url ${baseUrl}help.js, where ${baseUrl} is the baseUrl field set in your siteConfig.js file.
Page Require Paths
@@ -92,7 +92,7 @@ Background choices:dark, highlight, lightGetting StartedVersioningLocalizationAdding SearchAdding a Blog
Initial Setup
+Adding a Blog
Initial Setup
To setup your site's blog, start by creating a blog folder within your repo's website directory.
Then, add a header link to your blog within siteConfig.js:
headerLinks: [
@@ -67,7 +67,7 @@
/docs/en/installation.html">Getting StartedVersioningLocalizationAdding SearchCLI Commands
Docusaurus provides a set of scripts to help you generate, serve, and deploy your website. These scripts can be invoked with the run command when using Yarn or npm. Some common commands are:
CLI Commands
Docusaurus provides a set of scripts to help you generate, serve, and deploy your website. These scripts can be invoked with the run command when using Yarn or npm. Some common commands are:
yarn run start: build and serve the website from a local serveryarn run examples: create example configuration files
@@ -92,7 +92,7 @@
/docs/en/installation.html">Getting StartedVersioningLocalizationAdding Search
Custom Pages
You can add pages to your site that are not part of the standard docs or blog markdown files. You can do this by adding .js files to the website/pages directory. These files are React components and the render() is called to create them, backed by CSS classes, etc.
Custom Pages
You can add pages to your site that are not part of the standard docs or blog markdown files. You can do this by adding .js files to the website/pages directory. These files are React components and the render() is called to create them, backed by CSS classes, etc.
Customizing Your Home Page
The easiest way to get started customizing your home page is to use the example site that was created when you ran the Docusaurus initialization script.
You can start your local server and go to http://localhost:3000 to see what the example home page looks like. From there, edit the website/pages/en/index.js file and its various components to use the images and text you want for your project.
Markdown Features
Markdown Headers
+Markdown Features
Markdown Headers
Documents
Documents use the following markdown header fields that are enclosed by a line --- on either side:
id: A unique document id. If this field is not present, the document's id will default to its file name (without the extension).
Installation
Docusaurus was designed from the ground up to be easily installed and used to get your website up and running quickly. To install Docusaurus, we have created an easy script that will get all of the infrastructure setup for you:
+Installation
Docusaurus was designed from the ground up to be easily installed and used to get your website up and running quickly. To install Docusaurus, we have created an easy script that will get all of the infrastructure setup for you:
Ensure you have the latest version of Node installed. We also recommend you install Yarn as well.
@@ -55,7 +55,7 @@ /docs/en/installation.html">Getting StartedVersioningLocalizationAdding Search
Navigation and Sidebars
Referencing Site Documents
+Navigation and Sidebars
Referencing Site Documents
If you want to reference another document in your docs folder (or the location you set via the optional customDocsPath path site configuration option), then you just use the name of the document you want to reference.
For example, if you are in doc2.md and you want to reference doc1.md:
I am referencing a [document](doc1.md).
@@ -132,7 +132,7 @@
/docs/en/installation.html">Getting StartedVersioningLocalizationAdding SearchPublishing your site
You should now have a site up and running locally. Once you have customized it to your liking, it's time to publish it. Docusaurus generates a static HTML website that is ready to be served by your favorite web server or online hosting solution.
+Publishing your site
You should now have a site up and running locally. Once you have customized it to your liking, it's time to publish it. Docusaurus generates a static HTML website that is ready to be served by your favorite web server or online hosting solution.
Building Static HTML Pages
To create a static build of your website, run the following script from the website directory:
yarn run build # or `npm run build`
@@ -131,7 +131,7 @@
/docs/en/installation.html">Getting StartedVersioningLocalizationAdding SearchEnabling Search
Docusaurus supports search using Algolia DocSearch. Once you have set up your site, enter your site information to have Algolia crawl your website's documentation pages. Algolia will then send you an API key and index name for your site.
+Enabling Search
Docusaurus supports search using Algolia DocSearch. Once you have set up your site, enter your site information to have Algolia crawl your website's documentation pages. Algolia will then send you an API key and index name for your site.
Enabling the Search Bar
Enter your search-only API key and index name into siteConfig.js in the algolia section to enable search for your site.
const siteConfig = {
@@ -51,7 +51,7 @@
/docs/en/installation.html">Getting StartedVersioningLocalizationAdding SearchsiteConfig.js
A large part of site configuration is done by editing the siteConfig.js file.
siteConfig.js
A large part of site configuration is done by editing the siteConfig.js file.
User Showcase
The users array is used to store objects for each project/user that you want to show on your site. Currently this field is used by example the pages/en/index.js and pages/en/users.js files provided. Each user object should have caption, image, infoLink, and pinned fields. The caption is the text showed when someone hovers over the image of that user, and the infoLink is where clicking the image will bring someone. The pinned field determines whether or not it shows up on the index page.
Currently this users array is used only by the index.js and users.js example files. If you do not wish to have a users page or show users on the index page, you may remove this section.
Creating your site
Docusaurus was created to hopefully make it super simple for you to create a site and documentation for your open source project.
+Creating your site
Docusaurus was created to hopefully make it super simple for you to create a site and documentation for your open source project.
After installation and preparation, much of the work to create a basic site for your docs is already complete.
Site Structure
Your site structure looks like the following:
@@ -58,7 +58,7 @@ yarn run start # Getting StartedVersioningLocalizationAdding SearchSite Preparation
After installing Docusaurus, you now have a skeleton to work from for your specific website. The following discusses the rest of the Docusaurus structure in order for you to prepare your site.
+Site Preparation
After installing Docusaurus, you now have a skeleton to work from for your specific website. The following discusses the rest of the Docusaurus structure in order for you to prepare your site.
Directory Structure
As shown after you installed Docusaurus, the initialization script created a directory structure similar to:
root-of-repo
@@ -44,7 +44,7 @@
/docs/en/installation.html">Getting StartedVersioningLocalizationAdding SearchTranslations & Localization
Docusaurus allows for easy translation functionality using Crowdin. Documentation files written in English are uploaded to Crowdin for translation by users within a community. Top-level pages written with English strings can be translated by wrapping any strings you want to translate in a <translate> tag. Other titles and labels will also be found and properly translated.
Translations & Localization
Docusaurus allows for easy translation functionality using Crowdin. Documentation files written in English are uploaded to Crowdin for translation by users within a community. Top-level pages written with English strings can be translated by wrapping any strings you want to translate in a <translate> tag. Other titles and labels will also be found and properly translated.
Docusaurus Translation Configurations
To generate example files for translations with Docusaurus, run the examples script with the command line argument translations:
npm run examples translations
@@ -186,7 +186,7 @@ const translate = require("../../server/translate.js").translate;
/docs/en/installation.html">Getting StartedVersioningLocalizationAdding SearchVersioning
You can use the version script to cut a new documentation version based on the latest content in the docs folder. That specific set of documentation will then be preserved and accessible even as the documentation in the docs folder changes moving forward.
Versioning
You can use the version script to cut a new documentation version based on the latest content in the docs folder. That specific set of documentation will then be preserved and accessible even as the documentation in the docs folder changes moving forward.
How to Create New Versions
Run the following script to generate a starter versions page listing all the site versions:
yarn examples versions
@@ -55,7 +55,7 @@
/docs/en/installation.html">Getting StartedVersioningLocalizationAdding Search