Style Overview

• 1: Content Guide
• 2: Style Guide
• 3: Diagram Guide
• 4: Custom Hugo Shortcodes

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.

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

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.