...

Docusaurus is a static website generator written in NodeJS and available open source under the Apache 2.0 license. A similar technology is Jekyll, which provides a tighter integration with GitHub Pages, but lacks of development support (as in Ruby) and tools for local development.

This page walks through the use of docusaurus on a local environment; if Given the significant amount of FINOS projects that adopted this framework, it became our go-to solution to build project documentation websites; if you're getting started, you may want to use the FINOS project blueprint repository template, which already provides a built-in Docusaurus website.

Full documentation can be found on docusaurus website.

There ; there is also a Docusaurus Build action for GitHub.com available.

This page walks through the use of docusaurus on a local environment; full documentation can be found on docusaurus website.

Prerequisites

You need to have NodeJS and NPM command-line tools installed in your terminal. Run the following commands to check:

npm -v
node -v

Get Started in 5 Minutes

Open a terminal and cd into your project's folder; regardless of the language, eco-system or platform you're using, run the following commands:

npm i -g docusaurus-init docusaurus
docusaurus-init
mv docs-examples-from-docusaurus docs
mv website/blog-examples-from-docusaurus website/blog
cd website
docusaurus-start

Directory Structure

Your project file structure should look something like this:

/project_root
  docs/
    doc-1.md
    doc-2.md
    doc-3.md
  website/
    blog/
      2016-3-11-oldest-post.md
      2017-10-24-newest-post.md
    core/
    node_modules/
    pages/
    static/
      css/
      img/
    package.json
    sidebar.json
    siteConfig.js

Editing Content

Editing an existing docs page

Edit docs by navigating to docs/ and editing the corresponding document:

...

For more information, checkout the docusaurus navigation docs.

Editing an existing blog post

Edit blog posts by navigating to website/blog and editing the corresponding post:

...

Checkout docusaurus blog docs to know more.

Adding Content

Adding a new docs page to an existing sidebar

1. Create the doc as a new markdown file in /docs, example docs/newly-created-doc.md:

...

For more information, checkout the docusaurus navigation docs.

Adding a new blog post

Make sure there is a header link to your blog in website/siteConfig.js:

...

Checkout docusaurus blog docs to know more.

Adding items to your site's top navigation bar

Add links to docs, custom pages or external links by editing the headerLinks field of website/siteConfig.js:

...

For more information, checkout the docusaurus navigation docs.

Adding custom pages

Docusaurus uses React components to build pages; components must be saved as .js files in website/pages/en ; If you want your page to show up in your navigation header, you will need to update website/siteConfig.js to add to the headerLinks element, as shown below.

...