diff --git a/docs/en/api-pages.html b/docs/en/api-pages.html index b7a17b1b94..092ee2ae08 100644 --- a/docs/en/api-pages.html +++ b/docs/en/api-pages.html @@ -4,7 +4,7 @@ toggler.onclick = function() { nav.classList.toggle('docsSliderActive'); }; -
Edit this Doc

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 #

Docusaurus provides a few useful React components for users to write their own pages, found in the CompLibrary module. This module is provided as part of Docusaurus in node_modules/docusaurus, so to access it, pages in the pages folder are temporarily copied into node_modules/docusaurus when rendering to static html. As seen in the example files, this means that a user page at pages/en/index.js uses a require path to "../../core/CompLibrary.js" to import the provided components.

What this means to the user is that if you wish to use the CompLibrary module, make sure the require path is set correctly. For example, a page at page/mypage.js would use a path "../core/CompLibrary.js".

If you wish to use your own components inside the website folder, use process.cwd() which will refer to the website folder to construct require paths. For example, if you add a component to website/core/mycomponent.js, you can use the require path, "process.cwd() + /core/mycomponent.js".

Provided Components #

Docusaurus provides the following components in CompLibrary:

CompLibrary.Marked #

A React component that parses Markdown to html.

Example:

const Marked = CompLibrary.Marked;
+
Edit

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 #

Docusaurus provides a few useful React components for users to write their own pages, found in the CompLibrary module. This module is provided as part of Docusaurus in node_modules/docusaurus, so to access it, pages in the pages folder are temporarily copied into node_modules/docusaurus when rendering to static html. As seen in the example files, this means that a user page at pages/en/index.js uses a require path to "../../core/CompLibrary.js" to import the provided components.

What this means to the user is that if you wish to use the CompLibrary module, make sure the require path is set correctly. For example, a page at page/mypage.js would use a path "../core/CompLibrary.js".

If you wish to use your own components inside the website folder, use process.cwd() which will refer to the website folder to construct require paths. For example, if you add a component to website/core/mycomponent.js, you can use the require path, "process.cwd() + /core/mycomponent.js".

Provided Components #

Docusaurus provides the following components in CompLibrary:

CompLibrary.Marked #

A React component that parses Markdown to html.

Example:

const Marked = CompLibrary.Marked;
 
 <Marked>[Markdown syntax for a link](http://www.example.com)</Marked>

CompLibrary.Container #

A React container component using Docusaurus styles. Has optional padding and background color attributes that you can configure.

Padding choices: all, bottom, left, right, top.
Background choices: dark, highlight, light.

Example:

<Container padding={["bottom", "top"]} background="light">
   ...         
diff --git a/docs/en/blog.html b/docs/en/blog.html
index 48067f9ecb..8d8b4ece51 100644
--- a/docs/en/blog.html
+++ b/docs/en/blog.html
@@ -4,7 +4,7 @@
           toggler.onclick = function() {
             nav.classList.toggle('docsSliderActive');
           };
-
Edit this Doc

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: [
+
Edit

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: [
     ...
     {blog: true, label: 'Blog'},
     ...
diff --git a/docs/en/commands.html b/docs/en/commands.html
index ea23e06364..7cfc64595d 100644
--- a/docs/en/commands.html
+++ b/docs/en/commands.html
@@ -4,7 +4,7 @@
           toggler.onclick = function() {
             nav.classList.toggle('docsSliderActive');
           };
-
Edit this Doc

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:

Running from the command line #

The scripts can be run using either Yarn or npm. If you've already gone through our Getting Started guide, you may already be familiar with the start command. It's the command that tells Docusaurus to run the docusaurus-start script which generates the site and starts up a server, and it's usually invoked like so:

yarn run start

The same script can be invoked using npm:

npm run start

To run a particular script, just replace the start command in the examples above with the command associated with your script.

Using arguments #

Some commands support optional arguments. For example, to start a server on port 8080, you can specify the --port argument when running start:

yarn run start --port 8080

If you run Docusaurus using npm, you can still use the command line arguments by inserting a -- between npm run <command> and the command arguments:

npm run start -- --port 8080

Configuration #

These scripts are set up under the "scripts" key in your website/package.json file as part of the installation process. If you need help setting them up again, please refer to the Installation guide.

Docusaurus provides some default mappings to allow you to run commands following Node conventions. Instead of typing docusaurus-start every time, you can type yarn run start or npm start to achieve the same.

Commands #

Reference #

docusaurus-build #

Alias: build.

Generates the static website, applying translations if necessary. Useful for building the website prior to deployment.

See also docusaurus-start.

docusaurus-examples [feature] #

Alias: examples

When no feature is specified, sets up a minimally configured example website in your project. This command is covered in depth in the Site Preparation guide. Specify a feature translations or versions to generate the extra example files for that feature.

docusaurus-publish #

Alias: publish-gh-pages

Builds, then deploys the static website to GitHub Pages. This command is meant to be run during the deployment step in Circle CI, and therefore expects a few environment variables to be defined:

  • GIT_USER: The git user to be associated with the deploy commit.
  • CIRCLE_BRANCH: The git branch associated with the commit that triggered the CI run.
  • CIRCLE_PROJECT_USERNAME: The GitHub username or organization name that hosts the git repo, e.g. "FacebookExperimental".
  • CIRCLE_PROJECT_REPONAME: The name of the git repo, e.g. "Docusaurus".
  • CI_PULL_REQUEST: Expected to be truthy if the current CI run was triggered by a commit in a pull request.

You can learn more about configuring automatic deployments with CircleCI in the Publishing guide.

docusaurus-rename-version <currentVersion> <newVersion> #

Alias: rename-version

Renames an existing version of the docs to a new version name.

See the Versioning guide to learn more.

docusaurus-start [--port <number>] #

Alias: start.

This script will build the static website, apply translations if necessary, and then start a local server. The website will be served from port 3000 by default.

docusaurus-version <version> #

Alias: version

Generates a new version of the docs. This will result in a new copy of your site being generated and stored in its own versioned folder. Useful for capturing snapshots of API docs that map to specific versions of your software. Accepts any string as a version number.

See the Versioning guide to learn more.

docusaurus-write-translations #

Alias: write-translations

Writes the English for any strings that need to be translated into an website/i18n/en.json file. The script will go through every file in website/pages/en and through the siteConfig.js file and other config files to fetch English strings that will then be translated on Crowdin. See the Translation guide to learn more.

← PreviousNext →
Docusaurus
Docs
Edit

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:

Running from the command line #

The scripts can be run using either Yarn or npm. If you've already gone through our Getting Started guide, you may already be familiar with the start command. It's the command that tells Docusaurus to run the docusaurus-start script which generates the site and starts up a server, and it's usually invoked like so:

yarn run start

The same script can be invoked using npm:

npm run start

To run a particular script, just replace the start command in the examples above with the command associated with your script.

Using arguments #

Some commands support optional arguments. For example, to start a server on port 8080, you can specify the --port argument when running start:

yarn run start --port 8080

If you run Docusaurus using npm, you can still use the command line arguments by inserting a -- between npm run <command> and the command arguments:

npm run start -- --port 8080

Configuration #

These scripts are set up under the "scripts" key in your website/package.json file as part of the installation process. If you need help setting them up again, please refer to the Installation guide.

Docusaurus provides some default mappings to allow you to run commands following Node conventions. Instead of typing docusaurus-start every time, you can type yarn run start or npm start to achieve the same.

Commands #

Reference #

docusaurus-build #

Alias: build.

Generates the static website, applying translations if necessary. Useful for building the website prior to deployment.

See also docusaurus-start.

docusaurus-examples [feature] #

Alias: examples

When no feature is specified, sets up a minimally configured example website in your project. This command is covered in depth in the Site Preparation guide. Specify a feature translations or versions to generate the extra example files for that feature.

docusaurus-publish #

Alias: publish-gh-pages

Builds, then deploys the static website to GitHub Pages. This command is meant to be run during the deployment step in Circle CI, and therefore expects a few environment variables to be defined:

  • GIT_USER: The git user to be associated with the deploy commit.
  • CIRCLE_BRANCH: The git branch associated with the commit that triggered the CI run.
  • CIRCLE_PROJECT_USERNAME: The GitHub username or organization name that hosts the git repo, e.g. "FacebookExperimental".
  • CIRCLE_PROJECT_REPONAME: The name of the git repo, e.g. "Docusaurus".
  • CI_PULL_REQUEST: Expected to be truthy if the current CI run was triggered by a commit in a pull request.

You can learn more about configuring automatic deployments with CircleCI in the Publishing guide.

docusaurus-rename-version <currentVersion> <newVersion> #

Alias: rename-version

Renames an existing version of the docs to a new version name.

See the Versioning guide to learn more.

docusaurus-start [--port <number>] #

Alias: start.

This script will build the static website, apply translations if necessary, and then start a local server. The website will be served from port 3000 by default.

docusaurus-version <version> #

Alias: version

Generates a new version of the docs. This will result in a new copy of your site being generated and stored in its own versioned folder. Useful for capturing snapshots of API docs that map to specific versions of your software. Accepts any string as a version number.

See the Versioning guide to learn more.

docusaurus-write-translations #

Alias: write-translations

Writes the English for any strings that need to be translated into an website/i18n/en.json file. The script will go through every file in website/pages/en and through the siteConfig.js file and other config files to fetch English strings that will then be translated on Crowdin. See the Translation guide to learn more.

← PreviousNext →
Edit this Doc

Custom Pages

Customizing Your Home Page #

The easiest way to get started customizing your home page is to use the examples generated previously. 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.

Adding Other Custom Pages #

Docusaurus provides some simple example pages (index.js, users.js, help.js), but of course you're also free to write your own pages however you want. It is strongly suggested that you at least have an index page, but none of the pages are mandatory to include. More information on how to use the provided components or include your own can be found here. Information on how to link to your different pages in the header navigation bar can be found here.

Customizing Your Site Footer #

Starting from the example core/Footer.js file you generated before, edit the footer to include any links to pages on your site or elsewhere that you wish to have.

The example provided has three columns with a footer image on the left and Facebook's open source logo and copyright at the bottom. If your project is not a Facebook open source project, remove the logo and copyright. Otherwise, feel free to get creative with your footer and make it look however you'd like!

Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.

Your footer will automatically get applied to all pages on your site, including docs and blog posts. The sole exception to this is any static html pages you include.

If you don't want a footer for your site, change the render function of core/Footer.js to return null. e.g.,

const React = require("react");
+
Edit

Custom Pages

Customizing Your Home Page #

The easiest way to get started customizing your home page is to use the examples generated previously. 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.

Adding Other Custom Pages #

Docusaurus provides some simple example pages (index.js, users.js, help.js), but of course you're also free to write your own pages however you want. It is strongly suggested that you at least have an index page, but none of the pages are mandatory to include. More information on how to use the provided components or include your own can be found here. Information on how to link to your different pages in the header navigation bar can be found here.

Customizing Your Site Footer #

Starting from the example core/Footer.js file you generated before, edit the footer to include any links to pages on your site or elsewhere that you wish to have.

The example provided has three columns with a footer image on the left and Facebook's open source logo and copyright at the bottom. If your project is not a Facebook open source project, remove the logo and copyright. Otherwise, feel free to get creative with your footer and make it look however you'd like!

Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.

Your footer will automatically get applied to all pages on your site, including docs and blog posts. The sole exception to this is any static html pages you include.

If you don't want a footer for your site, change the render function of core/Footer.js to return null. e.g.,

const React = require("react");
 
 class Footer extends React.Component {
   render() {
diff --git a/docs/en/doc-markdown.html b/docs/en/doc-markdown.html
index e622803bbf..10954adfee 100644
--- a/docs/en/doc-markdown.html
+++ b/docs/en/doc-markdown.html
@@ -4,7 +4,7 @@
           toggler.onclick = function() {
             nav.classList.toggle('docsSliderActive');
           };
-
Edit this Doc

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 it's file name (without the extension).

title: The title of your document. If this field is not present, the document's title will default to it's id.

sidebar_label: The text shown in the document sidebar for this document. If this field is not present, the document's sidebar_label will default to it's title.

For example:

---
+
Edit

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 it's file name (without the extension).

title: The title of your document. If this field is not present, the document's title will default to it's id.

sidebar_label: The text shown in the document sidebar for this document. If this field is not present, the document's sidebar_label will default to it's title.

For example:

---
 id: doc1
 title: My Document
 sidebar_label: Document
diff --git a/docs/en/installation.html b/docs/en/installation.html
index 7137ffb8e6..b0b6fd8ae8 100644
--- a/docs/en/installation.html
+++ b/docs/en/installation.html
@@ -4,7 +4,7 @@
           toggler.onclick = function() {
             nav.classList.toggle('docsSliderActive');
           };
-
Edit this Doc

Installation

Docusaurus was designed from the ground up to be easily installed and used to get your website up an running quickly. To install Docusaurus, follow these steps:

  1. Create a website folder in the root of your GitHub repo.
  2. cd website

  3. Create a package.json file with the following scripts that will be used when developing documentation with Docusaurus:

     {
+
Edit

Installation

Docusaurus was designed from the ground up to be easily installed and used to get your website up an running quickly. To install Docusaurus, follow these steps:

  1. Create a website folder in the root of your GitHub repo.
  2. cd website

  3. Create a package.json file with the following scripts that will be used when developing documentation with Docusaurus:

     {
    "scripts": {
      "start": "docusaurus-start",
      "build": "docusaurus-build",
diff --git a/docs/en/navigation.html b/docs/en/navigation.html
index 4ad6d3711d..06bf94ae61 100644
--- a/docs/en/navigation.html
+++ b/docs/en/navigation.html
@@ -4,7 +4,7 @@
           toggler.onclick = function() {
             nav.classList.toggle('docsSliderActive');
           };
-
Edit this Doc

Navigation and Sidebars

New Hidden Docs #

New markdown files within docs will show up as pages on the website. Creating a file such as "docs/getting-started.md" will enable the new page /docs/getting-started.html.

To change the id (link name) of the file, set the id field in the markdown header. At the top of getting-started.md:

---
+
Edit

Navigation and Sidebars

New Hidden Docs #

New markdown files within docs will show up as pages on the website. Creating a file such as "docs/getting-started.md" will enable the new page /docs/getting-started.html.

To change the id (link name) of the file, set the id field in the markdown header. At the top of getting-started.md:

---
 id: intro
 title: Getting Started
 ---
diff --git a/docs/en/publishing.html b/docs/en/publishing.html
index 8b66043ee1..aad6e4c351 100644
--- a/docs/en/publishing.html
+++ b/docs/en/publishing.html
@@ -4,7 +4,7 @@
           toggler.onclick = function() {
             nav.classList.toggle('docsSliderActive');
           };
-
Edit this Doc

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 script:

npm run build

or

yarn run build

This will generate .html files from all of your docs and other pages included in pages. The build folder is inside Docusaurus's directory inside node_modules.

Hosting Static HTML Pages #

At this point, you can grab all of the files inside the node_modules/docusaurus/build folder and copy them over to your favorite web server's "html" directory. For example, both Apache and nginx serve content from /var/www/html by default. You'll still need to host the web server somewhere, and as it happens, choosing a web hosting provider is out of scope for this guide. Don't fret, as Docusaurus was designed to work really well with one of the most popular hosting solutions for open source projects: GitHub Pages.

Using GitHub Pages #

Deploying your Docusaurus site to GitHub Pages is straightforward if you are already using GitHub to host your project. Your code repository does not even need to be public. Most of the work is done for you automatically through the publish-gh-pages script.

Before you go ahead and do that, you need to determine the values for a few parameters required by the script. They are:

  • CIRCLE_PROJECT_REPONAME: The name of the GitHub repository for your project. For example, Docusaurus is hosted at https://github.com/facebookexperimental/docusaurus, so our repo name in this case would be "docusaurus".
  • CIRCLE_PROJECT_USERNAME: The GitHub user or organization that owns the repository. In the case of Docusaurus, that would be the "facebookexperimental" GitHub organization.
  • GITHUB_USERNAME: The username for a GitHub account that has commit access to this repo. For your own repositories, this will usually be your own GitHub username.
  • CIRCLE_BRANCH: The branch that contains the latest docs changes that will be deployed. Usually, "master".

Once you have this information, you can go ahead and run the publish-gh-pages script like so (making sure to insert your own values inside the <placeholders>):

GIT_USER=<GIT_USER> CIRCLE_PROJECT_USERNAME=<CIRCLE_PROJECT_REPONAME> CIRCLE_PROJECT_REPONAME=<CIRCLE_PROJECT_USERNAME> CIRCLE_BRANCH=master yarn run publish-gh-pages

You should now be able to load your website by visiting its GitHub Pages URL, which should be something along the lines of https://CIRCLE_PROJECT_USERNAME.github.io/CIRCLE_PROJECT_REPONAME. For example, Docusaurus's own GitHub Pages URL is https://facebookexperimental.github.io/docusaurus, because it is served from the gh-pages branch of the https://github.com/facebookexperimental/docusaurus GitHub repo. We highly encourage reading through the GitHub Pages documentation to learn more about how this hosting solution works.

You can run the command above any time you update the docs and wish to deploy the changes to your site. That's usually fine for sites where the documentation rarely changes, where it's not too much of an inconvenience to remember to manually deploy changes. Now, if you're wondering if this process can be automated in any way, keep reading...

Automating Deployments Using Continuous Integration #

Continuous integration services are typically used to perform routine tasks whenever new commits are checked in to source control. These tasks can be any combination of running unit tests and integration tests, automating builds, publishing packages to NPM, and yes, deploying changes to your website. All you need to do to automate deployment of your website is to invoke the publish-gh-pages script whenever your docs get updated. In the following section we'll be covering how to do just that using Circle CI, a popular continuous integration service provider.

Using Circle CI #

If you're already using Circle CI for your project, all you need to do to enable automatic deployments is to configure Circle to run the publish-gh-pages script as part of the deployment step.

  1. Go to https://github.com/settings/tokens and generate a new token, granting it full control of private repositories through the repo access scope. Store this token in a safe place, making sure to not share it with anyone. This token can be used to authenticate GitHub actions on your behalf in place of your GitHub password.
  2. Open your Circle CI dashboard, and navigate to the Settings page for your repository, then select "Environment variables". The URL looks like https://circleci.com/gh/facebookexperimental/docusaurus/edit#env-vars, where "facebookexperimental/docusaurus" should be replaced with your own GitHub user/repo.
  3. Create a new environment variable named "GITHUB_TOKEN", using your newly generated access token as the value.

  4. Open your circle.yml file and add the following under the machine: section to tell Circle to use relatively recent versions of node and npm, replacing npm with yarn if applicable:

    machine:
+
Edit

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 script:

npm run build

or

yarn run build

This will generate .html files from all of your docs and other pages included in pages. The build folder is inside Docusaurus's directory inside node_modules.

Hosting Static HTML Pages #

At this point, you can grab all of the files inside the node_modules/docusaurus/build folder and copy them over to your favorite web server's "html" directory. For example, both Apache and nginx serve content from /var/www/html by default. You'll still need to host the web server somewhere, and as it happens, choosing a web hosting provider is out of scope for this guide. Don't fret, as Docusaurus was designed to work really well with one of the most popular hosting solutions for open source projects: GitHub Pages.

Using GitHub Pages #

Deploying your Docusaurus site to GitHub Pages is straightforward if you are already using GitHub to host your project. Your code repository does not even need to be public. Most of the work is done for you automatically through the publish-gh-pages script.

Before you go ahead and do that, you need to determine the values for a few parameters required by the script. They are:

  • CIRCLE_PROJECT_REPONAME: The name of the GitHub repository for your project. For example, Docusaurus is hosted at https://github.com/facebookexperimental/docusaurus, so our repo name in this case would be "docusaurus".
  • CIRCLE_PROJECT_USERNAME: The GitHub user or organization that owns the repository. In the case of Docusaurus, that would be the "facebookexperimental" GitHub organization.
  • GITHUB_USERNAME: The username for a GitHub account that has commit access to this repo. For your own repositories, this will usually be your own GitHub username.
  • CIRCLE_BRANCH: The branch that contains the latest docs changes that will be deployed. Usually, "master".

Once you have this information, you can go ahead and run the publish-gh-pages script like so (making sure to insert your own values inside the <placeholders>):

GIT_USER=<GIT_USER> CIRCLE_PROJECT_USERNAME=<CIRCLE_PROJECT_REPONAME> CIRCLE_PROJECT_REPONAME=<CIRCLE_PROJECT_USERNAME> CIRCLE_BRANCH=master yarn run publish-gh-pages

You should now be able to load your website by visiting its GitHub Pages URL, which should be something along the lines of https://CIRCLE_PROJECT_USERNAME.github.io/CIRCLE_PROJECT_REPONAME. For example, Docusaurus's own GitHub Pages URL is https://facebookexperimental.github.io/docusaurus, because it is served from the gh-pages branch of the https://github.com/facebookexperimental/docusaurus GitHub repo. We highly encourage reading through the GitHub Pages documentation to learn more about how this hosting solution works.

You can run the command above any time you update the docs and wish to deploy the changes to your site. That's usually fine for sites where the documentation rarely changes, where it's not too much of an inconvenience to remember to manually deploy changes. Now, if you're wondering if this process can be automated in any way, keep reading...

Automating Deployments Using Continuous Integration #

Continuous integration services are typically used to perform routine tasks whenever new commits are checked in to source control. These tasks can be any combination of running unit tests and integration tests, automating builds, publishing packages to NPM, and yes, deploying changes to your website. All you need to do to automate deployment of your website is to invoke the publish-gh-pages script whenever your docs get updated. In the following section we'll be covering how to do just that using Circle CI, a popular continuous integration service provider.

Using Circle CI #

If you're already using Circle CI for your project, all you need to do to enable automatic deployments is to configure Circle to run the publish-gh-pages script as part of the deployment step.

  1. Go to https://github.com/settings/tokens and generate a new token, granting it full control of private repositories through the repo access scope. Store this token in a safe place, making sure to not share it with anyone. This token can be used to authenticate GitHub actions on your behalf in place of your GitHub password.
  2. Open your Circle CI dashboard, and navigate to the Settings page for your repository, then select "Environment variables". The URL looks like https://circleci.com/gh/facebookexperimental/docusaurus/edit#env-vars, where "facebookexperimental/docusaurus" should be replaced with your own GitHub user/repo.
  3. Create a new environment variable named "GITHUB_TOKEN", using your newly generated access token as the value.

  4. Open your circle.yml file and add the following under the machine: section to tell Circle to use relatively recent versions of node and npm, replacing npm with yarn if applicable:

    machine:
 node:
  version: 6.11.2
 npm:
diff --git a/docs/en/search.html b/docs/en/search.html
index ba26fab3e8..8d76ce6459 100644
--- a/docs/en/search.html
+++ b/docs/en/search.html
@@ -4,7 +4,7 @@
           toggler.onclick = function() {
             nav.classList.toggle('docsSliderActive');
           };
-
Edit this Doc

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 = {
+
Edit

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 = {
   ...
   algolia: {
     apiKey: "my-search-only-api-key-1234",
diff --git a/docs/en/site-config.html b/docs/en/site-config.html
index 416ea0cdbc..1ac2798d9d 100644
--- a/docs/en/site-config.html
+++ b/docs/en/site-config.html
@@ -4,7 +4,7 @@
           toggler.onclick = function() {
             nav.classList.toggle('docsSliderActive');
           };
-
Edit this Doc

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 someon. 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.

siteConfig Fields #

The siteConfig object contains the bulk of the configuration settings for your website.

Mandatory Fields #

title - Title for your website.

tagline - Tagline for your website.

url - url for your site.

baseUrl - baseUrl for your site.

projectName - Project name. This must match your GitHub repo project name (case sensitive).

noIndex - Boolean. If true, Docusaurus will politely ask crawlers and search engines to avoid indexing your site. This is done with a header tag and so only applies to docs and pages. Will not attempt to hide static resources. This is a best effort request. Malicious crawlers can and will still index your site.

headerLinks - Links that will be used in the header navigation bar. The label field of each object will be the link text and will also be translated for each language.

Example Usage:

headerLinks: [
+
Edit

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 someon. 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.

siteConfig Fields #

The siteConfig object contains the bulk of the configuration settings for your website.

Mandatory Fields #

title - Title for your website.

tagline - Tagline for your website.

url - url for your site.

baseUrl - baseUrl for your site.

projectName - Project name. This must match your GitHub repo project name (case sensitive).

noIndex - Boolean. If true, Docusaurus will politely ask crawlers and search engines to avoid indexing your site. This is done with a header tag and so only applies to docs and pages. Will not attempt to hide static resources. This is a best effort request. Malicious crawlers can and will still index your site.

headerLinks - Links that will be used in the header navigation bar. The label field of each object will be the link text and will also be translated for each language.

Example Usage:

headerLinks: [
   // Links to document with id doc1 for current language/version
   { doc: "doc1", label: "Getting Started" },
   // Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language
diff --git a/docs/en/site-creation.html b/docs/en/site-creation.html
index e5113376cb..d6d3e802c0 100644
--- a/docs/en/site-creation.html
+++ b/docs/en/site-creation.html
@@ -4,7 +4,7 @@
           toggler.onclick = function() {
             nav.classList.toggle('docsSliderActive');
           };
-
Edit this Doc

Creating your site

Docusaurus' primary purpose of existence is to make it super simple for you to create documentation for your project and have a site to house those docs.

After installation and preparation, much of the work to create a basic site for your docs is already complete.

Load the Example Site #

Preparation created a sample site for you to see Docusaurus in action. However, it also provided the infrastructure that will be used as you are developing your own site.

Site Structure #

After loading the example site, you should see a structure in your repo that looks similar to:

project-repo/
+
Edit

Creating your site

Docusaurus' primary purpose of existence is to make it super simple for you to create documentation for your project and have a site to house those docs.

After installation and preparation, much of the work to create a basic site for your docs is already complete.

Load the Example Site #

Preparation created a sample site for you to see Docusaurus in action. However, it also provided the infrastructure that will be used as you are developing your own site.

Site Structure #

After loading the example site, you should see a structure in your repo that looks similar to:

project-repo/
   docs/
     doc1.md
   website/
diff --git a/docs/en/site-preparation.html b/docs/en/site-preparation.html
index 4c53468b5e..fad89dd10d 100644
--- a/docs/en/site-preparation.html
+++ b/docs/en/site-preparation.html
@@ -4,7 +4,7 @@
           toggler.onclick = function() {
             nav.classList.toggle('docsSliderActive');
           };
-
Edit this Doc

Site Preparation

After installing Docusaurus, you will want to install and run the example site included. This serves dual purposes.

  1. Verifying that Docusaurus was installed correctly.
  2. Providing you the skeleton to create your site.

Verifying Installation #

  1. Generate the files for the example site by running examples using yarn or npm.

     npm run examples

    or

     yarn run examples

    If any of the files created by [yarn | npm] run examples already exists, Docusaurus will not overwrite them.

  2. Run the server.

     npm run start

    or

     yarn run start

  3. Load the example site at http://localhost:3000. You should see the example site loaded in your web browser.

Example Site Configuration #

Loading the example site will create the following files/folders:

website/core/Footer.js
+
Edit

Site Preparation

After installing Docusaurus, you will want to install and run the example site included. This serves dual purposes.

  1. Verifying that Docusaurus was installed correctly.
  2. Providing you the skeleton to create your site.

Verifying Installation #

  1. Generate the files for the example site by running examples using yarn or npm.

     npm run examples

    or

     yarn run examples

    If any of the files created by [yarn | npm] run examples already exists, Docusaurus will not overwrite them.

  2. Run the server.

     npm run start

    or

     yarn run start

  3. Load the example site at http://localhost:3000. You should see the example site loaded in your web browser.

Example Site Configuration #

Loading the example site will create the following files/folders:

website/core/Footer.js
 website/pages/...
 website/static/img/...
 website/siteConfig.js
diff --git a/docs/en/translation.html b/docs/en/translation.html
index 0010c52102..6053f361bf 100644
--- a/docs/en/translation.html
+++ b/docs/en/translation.html
@@ -4,7 +4,7 @@
           toggler.onclick = function() {
             nav.classList.toggle('docsSliderActive');
           };
-
Edit this Doc

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 Docusuaurus, run the examples script with the command line argument translations:

npm run examples translations

or

yarn examples translations

This will create the following files:

pages/en/help-with-translations.js
+
Edit

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 Docusuaurus, run the examples script with the command line argument translations:

npm run examples translations

or

yarn examples translations

This will create the following files:

pages/en/help-with-translations.js
 languages.js
 crowdin.yaml

The pages/en/help-with-translations.js file includes the same starter help page generated by the examples script, but now includes translation tags.

The languages.js file tells Docusaurus what languages you want to enable for your site. By default, we expect English to be enabled.

The crowdin.yaml file is used to configure crowdin integration, and is copied up one level into your docusaurus project repo. If your docusaurus project resides in /project/website, then crowdin.yaml will be copied to /project/crowdin.yaml.

Translating Your Existing Docs #

Your documentation files do not need to be changed or moved to support translations. They will be uploaded to Crowdin to be translated directly.

Enabling Translations on Pages #

Pages allow you to customize layout and specific content of pages like a custom index page or help page.

Pages with text that you want translated should be placed in website/pages/en folder.

Wrap strings you want translated in a <translate> tag, and add the following require statement to the top of the file:

...
 const translate = require("../../server/translate.js").translate;
diff --git a/docs/en/versioning.html b/docs/en/versioning.html
index 0a6553b7ed..8a6b635f01 100644
--- a/docs/en/versioning.html
+++ b/docs/en/versioning.html
@@ -4,7 +4,7 @@
           toggler.onclick = function() {
             nav.classList.toggle('docsSliderActive');
           };
-
Edit this Doc

Versioning

Users 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 #

Add the following script to your package.json file:

...
+
Edit

Versioning

Users 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 #

Add the following script to your package.json file:

...
 "scripts": {
   "version": "docusaurus-version"
 },