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.

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 are listed below.

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.

MDX

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

HTML

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

WithCaption

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

MDX

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

HTML

This allows you to put a caption under anything

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.

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:

Default

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).

Custom

This docs/docs/jargon/run-files.md example uses custom properties.

• title: Run scripts (default would have been run-scripts)
• term: run scripts (default would have been run-scripts)
• aliases: ['run script'] (default would have been no aliases)

In this case, all customisation is handled in the front matter:

docs/docs/jargon/run-scripts.md

---
title: Run scripts
term: run scripts
aliases:
  - run script
---

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](https://docs.npmjs.com/cli/v10/using-npm/scripts).

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.

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 As	Info
_abac_	ABAC Attribute-based access control (ABAC) is an abstraction to configure user permissions in computer systems, not unlike role-based access control (). The difference is in how permissions are mapped to users. With RBAC, each user has one or more roles that govern their access level. With ABAC, an attribute of the user's account info is used to assign privileges. A common example is to use group membership as a way to bestow privileges on users.
_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.
_gitops_	GITOPS GitOps is an operational framework that takes DevOps best practices used for application development such as version control, collaboration, compliance, and CI/CD, and applies them to infrastructure automation. GitOps Ebook GitLab has a free Ebook on gitops that is a good starting point to learn more.
_iam_	IAM Identity and Access Management (IAM) is all about who can do what. The who part is identity, and the what part is access management. Together, we refer to them as IAM. IAM strives to ensure that users have access to the correct resources. tip Wikipedia is a good source for more information on IAM
_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.
_rbac_	RBAC Role-based access control (RBAC) is an abstraction to configure user permissions in computer systems. Rather than assign rights to users directly, rights are assigned to roles. Users are then in turn assigned to one or more roles. For example, if user tony manages the support team and requires extra privileges to do their job, rather than assign those rights directly to Tony, with RBAC we will assign those rights to a manager role, and then assign that manager role to Tony.
_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?

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 as	Links 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
_cluster_	/docs/reference/terminology/cluster
_collector_	/docs/reference/terminology/collector
_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.

No Gen-AI please

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.

Use meaningful titles and hyperlinks

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:

• Bad: You can find the info here.
• Good: You can find the info by watching this YouTube video with 1.3 billion views

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.

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:

• /docs/reference/apis/api for the Management API
• /docs/reference/apis/core for the Core API