Docusaurus was designed from the ground up to be easily installed and used to get your website up and running quickly.

Important Note: we highly encourage you to use Docusaurus 2 instead.

Installing Docusaurus

We have created a helpful script that will get all of the infrastructure set up for you:

  1. Ensure you have the latest version of Node installed. We also recommend you install Yarn as well.

    You have to be on Node >= 10.9.0 and Yarn >= 1.5.

  2. Create a project, if none exists, and change your directory to this project’s root.

    You will be creating the docs in this directory. The root directory may contain other files. The Docusaurus installation script will create two new directories: docs and website.

    Commonly, either an existing or newly created GitHub project will be the location for your Docusaurus site, but that is not mandatory to use Docusaurus.

  3. Run the Docusaurus installation script: npx docusaurus-init.

    If you don’t have Node 8.2+ or if you prefer to install Docusaurus globally, run yarn global add docusaurus-init or npm install --global docusaurus-init. After that, run docusaurus-init.

Verifying Installation

Along with previously existing files and directories, your root directory will now contain a structure similar to:

  1. root-directory
  2. ├── Dockerfile
  3. ├── README.md
  4. ├── docker-compose.yml
  5. ├── docs
  6. │   ├── doc1.md
  7. │   ├── doc2.md
  8. │   ├── doc3.md
  9. │   ├── exampledoc4.md
  10. │   └── exampledoc5.md
  11. └── website
  12.     ├── blog
  13.     │   ├── 2016-03-11-blog-post.md
  14.     │   ├── 2017-04-10-blog-post-two.md
  15.     │   ├── 2017-09-25-testing-rss.md
  16.     │   ├── 2017-09-26-adding-rss.md
  17.     │   └── 2017-10-24-new-version-1.0.0.md
  18.     ├── core
  19.     │   └── Footer.js
  20.     ├── package.json
  21.     ├── pages
  22.     ├── sidebars.json
  23.     ├── siteConfig.js
  24.     └── static

This installation creates some Docker files that are not necessary to run docusaurus. They may be deleted without issue in the interest of saving space. For more information on Docker, please see the Docker documentation.

Running the example website

After running the Docusaurus initialization script, docusaurus-init as described in the Installation section, you will have a runnable, example website to use as your site’s base. To run:

  1. cd website

  2. From within the website directory, run the local web server using yarn start or npm start.

  3. Load the example site at http://localhost:3000 if it did not already open automatically. If port 3000 has already been taken, another port will be used. Look at the console messages to see which.

    You should see the example site loaded in your web browser. There’s also a LiveReload server running and any changes made to the docs and files in the website directory will cause the page to refresh. A randomly generated primary and secondary theme color will be picked for you.

Image 1

Launching the server behind a proxy

If you are behind a corporate proxy, you need to disable it for the development server requests. It can be done using the NO_PROXY environment variable.

  1. SET NO_PROXY=localhost
  2. yarn start (or npm run start)

Updating Your Docusaurus Version

At any time after Docusaurus is installed, you can check your current version of Docusaurus by going into the website directory and typing yarn outdated docusaurus or npm outdated docusaurus.

You will see something like this:

  1. $ yarn outdated
  2. Using globally installed version of Yarn
  3. yarn outdated v1.5.1
  4. warning package.json: No license field
  5. warning No license field
  6. info Color legend :
  7.  "<red>"    : Major Update backward-incompatible updates
  8.  "<yellow>" : Minor Update backward-compatible features
  9.  "<green>"  : Patch Update backward-compatible bug fixes
  10. Package    Current Wanted Latest Package Type    URL
  11. docusaurus 1.0.9   1.2.0  1.2.0  devDependencies https://github.com/facebook/docusaurus#readme
  12. ✨  Done in 0.41s.

If there is no noticeable version output from the outdated commands, then you are up-to-date.

You can update to the latest version of Docusaurus by:

  1. yarn upgrade docusaurus --latest

or

  1. npm update docusaurus

If you are finding that you are getting errors after your upgrade, try to either clear your Babel cache (usually it’s in a temporary directory or run the Docusaurus server (e.g., yarn start) with the BABEL_DISABLE_CACHE=1 environment configuration.