Skip to main content

Documentation Guide

Improving our documentation is one of the easiest ways to start contributing to Morio. So if you spot a mistake or see something that you can improve, please do not hesitate to do so.

This guide will show you how you can do that.

TIP

Making quick edits​

The easiest way to make changes to the documentation is via the Edit this page link that you can find at the bottom of every documentation page.

This will take you to the GitHub online editor where you can propose changes directly.
Note: You need a GitHub account to do this, but they are free.

Where to find our documentation​

We store our documentation as Markdown (nay ) in git and use Docusaurus to generate a static website from it, which we then publish at morio.it.

Inside our monorepo, the docs folder holds the docusaurus setup. Within that folder, the docs subfolder holds the actual markdown/mdx content.

So, relative to the monorepo root, you can find the source of our documentation under docs/docs.

Folder structure & file names​

The folder structure of the markdown files directly translates to the URL structure of the documentation website. The file names must always be readme.mdx.

If we take this documentation guide as an example:

  • Relative url: /docs/guides/contributors/docs
  • Path to the source file: docs/docs/guides/contributors/docs/readme.mdx

That not only makes it easy to find the source of any given page, it also has implications for how you should structure content:

  • All content files under docs/docs should be named readme.mdx
  • All folders under docs/docs should have a URL-friendly name, using only the characters a-z, 0-9, and -
  • Every folder should have a readme.mdx, no empty folders

Front matter​

Front matter is metadata that sits at the top of a markdown file. Strictly speaking, it is not part of markdown, but rather a list of key/value pairs in YAML format that starts and ends with ---. Here’s an example:

---
title: Documentation Guide
---

Improving our documentation is one of the easiest ways to start contributing to
Morio. So if you spot a mistake or see something that you can improve, please
do not hesitate to do so.

Title​

The title entry is mandatory. In other words, every documentation page must have its title set in front matter.

As in YAML, you do not have to wrap your title in quotes, unless when it holds characters that would trip up the YAML parser (like when your title itself includes quotations marks).

Supported front matter

For an overview of all supported front matter, see the Docusaurus documentation on front matter in docs

Tags​

The front matter example above can be further extended to add tags to the page. Here is an example:

---
title: Documentation Guide
tags:
  - contributors
---

Improving our documentation is one of the easiest ways to start contributing to
Morio. So if you spot a mistake or see something that you can improve, please
do not hesitate to do so.

We have added the contributors tag to this page, marking it as a page that is relevant for Morio contributors.

Tags are a way to group pages together that cover the same topic or category. Docusaurus will automatically create an overview page of all documentation that is tagged with any given tag.

For example, the pages tagged with contributors can be found at /docs/tags/contributors. Docusaurus will also include the tags at the bottom of the page, and they link to their overview pages.

Tags are most useful as a carefully curated collection of pointers. To ensure that, all tags must be defined in the docs/docs/tags.yml file.

Source Code

github.com/certeu/morio/blob/develop/docs/docs/tags.yml

The file holds tags that can be defined as such (using our contributors tag as an example):

contributors:
  label: Contributors
  permalink: /docs/tags/contributors
  description: Documentation relevant for contributors

As you can see, you can explicitly set a label, permalink, and description. However, we just rely on the defaults, so you will define the tag and do not specify any properties. Here is how to do that in YAML:

contributors:

To add a tag, place it on a new line followed by :.

TIP

An overview of all tags is available at /docs/tags.

Keywords​

Keywords are like tags but they are not centrally manages, and no pages are created to link together the pages with the same keywords.

Instead, their use is intended to enhance search results as Docusaurus will use them to populate the HTML meta tags of the page.

Here is an example:

---
title: Documentation Guide
keywords:
  - contributors
  - documentation
  - markdown
  - mdx
---

Custom components​

Docusaurus supports which is markdown with support for custom components. A number of MDX components are supported out of the box, like the tabs used on this page.

In addition, we provide some MDX components that you can use in documentation pages. They provide various ways to engage the reader with the material.

Comment​

The Comment custom component allows you to insert a comment.

<Comment by='joost'>
  Comments are most useful when something is opinion, rather than fact.
</Comment>

<Comment by='Joost' title="My title" compact>
  Compact view with custom title
</Comment>

<Comment>The `by` prop is mandatory</Comment>

Fixme​

The Fixme custom component allows you to insert a message indicating something needs work.

<Fixme>
Use this to indicate something needs work or is incomplete.
</Fixme>

<Fixme by='joost' title="My title" compact>
  Compact view with custom title
</Fixme>

Important​

The Important custom component allows you to insert a message indicating something is important.

<Important>Drink plenty of fluids</Important>

<Important by='Joost' title="My title" compact>
  Compact view with custom title
</Important>

Note​

The Note custom component allows you to insert something you want to draw the reader’s attention to.

<Note>
This is a good way to draw the reader's attention to additional information.
</Note>

<Note by='Joost' title="My title" compact>
  Compact view with custom title
</Note>

RepoFile​

The RepoFile custom component allows you to create a link to a file in the . The link will point to the same file on GitHub, specifically in the default develop branch.

To see this example, check out <RepoFile>/docs/guides/contributors/docs/readme.mdx</RepoFile>.

Scode​

The Scode custom component allows you to insert a message with links to the relevant source code.

<Scode>
The Morio source code is available at [github.com/certeu/morio](https://github.com/certeu/morio).
</Scode>

<Scode by='Joost' title="My title" compact>
  Compact view with custom title
</Scode>

Tip​

The Tip custom component allows you to insert a message with one or more tips for the reader.

<Tip>Good advice goes here</Tip>

<Tip by='Joost' title="My title" compact>
  Compact view with custom title
</Tip>

Warning​

The Warning custom component allows you to insert a message that warns the reader about potential consequences.

<Warning>
Use this when a certain action is potentially destructive or problems are likely to occur.
</Warning>

<Warning by='Joost' title="My title" compact>
  Compact view with custom title
</Warning>

WithCaption​

The WithCaption custom component allows you to place a caption under any content.

<WithCaption caption="This allows you to put a caption under anything">
![Placeholder image](https://dummyimage.com/1200x400/3/a&text=It's-a%20me,%20Morio!)
</WithCaption>

Jargon and Terminology​

It is common in technical documentation to use terms or acronyms that the reader might not be familiar with. This can create a barrier to readers, especially when those terms are specific to Morio.

To address this, we have extended Docusaurus with two custom features that help you demystify this type of content: jargon and terminology.

NOTE

Jargon vs Terminology​

Both jargon and terminology can be anything that needs explaining. The difference is that jargon does not warrant or require its own dedicated documentation page.

Jargon​

Creating a jargon term​

To create a new jargon term, create a term.mdx file under docs/docs/jargon.

The name of the file (term in our example) should follow the same rules as folders under docs/docs: use only the characters a-z, 0-9, and -.

Inside the file, write content like like in a regular documentation page.

Jargon front matter​

Jargon terms have the following properties that can be set in front matter and are used to render them on the page:

  • title
    • description: The title used when displaying the jargon term’s info
    • default: The file’s uppercased basename
    • custom: The front matter title value
  • term
    • description: The term that will trigger rendering the jargon term when emphasised
    • default: The file’s lowercased basename
    • custom: The front matter term value
  • aliases
    • description: A list of additional terms that will trigger rendering the jargon term when emphasised.
    • default: none
    • custom: The front matter aliases value (an array of strings)
  • content
    • description: The main content when displaying the jargon term’s info
    • default: The file’s markdown content
    • custom: none

Examples​

Let’s use two examples to illustrate the use of default versus custom values for jargon properties:

This docs/docs/jargon/mdx.md example uses only defaults.

  • title: MDX (the uppercased basename is used as default)
  • term: mdx (the lowercased basename is used as default)
  • aliases: [] (no aliases is default)

In a case like this, your markdown file does not need any front matter:

docs/docs/jargon/mdx.md
MDX lets you use JSX in your markdown content. It allows you to import
components, and embed them within your content. This makes writing markdown
with custom components a blast.

Learn more at [mdxjs.com](chttps://mdxjs.com).

Using a jargon term​

Once you have created a jargon term, you can use it by emphasising it in your content.

For example, this markdown:

I have no idea what _mdx_ is.

Will render as:

I have no idea what is.

The jargon term will be turned into a button that you can click to reveal the meaning of the term.

TIP

Jargon terms are case-insensitive​

You can write , , or even , they will all trigger rendering the mdx jargon term.

List of jargon terms​

The following jargon terms are currently available for use in your markdown content:

Use AsInfo
_ami_
AMI

An Amazon Machine Image (AMI) is a type of virtual machine image format suitable for deployment on the EC2 compute service of Amazon Web Services (AWS).

_aws_
AWS

Amazon Web Services is the world's largest cloud service provider.

Learn more at aws.amazon.com.

_cert-eu_
CERT-EU

CERT-EU is the Cybersecurity Service for the Institutions, Bodies, Offices and Agencies of the European Union, the home of Morio.

Learn more at cert.europa.eu.

_ci_
CI

CI stands for Continuous Integration. In the context of Morio, we use it as shorthand for CI/CD, which combines CI with Continuous Deployment. We use CI to refer to the automation in building, testing, and deploying changes in software.

To learn more, the CI and CI/CD articles on Wikipedia are a good starting point.

_dry_
DRY

In programming, DRY stands for Don’t Repeat Yourself. The idea being that you should not write the same thing twice, rather everything should have its place.

This way, when you need to make a change, you only need to change it in one place.

_fqdn_
FQDN

FQDN stands for Fully Qualified Domain Name, a name the specifies the exact location of a host by combining host name and domain name.

apt.repo.morio.it is an example of an FQDN.

_iicb_
IICB

The IICB is the European Union's Interinstitutional Cybersecurity Board and the governing body of CERT-EU, the home of Morio.

_mdx_
MDX

MDX lets you use JSX in your markdown content. It allows you to import components, and embed them within your content. This makes writing markdown with custom components a blast.

Learn more at mdxjs.com.

_monorepo_
Monorepo

A monorepo is a repository that combines source code for different project, packages, or services into a single source code repository. This facilitates sharing code, functionality, and dependencies.

The Morio monorepo, or monorepo for short, is the repository hosting the Morio source code.

You can find it at github.com/certeu/morio

_mtls_
mTLS

mTLS or Mutual TLS utilises Transport Layer Security (TLS) to not only authenticate the server by its certificate, but also the client.

It is an authentication method that identifies both parties with a certificate, rather than the much more common TLS where only the server is identified.

_pkce_
PKCE

Proof Key for Code Exchange or PKCE (pronounced pixy) is an OpenID Connect flow that is specifically designed to protect against authorisation code interception attacks.

It is typically used in scenarios where the client secret cannot be protected, such as native mobile apps, or single page applications.

While the Morio UI service is a single page application, any OpenID Connect client secret is not available in the frontend code since the OpenID flow is initiated by the Morio API service.

Still, Morio implements the PKCE flow for OpenID Connect as an extra layer of protection according to the defence in depth principle.

_run scripts_ or _run script_
Run scripts

NPM run scripts, or run scripts for short, refer to scripts defined in the scripts section of a NodeJS package.json file. These scripts are typically used for all sorts of housekeeping an automation.

For more info, refer to the NPM docs on scripts.

_workspaces_ or _workspace_
Workspaces

NPM workspaces is is a generic term that refers to the set of features in the npm cli that facilitate handling NodeJS dependencies inside a monorepo.

For example, both the core and api folders rely on common dependencies. Rather than installing them twice, through the use of workspaces they will be installed the monorepo root, and shared.

There is more to workspaces, as it is a somewhat advanced feature of NPM, but that's not really relevant for Morio. If you want to learn more, refer to the NPM documentation on workspaces.

Terminology​

Creating a terminology page​

To create a new terminology page, create a folder under /docs/docs/reference/terminology.
The name of the folder should follow the same rules as any folders under docs/docs: use only the characters a-z, 0-9, and -.

Then, add a readme.mdx file to the folder as you would for any documentation page.

Terminology properties​

Terminology terms have the following properties that are set in front matter and control how they are rendered on the page:

  • title
    • description: The text used when displaying the terminology link
    • default: The front matter title value
  • term
    • description: The term that will trigger rendering the terminology link when emphasised
    • default: The file’s lowercased basename with dashed replaced by spaces (core-service becomes core service)
    • custom: The front matter term value
  • aliases
    • description: A list of additional terms that will trigger rendering the terminology link when emphasised.
    • default: none
    • custom: The front matter aliases value (an array of strings)

Below is an example:

docs/docs/jargon/mdx.md
---
title: Core Service
aliases:
  - core
tags:
  - core
---

The **Morio Core Service** (core) sits at the root of any Morio deployment and is
responsible for [orchestration](#orchestration), [configuration
resolution](#configuration-resolution), and [clustering](#clustering).

To learn more, visit [the Core Service guide](/docs/guides/services/core).

Using a terminology term​

Once you have created a terminology term, you can use it by emphasising the page title in your markdown content. This will turn the terminology term into a link that leads to the terminology page:

I want to learn more about _core_. Is it the same as the _core service_?

Will render as:

I want to learn more about core. Is it the same as the core service?

TIP

Terminology terms are case-insensitive​

You can write core, CORE, or even cORe, they will all trigger rendering the core terminology link.

List of terminology pages​

The following terminology pages are currently available for use in your markdown content:

Use asLinks to
_api service_ or _api_/docs/reference/terminology/api-service
_broker node_ or _broker nodes_/docs/reference/terminology/broker-node
_broker service_ or _broker_/docs/reference/terminology/broker-service
_ca service_ or _ca_/docs/reference/terminology/ca-service
_connector service_ or _connector_/docs/reference/terminology/connector-service
_console service_ or _console_/docs/reference/terminology/console-service
_core service_ or _core_/docs/reference/terminology/core-service
_db service_ or _db_/docs/reference/terminology/db-service
_dbuilder service_ or _dbuilder_/docs/reference/terminology/dbuilder-service
_ephemeral mode_/docs/reference/terminology/ephemeral-mode
_ephemeral node_/docs/reference/terminology/ephemeral-node
_flanking node_ or _flanking nodes_/docs/reference/terminology/flanking-node
_flanking service_/docs/reference/terminology/flanking-service
_identity provider_ or _idps_ or _idp_ or _identity provider_/docs/reference/terminology/identity-provider
_mbuilder service_ or _mbuilder_/docs/reference/terminology/mbuilder-service
_moriod_/docs/reference/terminology/moriod
_morio root token_ or _mrt_ or _Morio root token_/docs/reference/terminology/mrt
_preseed_ or _preseeding_/docs/reference/terminology/preseed
_proxy service_ or _proxy_/docs/reference/terminology/proxy-service
_rbuilder service_ or _rbuilder_/docs/reference/terminology/rbuilder-service
_reseeding_ or _reseed_ or _reseeding event_/docs/reference/terminology/reseeding
_settings_ or _morio settings_/docs/reference/terminology/settings
_staging instance_/docs/reference/terminology/staging-instance
_ui service_ or _ui_/docs/reference/terminology/ui-service
_wbuilder service_ or _wbuilder_/docs/reference/terminology/wbuilder-service

Includes​

Sometimes, you may find yourself repeating the same information on various documentation pages. You could create a page for it and link to it, but perhaps it’s more elegant to inline the information in the page.

In a case like this, you can use an include. This allows you import content into your documentation page.

Creating an include page​

To create an include page, add the page to the docs/includes folder in the .

Unlike the docs/docs folder where we rely on folder structure, all files should be in the same folder.

As such, you should give it a name that conveys the intent of the include. As a practical example, the difference between the built container images for the development environment and production is something that is relevant on various documentation pages.

So, the documentation is kept in the docs/includes/docker-env-diffs.mdx file.

Importing and using the include file​

Once created, you can import the file as any other import in your readme.mdx:

---
title: Example of how to use an include
---

import DockerBuildEnvDiffs from '@site/includes/docker-env-diffs.mdx'

Some (optinoal) other content here.

<DockerBuildEnvDiffs />

A few things to note:

  • The import statement should be the first thing after the front matter
  • Use the @site/includes/ prefix to import include files.
  • Since we are using the default export, the name you give it can by anything (here we used DockerBuildEndDiffs
  • This will be used as a React component, so you must pick a name that starts with a capital letter
  • Output the info as a React component: <DockerBuildEnvDiffs />

See docs/reference/contributors/monorepo/run-scripts/build-api/readme.mdx for an example.

Tips for writing great documentation​

Here is some friendly advice to help you write great documentation:

Don’t use gen-AI​

Writing yourself will make you a better writer.

NOTE

We take pride in the fact that all of Morio’s documentation is written by actual human beings.
Please respect that and don’t reach for ChatGPT or whatever the generative AI flavour of the day is.

Write now, edit later​

Just write. Don’t worry about grammar or making mistakes. It’s fine.

It doesn’t have to be perfect, it just needs to be written down.

Anybody can edit to improve form or structure, and the spellcheck and ci:spellcheck are there to help with spelling.

Use plain language​

Explain things in simple words. Write short plain sentences. Use headings and paragraphs to structure your writing.

Get to the point​

Say what you need to say — no more, no less.
Make your text as short as possible; your documentation will be better this way.

Page titles should be meaningful without context. They are the main result in search, so strive to make them meaningful and informative on their own.

That often means making your titles a lot longer, which doesn’t work well in the navigation sidebar. You can use the sidebar_label key in front matter to set a different title to use in the sidebar.:

To a lesser extend, the same advice applies to links:

Define jargon​

Don’t use jargon without giving readers an easy way to learn about it.

More advice​

The “Technical Writing From Google” course comes highly recommended.

Remember that the worst possible documentation is the documentation that is never written.

Running the documentation site locally​

NOTE

We assume you have git and NodeJS installed.

To run a local instance of the documentation site — highly recommended if you’re looking to make non-trivial changes to the documentation — you can follow these steps:

Terminal
git clone git@github.com:certeu/morio.git
cd morio
npm install
cd docs
npm run start

In other words:

  • Clone the repository
  • Install dependencies
  • Run npm run start in the docs folder

The docs site will now be running on http://localhost:3000 and any changes you make will be hot-reloaded.

WARNING

Untested on Windows​

While we support Microsoft Windows as a platform for the Morio client, no Microsoft Windows is used in the development of Morio. If you are on Windows, your mileage may vary.

Redoc Integration​

We generate our API reference documentation by using redocusaurus which integrates redoc in docusaurus.

The configuration is part of docs/docusaurus.config.js and it adds these two routes: