Documentation

• 1: Setup Local Environment
• 2: Write a new topic
• 3: Style Overview
• 3.1: Content Guide
• 3.2: Style Guide
• 3.3: Diagram Guide
• 3.4: Custom Hugo Shortcodes
• 4: Localizing UMH documentation
• 5: Versioning Documentation

1 - Setup Local Environment

The following instructions describe how to set up your local environment for contributing to United Manufacturing Hub documentation website.

You can use any text editor to contribute to the documentation. However, we recommend using Visual Studio Code with the Markdown All in One extension. Additional extensions that can be useful are:

• GoHugo
• Hugo Language and Syntax Support
• markdownlint

Requirements

The following tools are required to contribute to the documentation website. Use your preferred package manager to install them (for Windows users, we recommend using Chocolatey).

• Git
• Git LFS
• Hugo (Extended version) v0.111.3
• Node.js LTS v18.16.0

Other tools that are not required, but are recommended:

• GNU make to easily run scripts

Fork the documentation repository

If you are not a member of the United Manufacturing Hub organization, you will need to fork the repository to your own GitHub account. This is done by clicking the Fork button in the top-right corner of the united-manufacturing-hub/umh.docs.umh.app repository page.

Clone the repository

Clone the repository to your local machine:

git clone https://github.com/<user>/umh.docs.umh.app.git
# or: git clone [email protected]:<user>/umh.docs.umh.app.git

Where <user> is your GitHub username, or united-manufacturing-hub if you are a member of the United Manufacturing Hub organization.

If you are not a member of the United Manufacturing Hub organization, you will need to add the upstream repository as a remote:

git remote add upstream https://github.com/united-manufacturing-hub/umh.docs.umh.app.git

# Never push to upstream master
git remote set-url --push upstream no_push

Setup the environment

If you are running on a Windows system, manually install the above required tools.

If you are running on a Linux system, or can run a bash shell, you can use the following commands to install the required tools:

cd <path_to_your_repo>
make install

Run the development server

Now it’s time to run the server locally.

Navigate to the umh.docs.umh.app directory inside the repository you cloned earlier.

cd <path_to_your_repo>/umh.docs.umh.app

If you have not installed GNU make, run the following command:

hugo server --buildDrafts

Otherwise, run the following command:

make serve

Either method will start the local Hugo server on port 1313. Open up your browser to http://localhost:1313 to view the website. As you make changes to the source files, Hugo updates the website and forces a browser refresh.

You can stop the server by pressing Ctrl+C in the terminal.

What’s next

• Learn how to write a new topic.
• Get an overview of the documentation style.

2 - Write a new topic

Choosing a page type

As you prepare to write a new topic, think about the page type that would fit your content the best. We have many archetypes to choose from, and you can create a new one if none of the existing ones fit your needs.

Generally, each archetype is specific to a particular type of content. For example, the upgrading archetype is used for pages that describe how to upgrade to a new version of United Manufacturing Hub, and most of the content in the Production Guide section of the docs uses the tasks archetype.

In the content guide you can find a description of the most used archetypes. If you need to create a new archetype, you can find more information in the Hugo documentation.

Choosing a directory

The directory in which you put your file is mostly determined by the page type you choose.

If you think that your topic doesn’t belong to any of the existing sections, you should first discuss with the United Manufacturing Hub team where your topic should go. They will coordinate the creation of a new section if needed.

Choosing a title and filename

Choose a title that has the keywords you want search engines to find. Create a filename that uses the words in your title separated by hyphens. For example, the topic with title Access Factoryinsight Outside the Cluster has filename access-factoryinsight-outside-cluster.md. You don’t need to put “united manufacturing hub” in the filename, because “umh” is already in the URL for the topic, for example:

https://umh.docs.umh.app/docs/production-guide/administration/access-factoryinsight-outside-cluster/

Adding the topic title to the front matter

In your topic, put a title field in the front matter. The front matter is the YAML block that is between the triple-dashed lines at the top of the page. Here’s an example:

---
title: Access Factoryinsight Outside the Cluster
---

Most of the archetypes automatically create the page title using the filename, but always check that the title makes sense.

Creating a new page

Once you have chosen the archetype, the location, and the file name, you can create a new page using the hugo new command. For example, to create a new page using the tasks archetype, run the following command:

hugo new docs/production-guide/my-first-task.md -k tasks

Placing your topic in the table of contents

The table of contents is built dynamically using the directory structure of the documentation source. The top-level directories under /content/en/docs/ create top-level navigation, and subdirectories each have entries in the table of contents.

Each subdirectory has a file _index.md, which represents the “home” page for a given subdirectory’s content. The _index.md does not need a template. It can contain overview content about the topics in the subdirectory.

Other files in a directory are sorted alphabetically by default. This is almost never the best order. To control the relative sorting of topics in a subdirectory, set the weight: front-matter key to an integer. Typically, we use multiples of 10, to account for adding topics later. For instance, a topic with weight 10 will come before one with weight 20.

You can hide a topic from the table of contents by setting toc_hide: true, and you can hide the list of child pages at the botton of an _index.md file by setting no_list: true.

Embedding code in your topic

If you want to include some code in your topic, you can embed the code in your file directly using the markdown code block syntax. This is recommended for the following cases (not an exhaustive list):

• The code shows the output from a command such as kubectl get deploy mydeployment -o json | jq '.status'.
• The code is not generic enough for users to try out.
• The code is an incomplete example because its purpose is to highlight a portion of a larger file.
• The code is not meant for users to try out due to other reasons.

Including code from another file

Another way to include code in your topic is to create a new, complete sample file (or group of sample files) and then reference the sample from your topic. Use this method to include sample YAML files when the sample is generic and reusable, and you want the reader to try it out themselves.

When adding a new standalone sample file, such as a YAML file, place the code in one of the <LANG>/examples/ subdirectories where <LANG> is the language for the topic. In your topic file, use the codenew shortcode:

{{< codenew file="<RELPATH>/my-example-yaml>" >}}

where <RELPATH> is the path to the file to include, relative to the examples directory. The following Hugo shortcode references a YAML file located at /content/en/examples/pods/storage/gce-volume.yaml.

{{< codenew file="pods/storage/gce-volume.yaml" >}}

Adding images to a topic

Put image files in the /static/images directory. The preferred image format is SVG. Organize images in subdirectories under /static/images as needed.

Add images to the page using markdown image syntax:

![Alt text](/images/my-image.svg)

What’s next

• Read the content guidelines.
• Learn about content styling.

3 - Style Overview

The topics in this section provide guidance on writing style, content formatting and organization, and using Hugo customizations specific to UMH documentation.

3.1 - Content Guide

In this guide, you’ll find guidelines regarding the content for the United Manufacturing Hub documentation, that is what content is allowed and how to organize it.

For information about the styling, follow the style guide, and for a quick guide to writing a new page, follow the quick start guide.

What’s allowed

United Manufacturing Hub docs allow content for third-party projects only when:

• Content documents software in the United Manufacturing Hub project
• Content documents software that’s out of project but necessary for United Manufacturing Hub to function

Sections

The United Manufacturing Hub documentation is organized into sections. Each section contains a specific set of pages that are relevant to a user goal.

Get started

The Get started section contains information to help new users get started with the United Manufacturing Hub. It’s the first section a reader sees when visiting the website, and it guides users through the installation process.

Features

The Features section contains information about the capabilities of the United Manufacturing Hub. It’s a high-level overview of the project’s features, and it’s intended for users who want to learn more about them without diving into the technical details.

Data Model

The Data Model section contains information about the data model of the United Manufacturing Hub. It’s intended for users who want to learn more about the data model of the United Manufacturing Hub and how it’s used by the different components of the project.

Architecture

The Architecture section contains technical information about the United Manufacturing Hub. It’s intended for users who want to learn more about the project’s architecture and design decisions. Here there are information about the different components of the United Manufacturing Hub and how they interact with each other.

Production Guide

The Production Guide section contains a series of guides that help users to set up and operate the United Manufacturing Hub.

What’s New

The What’s New section contains high-level overview of all the releases of the United Manufacturing Hub. Usually, only the last 3 to 4 releases are displayed in the sidebar, but all the releases are available in the section page.

Reference

The Reference section contains technical information about the different components of the United Manufacturing Hub. It’s intended for users who want to learn more about the different components of the project and how they work.

Development

The Development section contains information about contributing to the United Manufacturing Hub project. It’s intended for users who want to contribute to the project, either by writing code or documentation.

Page Organization

This site uses Hugo. In Hugo, content organization is a core concept.

Page Lists

Page Order

The documentation side menu, the documentation page browser etc. are listed using Hugo’s default sort order, which sorts by weight (from 1), date (newest first), and finally by the link title.

Given that, if you want to move a page or a section up, set a weight in the page’s front matter:

title: My Page
weight: 10

For page weights, it can be smart not to use 1, 2, 3 …, but some other interval, say 10, 20, 30… This allows you to insert pages where you want later. Additionally, each weight within the same directory (section) should not be overlapped with the other weights. This makes sure that content is always organized correctly, especially in localized content.

In some sections, like the What’s New section, it’s easier to manage the order using a negative weight. This is because the What’s New section is organized by release version, and the release version is a string, so it’s easier to use a negative weight to sort the releases in the correct order.

Side Menu

The documentation side-bar menu is built from the current section tree starting below docs/.

It will show all sections and their pages.

If you don’t want to list a section or page, set the toc_hide flag to true in front matter:

toc_hide: true

When you navigate to a section that has content, the specific section or page (e.g. _index.md) is shown. Else, the first page inside that section is shown.

Page Bundles

In addition to standalone content pages (Markdown files), Hugo supports Page Bundles.

One example is Custom Hugo Shortcodes. It is considered a leaf bundle. Everything below the directory, including the index.md, will be part of the bundle. This also includes page-relative links, images that can be processed etc.:

en/docs/home/contribute/includes
├── example1.md
├── example2.md
├── index.md
└── podtemplate.json

Another widely used example is the includes bundle. It sets headless: true in front matter, which means that it does not get its own URL. It is only used in other pages.

en/includes
├── default-storage-class-prereqs.md
├── index.md
├── partner-script.js
├── partner-style.css
├── task-tutorial-prereqs.md
├── user-guide-content-moved.md
└── user-guide-migration-notice.md

Some important notes to the files in the bundles:

• For translated bundles, any missing non-content files will be inherited from languages above. This avoids duplication.
• All the files in a bundle are what Hugo calls Resources and you can provide metadata per language, such as parameters and title, even if it does not supports front matter (YAML files etc.). See Page Resources Metadata.
• The value you get from .RelPermalink of a Resource is page-relative. See Permalinks.

Page Content Types

Hugo uses archetypes to define page types. The archetypes are located in the archetypes directory.

Each archetype informally defines its expected page structure. There are two main archetypes, described below, but it’s possible to create new archetypes for specific page types that are frequently used.

To create a new page using an archetype, run the following command:

hugo new -k <archetype> docs/<section>/<page-name>.md

Content Types

Concept

A concept page explains some aspect of United Manufacturing Hub. For example, a concept page might describe a specific component of the United Manufacturing Hub and explain the role it plays as an application while it is deployed, scaled, and updated. Typically, concept pages don’t include sequences of steps, but instead provide links to tasks or tutorials.

To write a new concept page, create a Markdown file with the following characteristics:

Concept pages are divided into three sections:

The overview and body sections appear as comments in the concept page. You can add the whatsnext section to your page with the heading shortcode.

Fill each section with content. Follow these guidelines:

• Organize content with H2 and H3 headings.
• For overview, set the topic’s context with a single paragraph.
• For body, explain the concept.
• For whatsnext, provide a bulleted list of topics (5 maximum) to learn more about the concept.

Task

A task page shows how to do a single thing. The idea is to give readers a sequence of steps that they can actually do as they read the page. A task page can be short or long, provided it stays focused on one area. In a task page, it is OK to blend brief explanations with the steps to be performed, but if you need to provide a lengthy explanation, you should do that in a concept topic. Related task and concept topics should link to each other.

To write a new task page, create a Markdown file with the following characteristics:

The overview, steps, and discussion sections appear as comments in the task page. You can add the prerequisites and whatsnext sections to your page with the heading shortcode.

Within each section, write your content. Use the following guidelines:

• Use a minimum of H2 headings (with two leading # characters). The sections themselves are titled automatically by the template.
• For overview, use a paragraph to set context for the entire topic.
• For prerequisites, use bullet lists when possible. Start adding additional prerequisites below the include. The default prerequisites include a running Kubernetes cluster.
• For steps, use numbered lists.
• For discussion, use normal content to expand upon the information covered in steps.
• For whatsnext, give a bullet list of up to 5 topics the reader might be interested in reading next.

For an example of a short task page, see Expose Grafana to the internet. For an example of a longer task page, see Access the database

Content Sections

Each page content type contains a number of sections defined by Markdown comments and HTML headings. You can add content headings to your page with the heading shortcode. The comments and headings help maintain the structure of the page content types.

Examples of Markdown comments defining page content sections:

<!-- overview -->

<!-- body -->

To create common headings in your content pages, use the heading shortcode with a heading string.

Examples of heading strings:

• whatsnext
• prerequisites
• objectives
• cleanup
• synopsis
• seealso
• options

For example, to create a whatsnext heading, add the heading shortcode with the “whatsnext” string:

## {{% heading "whatsnext" %}}

You can declare a prerequisites heading as follows:

## {{% heading "prerequisites" %}}

The heading shortcode expects one string parameter. The heading string parameter matches the prefix of a variable in the i18n/<lang>.toml files. For example:

i18n/en.toml:

[heading_whatsnext]
other = "What's next"

What’s next

• Read the Style guide.

3.2 - Style Guide

This page gives writing style guidelines for the United Manufacturing Hub documentation. These are guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.

For additional information on creating new content for the United Manufacturing Hub documentation, read the Documentation Content Guide.

Language

The United Manufacturing Hub documentation has not been translated yet. But if you want to help with that, you can check out the localization page.

Documentation formatting standards

Use upper camel case for Kubernetes objects

When you refer specifically to interacting with a Kubernetes object, use UpperCamelCase, also known as Pascal case.

When you are generally discussing a Kubernetes object, use sentence-style capitalization.

The following examples focus on capitalization. For more information about formatting Kubernetes object names, review the related guidance on Code Style.

Use angle brackets for placeholders

Use angle brackets for placeholders. Tell the reader what a placeholder represents, for example:

Display information about a pod:

kubectl describe pod <pod-name> -n <namespace>

Use bold for user interface elements

Use italics to define or introduce new terms

Use code style for filenames, directories, and paths

Use the international standard for punctuation inside quotes

Inline code formatting

Use code style for inline code, commands, and API objects

For inline code in an HTML document, use the <code> tag. In a Markdown document, use the backtick (`).

The website supports syntax highlighting for code samples, but specifying a language is optional. Syntax highlighting in the code block should conform to the contrast guidelines.

Use code style for object field names and namespaces

Use code style for command tools and component names

Starting a sentence with a component tool or component name

Use a general descriptor over a component name

Use normal style for string and integer field values

For field values of type string or integer, use normal style without quotation marks.

Code snippet formatting

Don’t include the command prompt

Separate commands from output

Verify that the pod is running on your chosen node:

kubectl get pods --output=wide

The output is similar to this:

NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
nginx    1/1       Running   0          13s    10.200.0.4   worker0

Versioning United Manufacturing Hub examples

Code examples and configuration examples that include version information should be consistent with the accompanying text.

If the information is version specific, the United Manufacturing Hub version needs to be defined in the prerequisites section of the Task template or the Tutorial template. Once the page is saved, the prerequisites section is shown as Before you begin.

To specify the United Manufacturing Hub version for a task or tutorial page, include minimum-version in the front matter of the page.

If the example YAML is in a standalone file, find and review the topics that include it as a reference. Verify that any topics using the standalone YAML have the appropriate version information defined. If a stand-alone YAML file is not referenced from any topics, consider deleting it instead of updating it.

For example, if you are writing a tutorial that is relevant to United Manufacturing Hub version 0.9.11, the front-matter of your markdown file should look something like:

---
title: <your tutorial title here>
minimum-version: 0.9.11
---

In code and configuration examples, do not include comments about alternative versions. Be careful to not include incorrect statements in your examples as comments, such as:

apiVersion: v1 # earlier versions use...
kind: Pod
...

United Manufacturing Hub word list

A list of UMH-specific terms and words to be used consistently across the site.

Shortcodes

Hugo Shortcodes help create different rhetorical appeal levels.

There are multiple custom shortcodes that can be used in the United Manufacturing Hub documentation. Refer to the shortcode guide for more information.

Markdown elements

Line breaks

Use a single newline to separate block-level content like headings, lists, images, code blocks, and others. The exception is second-level headings, where it should be two newlines. Second-level headings follow the first-level (or the title) without any preceding paragraphs or texts. A two line spacing helps visualize the overall structure of content in a code editor better.

Headings and titles

People accessing this documentation may use a screen reader or other assistive technology (AT). Screen readers are linear output devices, they output items on a page one at a time. If there is a lot of content on a page, you can use headings to give the page an internal structure. A good page structure helps all readers to easily navigate the page or filter topics of interest.

Paragraphs

Links

Lists

Group items in a list that are related to each other and need to appear in a specific order or to indicate a correlation between multiple items. When a screen reader comes across a list—whether it is an ordered or unordered list—it will be announced to the user that there is a group of list items. The user can then use the arrow keys to move up and down between the various items in the list. Website navigation links can also be marked up as list items; after all they are nothing but a group of related links.

• End each item in a list with a period if one or more items in the list are complete sentences. For the sake of consistency, normally either all items or none should be complete sentences.

  Ordered lists that are part of an incomplete introductory sentence can be in lowercase and punctuated as if each item was a part of the introductory sentence.

• Use the number one (1.) for ordered lists.

• Use (+), (*), or (-) for unordered lists.

• Leave a blank line after each list.

• Indent nested lists with four spaces (for example, ⋅⋅⋅⋅).

• List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by either four spaces or one tab.

Tables

The semantic purpose of a data table is to present tabular data. Sighted users can quickly scan the table but a screen reader goes through line by line. A table caption is used to create a descriptive title for a data table. Assistive technologies (AT) use the HTML table caption element to identify the table contents to the user within the page structure.

• Add table captions using Hugo shortcodes for tables.

Content best practices

This section contains suggested best practices for clear, concise, and consistent content.

Use present tense

Exception: Use future or past tense if it is required to convey the correct meaning.

Use active voice

Exception: Use passive voice if active voice leads to an awkward construction.

Use simple and direct language

Use simple and direct language. Avoid using unnecessary phrases, such as saying “please.”

Address the reader as “you”

Avoid Latin phrases

Prefer English terms over Latin abbreviations.

Exception: Use “etc.” for et cetera.

Patterns to avoid

Avoid using “we”

Using “we” in a sentence can be confusing, because the reader might not know whether they’re part of the “we” you’re describing.

Avoid jargon and idioms

Some readers speak English as a second language. Avoid jargon and idioms to help them understand better.

Avoid statements about the future

Avoid making promises or giving hints about the future. If you need to talk about an alpha feature, put the text under a heading that identifies it as alpha information.

An exception to this rule is documentation about announced deprecations targeting removal in future versions.

Avoid statements that will soon be out of date

Avoid words like “currently” and “new.” A feature that is new today might not be considered new in a few months.

Avoid words that assume a specific level of understanding

Avoid words such as “just”, “simply”, “easy”, “easily”, or “simple”. These words do not add value.

What’s next

• Learn how to write a new topic.
• Read the Content guide.

3.3 - Diagram Guide

This guide is taken from the Kubernets documentation, so there might be some references to Kubernetes that are not relevant to United Manufacturing Hub.

This guide shows you how to create, edit and share diagrams using the Mermaid JavaScript library. Mermaid.js allows you to generate diagrams using a simple markdown-like syntax inside Markdown files. You can also use Mermaid to generate .svg or .png image files that you can add to your documentation.

The target audience for this guide is anybody wishing to learn about Mermaid and/or how to create and add diagrams to United Manufacturing Hub documentation.

Figure 1 outlines the topics covered in this section.

All you need to begin working with Mermaid is the following:

• Basic understanding of markdown.
• Using the Mermaid live editor.
• Using Hugo shortcodes.
• Using the Hugo {{< figure >}} shortcode.
• Performing Hugo local previews.
• Familiar with the Contributing new content process.

You can click on each diagram in this section to view the code and rendered diagram in the Mermaid live editor.

Why you should use diagrams in documentation

Diagrams improve documentation clarity and comprehension. There are advantages for both the user and the contributor.

The user benefits include:

• Friendly landing spot. A detailed text-only greeting page could intimidate users, in particular, first-time United Manufacturing Hub users.
• Faster grasp of concepts. A diagram can help users understand the key points of a complex topic. Your diagram can serve as a visual learning guide to dive into the topic details.
• Better retention. For some, it is easier to recall pictures rather than text.

The contributor benefits include:

• Assist in developing the structure and content of your contribution. For example, you can start with a simple diagram covering the high-level points and then dive into details.
• Expand and grow the user community. Easily consumed documentation augmented with diagrams attracts new users who might previously have been reluctant to engage due to perceived complexities.

You should consider your target audience. In addition to experienced UMH users, you will have many who are new to United Manufacturing Hub. Even a simple diagram can assist new users in absorbing United Manufacturing Hub concepts. They become emboldened and more confident to further explore United Manufacturing Hub and the documentation.

Mermaid

Mermaid is an open source JavaScript library that allows you to create, edit and easily share diagrams using a simple, markdown-like syntax configured inline in Markdown files.

The following lists features of Mermaid:

• Simple code syntax.
• Includes a web-based tool allowing you to code and preview your diagrams.
• Supports multiple formats including flowchart, state and sequence.
• Easy collaboration with colleagues by sharing a per-diagram URL.
• Broad selection of shapes, lines, themes and styling.

The following lists advantages of using Mermaid:

• No need for separate, non-Mermaid diagram tools.
• Adheres to existing PR workflow. You can think of Mermaid code as just Markdown text included in your PR.
• Simple tool builds simple diagrams. You don’t want to get bogged down (re)crafting an overly complex and detailed picture. Keep it simple!

Mermaid provides a simple, open and transparent method for the SIG communities to add, edit and collaborate on diagrams for new or existing documentation.

You can still use Mermaid to create/edit diagrams even if it’s not supported in your environment. This method is called Mermaid+SVG and is explained below.

Live editor

The Mermaid live editor is a web-based tool that enables you to create, edit and review diagrams.

The following lists live editor functions:

• Displays Mermaid code and rendered diagram.
• Generates a URL for each saved diagram. The URL is displayed in the URL field of your browser. You can share the URL with colleagues who can access and modify the diagram.
• Option to download .svg or .png files.

The live editor is the easiest and fastest way to create and edit Mermaid diagrams.

Methods for creating diagrams

Figure 2 outlines the three methods to generate and add diagrams.

Figure 2. Methods to create diagrams.

Inline

Figure 3 outlines the steps to follow for adding a diagram using the Inline method.

The following lists the steps you should follow for adding a diagram using the Inline method:

1. Create your diagram using the live editor.
2. Store the diagram URL somewhere for later access.
3. Copy the mermaid code to the location in your .md file where you want the diagram to appear.
4. Add a caption below the diagram using Markdown text.

A Hugo build runs the Mermaid code and turns it into a diagram.

You may find keeping track of diagram URLs is cumbersome. If so, make a notice note in the .md file that the Mermaid code is self-documenting. Contributors can copy the Mermaid code to and from the live editor for diagram edits.

Here is a sample code snippet contained in an .md file:

---
title: My PR
---
Figure 17 shows a simple A to B process.
some markdown text
...
{{< mermaid >}} 
    graph TB
    A --> B
{{< /mermaid >}}

Figure 17. A to B
more text

You must include the Hugo Mermaid shortcode tags at the start and end of the Mermaid code block. You should add a diagram caption below the diagram.

For more details on diagram captions, see How to use captions.

The following lists advantages of the Inline method:

• Live editor tool.
• Easy to copy Mermaid code to and from the live editor and your .md file.
• No need for separate .svg image file handling.
• Content text, diagram code and diagram caption contained in the same .md file.

You should use the local and Cloudflare previews to verify the diagram is properly rendered.

The Mermaid live editor feature set may not support the umh/umh.docd.umh.app Mermaid feature set. You might see a syntax error or a blank screen after the Hugo build. If that is the case, consider using the Mermaid+SVG method.

Mermaid+SVG

Figure 4 outlines the steps to follow for adding a diagram using the Mermaid+SVG method.

Figure 4. Mermaid+SVG method steps.

The following lists the steps you should follow for adding a diagram using the Mermaid+SVG method:

1. Create your diagram using the live editor.
2. Store the diagram URL somewhere for later access.
3. Generate an .svg image file for the diagram and download it to the appropriate images/ folder.
4. Use the {{< figure >}} shortcode to reference the diagram in the .md file.
5. Add a caption using the {{< figure >}} shortcode’s caption parameter.

For example, use the live editor to create a diagram called boxnet. Store the diagram URL somewhere for later access. Generate and download a boxnet.svg file to the appropriate ../images/ folder.

Use the {{< figure >}} shortcode in your PR’s .md file to reference the .svg image file and add a caption.

{{< figure src="/static/images/boxnet.svg" alt="Boxnet figure" class="diagram-large" caption="Figure 14. Boxnet caption" >}}

For more details on diagram captions, see How to use captions.

The {{< figure >}} shortcode is the preferred method for adding .svg image files to your documentation. You can also use the standard markdown image syntax like so: ![my boxnet diagram](/static/images/boxnet.svg). And you will need to add a caption below the diagram.

You should add the live editor URL as a comment block in the .svg image file using a text editor. For example, you would include the following at the beginning of the .svg image file:

<!-- To view or edit the mermaid code, use the following URL: -->
<!-- https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb ... <remainder of the URL> -->

The following lists advantages of the Mermaid+SVG method:

• Live editor tool.
• Live editor tool supports the most current Mermaid feature set.
• Employ existing umh/website methods for handling .svg image files.
• Environment doesn’t require Mermaid support.

Be sure to check that your diagram renders properly using the local and Netlify previews.

External tool

Figure 5 outlines the steps to follow for adding a diagram using the External Tool method.

First, use your external tool to create the diagram and save it as an .svg or .png image file. After that, use the same steps as the Mermaid+SVG method for adding .svg image files.

The following lists the steps you should follow for adding a diagram using the External Tool method:

1. Use your external tool to create a diagram.
2. Save the diagram coordinates for contributor access. For example, your tool may offer a link to the diagram image, or you could place the source code file, such as an .xml file, in a public repository for later contributor access.
3. Generate and save the diagram as an .svg or .png image file. Download this file to the appropriate ../images/ folder.
4. Use the {{< figure >}} shortcode to reference the diagram in the .md file.
5. Add a caption using the {{< figure >}} shortcode’s caption parameter.

Here is the {{< figure >}} shortcode for the images/apple.svg diagram:

{{< figure src="/static/images/apple.svg" alt="red-apple-figure" class="diagram-large" caption="Figure 9. A Big Red Apple" >}} 

If your external drawing tool permits:

• You can incorporate multiple .svg or .png logos, icons and images into your diagram. However, make sure you observe copyright and follow the United Manufacturing Hub documentation guidelines on the use of third party content.
• You should save the diagram source coordinates for later contributor access. For example, your tool may offer a link to the diagram image, or you could place the source code file, such as an .xml file, somewhere for contributor access.

The following lists advantages of the External Tool method:

• Contributor familiarity with external tool.
• Diagrams require more detail than what Mermaid can offer.

Don’t forget to check that your diagram renders correctly using the local and Netlify previews.

Examples

This section shows several examples of Mermaid diagrams.

The code block examples omit the Hugo Mermaid shortcode tags. This allows you to copy the code block into the live editor to experiment on your own. notice note that the live editor doesn't recognize Hugo shortcodes.

Example 1 - Pod topology spread constraints

Figure 6 shows the diagram appearing in the Pod topology spread constraints page.

Figure 6. Pod Topology Spread Constraints.

Code block:

graph TB
   subgraph "zoneB"
       n3(Node3)
       n4(Node4)
   end
   subgraph "zoneA"
       n1(Node1)
       n2(Node2)
   end
 
   classDef plain fill:#ddd,stroke:#fff,stroke-width:4px,color:#000;
   classDef k8s fill:#326ce5,stroke:#fff,stroke-width:4px,color:#fff;
   classDef cluster fill:#fff,stroke:#bbb,stroke-width:2px,color:#326ce5;
   class n1,n2,n3,n4 k8s;
   class zoneA,zoneB cluster;

Example 2 - Ingress

Figure 7 shows the diagram appearing in the What is Ingress page.

Code block:

graph LR;
 client([client])-. Ingress-managed <br> load balancer .->ingress[Ingress];
 ingress-->|routing rule|service[Service];
 subgraph cluster
 ingress;
 service-->pod1[Pod];
 service-->pod2[Pod];
 end
 classDef plain fill:#ddd,stroke:#fff,stroke-width:4px,color:#000;
 classDef k8s fill:#326ce5,stroke:#fff,stroke-width:4px,color:#fff;
 classDef cluster fill:#fff,stroke:#bbb,stroke-width:2px,color:#326ce5;
 class ingress,service,pod1,pod2 k8s;
 class client plain;
 class cluster cluster;

Example 3 - umh system flow WIP

Figure 8 depicts a Mermaid sequence diagram showing the system flow between umh components to start a container.

Code block:

%%{init:{"theme":"neutral"}}%%
sequenceDiagram
    actor me
    participant apiSrv as control plane<br><br>api-server
    participant etcd as control plane<br><br>etcd datastore
    participant cntrlMgr as control plane<br><br>controller<br>manager
    participant sched as control plane<br><br>scheduler
    participant kubelet as node<br><br>kubelet
    participant container as node<br><br>container<br>runtime
    me->>apiSrv: 1. kubectl create -f pod.yaml
    apiSrv-->>etcd: 2. save new state
    cntrlMgr->>apiSrv: 3. check for changes
    sched->>apiSrv: 4. watch for unassigned pods(s)
    apiSrv->>sched: 5. notify about pod w nodename=" "
    sched->>apiSrv: 6. assign pod to node
    apiSrv-->>etcd: 7. save new state
    kubelet->>apiSrv: 8. look for newly assigned pod(s)
    apiSrv->>kubelet: 9. bind pod to node
    kubelet->>container: 10. start container
    kubelet->>apiSrv: 11. update pod status
    apiSrv-->>etcd: 12. save new state

How to style diagrams

You can style one or more diagram elements using well-known CSS nomenclature. You accomplish this using two types of statements in the Mermaid code.

• classDef defines a class of style attributes.
• class defines one or more elements to apply the class to.

In the code for figure 7, you can see examples of both.

classDef k8s fill:#326ce5,stroke:#fff,stroke-width:4px,color:#fff; // defines style for the k8s class
class ingress,service,pod1,pod2 k8s; // k8s class is applied to elements ingress, service, pod1 and pod2.

You can include one or multiple classDef and class statements in your diagram.

For more information on styling and classes, see Mermaid Styling and classes docs.

How to use captions

A caption is a brief description of a diagram. A title or a short description of the diagram are examples of captions. Captions aren’t meant to replace explanatory text you have in your documentation. Rather, they serve as a “context link” between that text and your diagram.

The combination of some text and a diagram tied together with a caption help provide a concise representation of the information you wish to convey to the user.

Without captions, you are asking the user to scan the text above or below the diagram to figure out a meaning. This can be frustrating for the user.

Figure 9 lays out the three components for proper captioning: diagram, diagram caption and the diagram referral.

You should always add a caption to each diagram in your documentation.

Diagram

The Mermaid+SVG and External Tool methods generate .svg image files.

Here is the {{< figure >}} shortcode for the diagram defined in an .svg image file saved to /images/development/contribute/documentation/components-of-kubernetes.svg:

{{< figure src="/images/development/contribute/documentation/components-of-kubernetes.svg" alt="United Manufacturing Hub pod running inside a cluster" class="diagram-large" caption="Figure 4. United Manufacturing Hub Architecture Components >}}

You should pass the src, alt, class and caption values into the {{< figure >}} shortcode. You can adjust the size of the diagram using diagram-large, diagram-medium and diagram-small classes.

Diagrams created using the `Inline` method don't use the `{{< figure >}}` shortcode. The Mermaid code defines how the diagram will render on your page.

See Methods for creating diagrams for more information on the different methods for creating diagrams.

Diagram Caption

Next, add a diagram caption.

If you define your diagram in an .svg image file, then you should use the {{< figure >}} shortcode’s caption parameter.

{{< figure src="/images/development/contribute/documentation/components-of-kubernetes.svg" alt="United Manufacturing Hub pod running inside a cluster" class="diagram-large" caption="Figure 4. United Manufacturing Hub Architecture Components" >}}

If you define your diagram using inline Mermaid code, then you should use Markdown text.

Figure 4. United Manufacturing Hub Architecture Components

The following lists several items to consider when adding diagram captions:

• Use the {{< figure >}} shortcode to add a diagram caption for Mermaid+SVG and External Tool diagrams.
• Use simple Markdown text to add a diagram caption for the Inline method.
• Prepend your diagram caption with Figure NUMBER.. You must use Figure and the number must be unique for each diagram in your documentation page. Add a period after the number.
• Add your diagram caption text after the Figure NUMBER. on the same line. You must puncuate the caption with a period. Keep the caption text short.
• Position your diagram caption BELOW your diagram.

Diagram Referral

Finally, you can add a diagram referral. This is used inside your text and should precede the diagram itself. It allows a user to connect your text with the associated diagram. The Figure NUMBER in your referral and caption must match.

You should avoid using spatial references such as ..the image below.. or ..the following figure ..

Here is an example of a diagram referral:

Figure 10 depicts the components of the United Manufacturing Hub architecture.
The control plane ...

Diagram referrals are optional and there are cases where they might not be suitable. If you are not sure, add a diagram referral to your text to see if it looks and sounds okay. When in doubt, use a diagram referral.

Complete picture

Figure 10 shows the United Manufacturing Hub Architecture diagram that includes the diagram, diagram caption and diagram referral. The {{< figure >}} shortcode renders the diagram, adds the caption and includes the optional link parameter so you can hyperlink the diagram. The diagram referral is contained in this paragraph.

Here is the {{< figure >}} shortcode for this diagram:

{{< figure src="/images/development/contribute/documentation/components-of-kubernetes.svg" alt="United Manufacturing Hub pod running inside a cluster" class="diagram-large" caption="Figure 10. United Manufacturing Hub Architecture." link="https://kubernetes.io/docs/concepts/overview/components/" >}}

Tips

• Always use the live editor to create/edit your diagram.

• Always use Hugo local and Netlify previews to check out how the diagram appears in the documentation.

• Include diagram source pointers such as a URL, source code location, or indicate the code is self-documenting.

• Always use diagram captions.

• Very helpful to include the diagram .svg or .png image and/or Mermaid source code in issues and PRs.

• With the Mermaid+SVG and External Tool methods, use .svg image files because they stay sharp when you zoom in on the diagram.

• Best practice for .svg files is to load it into an SVG editing tool and use the “Convert text to paths” function. This ensures that the diagram renders the same on all systems, regardless of font availability and font rendering support.

• No Mermaid support for additional icons or artwork.

• Hugo Mermaid shortcodes don’t work in the live editor.

• Any time you modify a diagram in the live editor, you must save it to generate a new URL for the diagram.

• Click on the diagrams in this section to view the code and diagram rendering in the live editor.

• Look over the source code of this page, diagram-guide.md, for more examples.

• Check out the Mermaid docs for explanations and examples.

Most important, Keep Diagrams Simple. This will save time for you and fellow contributors, and allow for easier reading by new and experienced users.

3.4 - Custom Hugo Shortcodes

One of the powerful features of Hugo is the ability to create custom shortcodes. Shortcodes are simple snippets of code that you can use to add complex content to your documentation.

Read more about shortcodes in the Hugo documentation.

Code example

You can use the codenew shortcode to display code examples in your documentation. This is especially useful for code snippets that you want to reuse in multiple places.

After you add a new file with a code snippet in the examples directory, you can reference it in your documentation using the codenew shortcode with the file parameter set to the path to the file, relative to the examples directory.

A Copy button is automatically added to the code snippet. When the user clicks the button, the code is copied to the clipboard.

Here’s an example:

{{< codenew file="helm/install-umh.sh" >}}

The rendered shortcode looks like this:

helm install united-manufacturing-hub united-manufacturing-hub -n united-manufacturing-hub

Heading

You can use the heading shortcode to use localized strings as headings in your documentation. The available headings are described in the content types page.

For example, to create a whatsnext heading, add the heading shortcode with the “whatsnext” string:

## {{% heading "whatsnext" %}}

Include

You can use the include shortcode to include a file in your documentation. This is especially useful for including markdown files that you want to reuse in multiple places.

After you add a new file in the includes directory, you can reference it in your documentation using the include shortcode with the first parameter set to the path to the file, relative to the includes directory.

Here’s an example:

{{< include "pod-logs.md" >}}

Mermaid

You can use the mermaid shortcode to display Mermaid diagrams in your documentation. You can find more information in the diagram guide.

Here’s an example:

{{< mermaid >}}
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
{{< /mermaid >}}

The rendered shortcode looks like this:

Notice

You can use the notice shortcode to display a notice in your documentation. There are four types of notices: note, warning, info, and tip.

Here’s an example:

{{< notice note >}}
This is a note.
{{< /notice >}}
{{< notice warning >}}
This is a warning.
{{< /notice >}}
{{< notice info >}}
This is an info.
{{< /notice >}}
{{< notice tip >}}
This is a tip.
{{< /notice >}}

The rendered shortcode looks like this:

This is a note.

This is a warning.

This is an info.

This is a tip.

Resource

You can use the resource shortcode to display a resource in your documentation. The resource shortcode takes these parameters:

• name: The name of the resource.
• type: The type of the resource.

This is useful for displaying resources which name might change over time, like a pod name.

Here’s an example:

{{< resource type="pod" name="database" >}}

The rendered shortcode looks like this: united-manufacturing-hub-timescaledb-0

The resources are defined in the i18n/en.toml file. You can add a new resource by adding a new entry like [resource_<type>_<name>]

Table captions

You can make tables more accessible to screen readers by adding a table caption. To add a caption to a table, enclose the table with a table shortcode and specify the caption with the caption parameter.

Table captions are visible to screen readers but invisible when viewed in standard HTML.

Here’s an example:

{{< table caption="Configuration parameters" >}}
| Parameter  | Description                  | Default |
| :--------- | :--------------------------- | :------ |
| `timeout`  | The timeout for requests     | `30s`   |
| `logLevel` | The log level for log output | `INFO`  |
{{< /table >}}

The rendered table looks like this:

If you inspect the HTML for the table, you should see this element immediately after the opening <table> element:

<caption style="display: none;">Configuration parameters</caption>

Tabs

In a markdown page (.md file) on this site, you can add a tab set to display multiple flavors of a given solution.

The tabs shortcode takes these parameters:

• name: The name as shown on the tab.
• codelang: If you provide inner content to the tab shortcode, you can tell Hugo what code language to use for highlighting.
• include: The file to include in the tab. If the tab lives in a Hugo leaf bundle, the file – which can be any MIME type supported by Hugo – is looked up in the bundle itself. If not, the content page that needs to be included is looked up relative to the current page. Note that with the include, you do not have any shortcode inner content and must use the self-closing syntax. For example, {{< tab name="Content File #1" include="example1" />}}. The language needs to be specified under codelang or the language is taken based on the file name. Non-content files are code-highlighted by default.
• If your inner content is markdown, you must use the %-delimiter to surround the tab. For example, {{% tab name="Tab 1" %}}This is **markdown**{{% /tab %}}
• You can combine the variations mentioned above inside a tab set.

Below is a demo of the tabs shortcode.

The tab **name** in a `tabs` definition must be unique within a content page.

Tabs demo: Code highlighting

{{< tabs name="tab_with_code" >}}
{{< tab name="Tab 1" codelang="bash" >}}
echo "This is tab 1."
{{< /tab >}}
{{< tab name="Tab 2" codelang="go" >}}
println "This is tab 2."
{{< /tab >}}
{{< /tabs >}}

Renders to:

• Tab 1
• Tab 2

echo "This is tab 1."

println "This is tab 2."

Tabs demo: Inline Markdown and HTML

{{< tabs name="tab_with_md" >}}
{{% tab name="Markdown" %}}
This is **some markdown.**
{{< note >}}
It can even contain shortcodes.
{{< /note >}}
{{% /tab %}}
{{< tab name="HTML" >}}
<div>
  <h3>Plain HTML</h3>
  <p>This is some <i>plain</i> HTML.</p>
</div>
{{< /tab >}}
{{< /tabs >}}

Renders to:

• Markdown
• HTML

This is some markdown.

It can even contain shortcodes.

Plain HTML

This is some plain HTML.

Tabs demo: File include

{{< tabs name="tab_with_file_include" >}}
{{< tab name="Content File #1" include="example1" />}}
{{< tab name="Content File #2" include="example2" />}}
{{< tab name="JSON File" include="podtemplate" />}}
{{< /tabs >}}

Renders to:

• Content File #1
• Content File #2
• JSON File

This is an example content file inside the includes leaf bundle.

Included content files can also contain shortcodes.

This is another example content file inside the includes leaf bundle.

  {
    "apiVersion": "v1",
    "kind": "PodTemplate",
    "metadata": {
      "name": "nginx"
    },
    "template": {
      "metadata": {
        "labels": {
          "name": "nginx"
        },
        "generateName": "nginx-"
      },
      "spec": {
         "containers": [{
           "name": "nginx",
           "image": "dockerfile/nginx",
           "ports": [{"containerPort": 80}]
         }]
      }
    }
  }

Version strings

To generate a version string for inclusion in the documentation, you can choose from several version shortcodes. Each version shortcode displays a version string derived from the value of a version parameter found in the site configuration file, config.toml. The two most commonly used version parameters are latest and version.

{{< param "version" >}}

The {{< param "version" >}} shortcode generates the value of the current version of the Kubernetes documentation from the version site parameter. The param shortcode accepts the name of one site parameter, in this case: version.

In previously released documentation, `latest` and `version` parameter values are not equivalent. After a new version is released, `latest` is incremented and the value of `version` for the documentation set remains unchanged. For example, a previously released version of the documentation displays `version` as `v1.19` and `latest` as `v1.20`.

Renders to:

{{< latest-umh-version >}}

The {{< latest-umh-version >}} shortcode returns the value of the latestUMH site parameter. The latestUMH site parameter must be updated when a new version of the UMH Helm chart is released.

Renders to:

{{< latest-umh-semver >}}

The {{< latest-umh-semver >}} shortcode generates the value of latestUMH without the “v” prefix.

Renders to:

{{< version-check >}}

The {{< version-check >}} shortcode checks if the min-kubernetes-server-version page parameter is present and then uses this value to compare to version.

Renders to:

What’s next

• Read the Hugo documentation.
• Learn how to write a new topic.
• Read the Content guide.

4 - Localizing UMH documentation

This page shows you how to localize the docs for a different language.

Contribute to an existing localization

You can help add or improve the content of an existing localization.

For extra details on how to contribute to a specific localization, look for a localized version of this page.

Find your two-letter language code

First, consult the ISO 639-1standard to find your localization’s two-letter language code. For example, the two-letter code for German is de.

Some languages use a lowercase version of the country code as defined by the ISO-3166 along with their language codes. For example, the Brazilian Portuguese language code is pt-br.

Fork and clone the repo

First, create your ownfork of the united-manufacturing-hub/umh.docs.umh.app repository.

Then, clone your fork and cd into it:

git clone https://github.com/<username>/umh.docs.umh.app
cd umh.docs.umh.app

The website content directory includes subdirectories for each language. The localization you want to help out with is inside content/<two-letter-code>.

Suggest changes

Create or update your chosen localized page based on the English original. See translating content for more details.

If you notice a technical inaccuracy or other problem with the upstream (English) documentation, you should fix the upstream documentation first and then repeat the equivalent fix by updating the localization you’re working on.

Limit changes in a pull requests to a single localization. Reviewing pull requests that change content in multiple localizations is problematic.

Follow Suggesting Content Improvements to propose changes to that localization. The process is similar to proposing changes to the upstream (English) content.

Start a new localization

If you want the United Manufacturing Hub documentation localized into a new language, here’s what you need to do.

All localization teams must be self-sufficient. The United Manufacturing Hub website is happy to host your work, but it’s up to you to translate it and keep existing localized content current.

You’ll need to know the two-letter language code for your language. Consult the ISO 639-1 standard to find your localization’s two-letter language code. For example, the two-letter code for Korean is ko.

If the language you are starting a localization for is spoken in various places with significant differences between the variants, it might make sense to combine the lowercased ISO-3166 country code with the language two-letter code. For example, Brazilian Portuguese is localized as pt-br.

When you start a new localization, you must localize all the minimum required content before the United Manufacturing Hub project can publish your changes to the live website.

Modify the site configuration

The United Manufacturing Hub website uses Hugo as its web framework. The website’s Hugo configuration resides in the config.toml file. You’ll need to modify config.toml to support a new localization.

Add a configuration block for the new language to config.toml under the existing [languages] block. The German block, for example, looks like:

[languages.de]
title = "United Manufacturing Hub"
description = "Dokumentation des United Manufacturing Hub"
languageName = "Deutsch (German)"
languageNameLatinScript = "Deutsch"
contentDir = "content/de"
weight = 8

The language selection bar lists the value for languageName. Assign “language name in native script and language (English language name in Latin script)” to languageName. For example, languageName = "한국어 (Korean)" or languageName = "Deutsch (German)".

languageNameLatinScript can be used to access the language name in Latin script and use it in the theme. Assign “language name in latin script” to languageNameLatinScript. For example, languageNameLatinScript ="Korean" or languageNameLatinScript = "Deutsch".

When assigning a weight parameter for your block, find the language block with the highest weight and add 1 to that value.

For more information about Hugo’s multilingual support, see “Multilingual Mode”.

Add a new localization directory

Add a language-specific subdirectory to the content folder in the repository. For example, the two-letter code for German is de:

mkdir content/de

You also need to create a directory inside i18n/ for localized strings; look at existing localizations for an example.

For example, for German the strings live in i18n/de.toml.

Open a pull request

Next, open a pull request (PR) to add a localization to the united-manufacturing-hub/umh.docs.umh.app repository. The PR must include all the minimum required content before it can be approved.

Add a localized README file

To guide other localization contributors, add a new README-**.md to the top level of united-manufacturing-hub/umh.docs.umh.app, where ** is the two-letter language code. For example, a German README file would be README-de.md.

Guide localization contributors in the localized README-**.md file. Include the same information contained in README.md as well as:

• A point of contact for the localization project
• Any information specific to the localization

After you create the localized README, add a link to the file from the main English README.md, and include contact information in English. You can provide a GitHub ID, email address, Discord channel, or another method of contact.

Launching your new localization

When a localization meets the requirements for workflow and minimum output, the UMH team does the following:

• Enables language selection on the website.
• Publicizes the localization’s availability through the United Manufacturing Hub blog.

Translating content

Localizing all the United Manufacturing Hub documentation is an enormous task. It’s okay to start small and expand over time.

Minimum required content

At a minimum, all localizations must include:

Translated documents must reside in their own content/**/ subdirectory, but otherwise, follow the same URL path as the English source. For example, to prepare the Getting started tutorial for translation into German, create a subfolder under the content/de/ folder and copy the English source:

mkdir -p content/de/docs/getstarted
cp content/en/docs/getstarted/installation.md content/de/docs/getstarted/installation.md

Translation tools can speed up the translation process. For example, some editors offer plugins to quickly translate text.

Machine-generated translation is insufficient on its own. Localization requires extensive human review to meet minimum standards of quality.

To ensure accuracy in grammar and meaning, members of your localization team should carefully review all machine-generated translations before publishing.

Source files

Localizations must be based on the English files from a specific release targeted by the localization team. Each localization team can decide which release to target, referred to as the target version below.

To find source files for your target version:

1. Navigate to the United Manufacturing Hub website repository at united-manufacturing-hub/umh.docs.umh.app.

2. Select a branch for your target version from the following table:

The main branch holds content for the current release .

Site strings in i18n

Localizations must include the contents of i18n/en.toml in a new language-specific file. Using German as an example: i18n/de.toml.

Add a new localization file to i18n/. For example, with German (de):

cp i18n/en.toml i18n/de.toml

Revise the comments at the top of the file to suit your localization, then translate the value of each string. For example, this is the German-language placeholder text for the search form:

[ui_search_placeholder]
other = "Suchen"

Localizing site strings lets you customize site-wide text and features: for example, the legal copyright text in the footer on each page.

5 - Versioning Documentation

With the Beta release of the Management Console, we are introducing a new versioning system for the documentation website. This system will ensure that the documentation is versioned in sync with the Management Console’s minor versions. Each new minor release of the Management Console will correspond to a new version of the documentation.

Branches

Below is an outline of the branching strategy we will employ for versioning the documentation website:

main branch

The main branch will serve as the living documentation for the latest released version of the Management Console. Following a new release, only patches and hotfixes will be committed to this branch.

Version branches

Upon the release of a new minor version of the Management Console, a snapshot of the main branch will be taken. This serves as an archive for the documentation corresponding to the previous version. For instance, with the release of Management Console version 1.1, we will create a branch from main named v1.0. The v1.0 branch will host the documentation for the Management Console version 1.0 and will no longer receive updates for subsequent versions.

Development branches

Simultaneously with the snapshot creation, we’ll establish a development branch for the upcoming version. For example, concurrent with the launch of Management Console version 1.1, we will initiate a dev-v1.2 branch. This branch will accumulate all the documentation updates for the forthcoming version of the Management Console. Upon the release of the next version, we will merge the dev-v1.2 branch into main, updating the documentation website to reflect the newest version.

Hugo configuration

To maintain the versioning of our documentation website, specific adjustments need to be made to the Hugo configuration file (hugo.toml). Follow the steps below to ensure the versioning is correctly reflected.

• Version branches

  • Update the latest parameter to match the branch version. For instance, for the v1.0 branch, set latest to 1.0.

  • The [[params.versions]] array should include entries for the current version and the upcoming version. For the v1.0 branch, the configuration would be:

    [[params.versions]]
    version = "1.1" # Upcoming version
    url = "https://umh.docs.umh.app"
    branch = "main"
    [[params.versions]]
    version = "1.0" # Current version
    url = "https://v1-0.umh-docs-umh-app.pages.dev/docs/"
    branch = "v1.0"
    

• Development branches

  • Set the latest parameter to the version that the branch is preparing. If the branch is dev-v1.2, then latest should be 1.2.

  • The [[params.versions]] array should list the version being developed using the Cloudflare Pages URL. The entry for dev-v1.2 would be:

    [[params.versions]]
    version = "1.2" # Version in development
    url = "https://dev-v1-2--umh-docs-umh-app.pages.dev"
    branch = "dev-v1.2"
    [[params.versions]]
    version = "1.1" # latest version
    url = "https://umh.docs.umh.app"
    branch = "main"
    

  • Prior to merging a development branch into main, update the url for the version being released to point to the main site and adjust the entry for the previous version to its Cloudflare Pages URL. For instance, just before merging dev-v1.2:

    [[params.versions]]
    version = "1.2" # New stable version
    url = "https://umh.docs.umh.app"
    branch = "main"
    [[params.versions]]
    version = "1.1" # Previous version
    url = "https://v1-1--umh-docs-umh-app.pages.dev"
    branch = "v1.1"
    

Always ensure that the [[params.versions]] array reflects the correct order of the versions, with the newest version appearing first.