Skip to main content

Working on Documentation

The Documentation System is built using Docusaurus - a static site generator built using React and set up for TypeScript.

Most of the time, to update a document, you just need to edit or create a Markdown (.md) file. Touching React is entirely optional and not recommended without first consulting with the Lead Developer.

Installation​

  • Clone the Repository
  • Node.js version 14 or above
  • Recommend you install Yarn
  • Run yarn to install dependencies
  • Check out a new branch git checkout -b your-branch-name

Development​

Run the development server:

yarn run start

This will open up a development server on http://localhost:3000/

Any changes you make to the files inside /docs will trigger an automatic rebuild of the site and an automatic live update of the page in your browser!

Creating a new Section​

First you need to decide where your new piece of content belongs. Within Development, Plugins or Websites. If you think it doesn't belong in any of those, speak to the Lead Developer.

All Plugins should have a section created already inside /plugins/LANGUAGE/PLUGIN_NAME, unless this is a new Plugin.

Looking at the existing structure you should be able to see that a folder automatically creates a collapsible sidebar menu, with the MarkDown files inside, representing individual pages.

If you're creating a file for a Plugin you can base the structure on the Template file - located at /docs/plugins/_template.md.

You may also deduce that prefixing a file with an underscore prevents it from being included in the Frontend - so you can only find this template in the repository itself.

Customising The Page​

You are free to use all standard Markdown features.

Docusaurus also comes with some very nice extra Markdown features too.

You may notice at the top of the Markdown file, a section surrounded by dashes:

---
slug: /
title: Hello world
sidebar_position: 1
---

These should be fairly self explanatory but most of the time you'll only need to worry about sidebar_position!

Inside a folder you may see a _category.json file with similar contents to this:

{
  "label": "Troubleshooting",
  "position": 8
}

This is used to help the Auto Sidemenu Generation - See Docusaurus for more information

Assets​

If you need any assets (such as images) to reference inside your Markdown, create an assets folder in the directory your document is and reference them relatively:

your-doc-file.md
![Example banner](./assets/docusaurus-asset-example-banner.png)

For more detail see Using Assets in Markdown on the Docusaurus site.

Deployment​

The JUMP Docs are hosted on Vercel - Log in with our Jump Ops Github Account.

Vercel is a serverless deployment tool that automatically builds whenever the Github repository is updated.

Staging​

Once you've made your changes on your new local branch, simply push the branch to Github.

Vercel will automatically pick up on this branch and build a brand new staging site for you to test!

Log in to Vercel to see the URL for this site in the Deployment section.

Live​

When you're happy, simply create a Pull Request to the master branch with the Lead Developer as a Reviewer.