GitHub Docusaurus build action available!

Checkout the GitHub Action we designed to automagically build and publish Docusaurus websites!

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.

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

Folder Structure

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

docs/doc-to-be-edited.md

---
id: page-needs-edit
title: This Doc Needs To Be Edited
---

Edit me...

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:

website/blog/post-to-be-edited.md

---
id: post-needs-edit
title: This Blog Post Needs To Be Edited
---

Edit me...

Checkout docusaurus blog docs to know more.

Adding Content

Adding a new docs page to an existing sidebar

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

website/blog/post-to-be-edited.md

---
id: newly-created-doc
title: This Doc Needs To Be Edited
---

My new content here..
Refer to that doc's ID in an existing sidebar in website/sidebar.json:
// Add newly-created-doc to the Getting Started category of docs
{
  "docs": {
    "Getting Started": [
      "quick-start",
      "newly-created-doc" // new doc here
    ],
    ...
  },
  ...
}

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:

website/siteConfig.js

{
  headerLinks: [
    ...
    { blog: true, label: 'Blog' },
    ...
  ]
}

Create the blog post with the format YYYY-MM-DD-My-Blog-Post-Title.md in website/blog:

website/blog/2018-05-21-New-Blog-Post.md

---
author: Frank Li
authorURL: https://twitter.com/foobarbaz
authorFBID: 503283835
title: New Blog Post
---

Lorem Ipsum...

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:

website/siteConfig.js

{
  headerLinks: [
    ...
    /* you can add docs */
    { doc: 'my-examples', label: 'Examples' },
    /* you can add custom pages */
    { page: 'help', label: 'Help' },
    /* you can add external links */
    { href: 'https://github.com/facebook/Docusaurus', label: 'GitHub' },
    ...
  ],
  ...
}

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.

website/siteConfig.js

{
  headerLinks: [
    ...
    { page: 'my-new-custom-page', label: 'My New Custom Page' },
    ...
  ],
  ...
}

For more information, checkouot the docusaurus custom pages docs