Skip to main content

Project Documentation

FINOS collaboration services offer several tools and technologies to write, collaborate, and publish project documentation.

After experimenting with various tools, we have selected Docusaurus and Netlify as the best choices.

Advantages of a Centralized Documentation Strategy​

  1. Ease of use - Markdown syntax, simple local development, and easy configuration.
  2. Easy to collaborate - Files are stored in a docs/ folder in the GitHub repository, allowing anyone can submit a Pull Request.
  3. Automated - Change to the main branch version will trigger a deployment of the website.
  4. Branded - Enforces FINOS graphic guidelines across all websites.

Getting Started with Project Documentation​

In order to add a website to an existing project, see the Docusaurus section below. If instead you are starting a new project, see the FINOS project blueprint documentation.

Examples of Docusaurus Project Documentation Websites​

Docusaurus​

Docusaurus is a static website generator written in React, available open source under the Apache 2.0 license. It is technologically similar to Jekyll, which integrates tightly with GitHub Pages but lacks modern development support and local development tools.

Given the significant adoption of Docusaurus within FINOS projects, it has become our go-to solution for building project documentation websites. If you're just getting started, use the FINOS project blueprint repository template and follow the blueprint documentation to get started which includes a built-in Docusaurus website.

The full Docusaurus documentation can be found on the Docusaurus website.

Get Started in 5 Minutes​

info

The following steps refers to Docusaurus 3.x version and how its used in conjunction with the FINOS project blueprint.

Ensure NodeJS and NPM are installed:

npm -v
node -v

Create a Docusaurus project and start the website locally:

npm i -g docusaurus-init docusaurus
git clone git@github.com:finos/software-project-blueprint.git
cd software-project-blueprint/website
npm install
npm 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/
    .docusaurus/
    node_modules/
    src/
    static/
      css/
      img/
    docusaurus.config.js
    package.json
    sidebars.js
  netlify.toml

See the Docusaurus 3 project structure.

Adding and Editing Content​

Website pages are represented by Markdown files in the the docs/ folder (in Docusaurus 3, MarkDown React files are also supported). The page id maps to the URL slug of the page; the title renders out as an <h1> on the page.

---
id: example-doc
title: Example Doc Page
---

Add/Edit content here!

See the Docusarus docs documentation page for more information.

Add links to docs, custom pages, or external links by editing the themeConfig object in the website/docusaurus.config.js file:

themeConfig: {
  navbar: {
    title: `FINOS ${projectName}`,
    logo: {
      alt: 'FINOS Logo',
      src: 'img/favicon/favicon-finos.ico',
    },
    items: [
      /* you can add docs */
      {to: 'docs/home', label: 'Docs', position: 'right'},
      {to: 'docs/roadmap', label: 'Roadmap', position: 'right'},
      {to: 'docs/team', label: 'Team', position: 'right'},
      {
        /* you can add external links */
        href: 'https://github.com/finos/',
        label: 'GitHub',
        position: 'right',
      }
    ],
  },
}

For more information, see the Docusaurus Navbar Items documentation.

The sidebar that is used to navigate the doc files in docs/ folder is managed in the website/sidebars.js file. The sidebar liks to each doc file via the id property set in the .md or .mdx file. 

module.exports = {
  mainSidebar: {
    'Main Menu': ["example-doc", "team", "roadmap"]
  },
}

For more details on how to configure the sidebar see the Docusaurus Sidebar documentation.

Docusaurus Alternatives​

The Accessibility Theme Builder project website utilises MKDocs (specfically Material for MKDocs).

Before Docusaurus, the FINOS Community also experimented with a few other solutions, which are worth mentioning for historical reasons:

  1. GitHub Wiki provides a great integration with code, as it's hosted as a git endpoint; however, Pull Requests are not available, therefore the collaboration mechanism can only be extended to the project team, which is a big limitation. Also, installing a local development environment is not trivial Its biggest advantage is the possibility to preview the changes via the GitHub web UI.
  2. Jekyll, the page generator engine used by GitHub Pages, which also supports templating; the downside of Jekyll is that the installation of a local development environment (Ruby) is hard.
  3. GoHugo, a generic static page generator written in Go, with a strong community and eco-system.

Website Deployment​

Netlify​

Netlify is the prefered tool by FINOS when it comes to hosting websites as it offers hosting and serverless backend services for web applications and static websites. As well as a seamless integration with GitHub and provides automatic preview capabilities, making it easier to review changes before they go live.

Custom Domain Setup​

In order to deploy your website and get a custom subdomain configured, such as fdc3.finos.org, please email help@finos.org.

Netlify Configurations​

In order to manage when/how Netlify creates previews a netlify.toml file can be placed in the root of the repository.

For example the following configuration will trigger a preview only when it detects changes in the docs and website folders:

[build]
  ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF . ../{docs,website}/"

See this netlify.toml.

[DEPRECATED] Docusaurus Build Action​

Note! This GitHub action has been deprecated in favor of using Netlify

FINOS have developed a GitHub Action to automatically build the Docusaurus websites and publish them into GitHub Pages; the action works on upstream repositories (ie https://github.com/finos/software-project-blueprint) as well as forked ones , providing a simple way to stage the web version of a change to a Docusaurus website.

The action also intercepts Pull Requests and adds a comment with the link to the website (preview) of the PR submitter; this way issue reviewers can easily and visually see the changes.

The action can be copied from here.