Contributing to Meshery Docs

Use the following steps to set up your development environment depending on your Operating System of choice, fork the repository, install dependencies and run the site locally. You can then make changes, test locally, sign-off and commit, and push the changes made for review.

Documentation Framework

Meshery documentation is built using the following components:

Set up your development environment

Prerequisites

The following tools are required to build and run the Meshery documentation site locally:

  • Node.js (LTS recommended)
  • Go (required for Hugo modules)
  • Dart Sass (required to transpile the site’s stylesheets)

Get the code

  • Fork and then clone the Meshery repository

    git clone https://github.com/YOUR-USERNAME/meshery
  • Change to the docs directory

    cd meshery/docs
  • Install dependencies

    make setup

    This runs npm install, which installs Hugo Extended and all other required dependencies.

Serve the site

  • Serve the site locally.

    make site

    This runs hugo -e dev -DFE --minify server, which serves the site with draft and future content enabled. The site will be available at http://localhost:1313.

  • To build the site without serving:

    make build

Using Docker

If you have Docker and make installed on your system, then you can serve the site locally. This doesn’t require the need to install Hugo, Node.js, or Go on your system.

Run the following command from the docs folder.

make docker

This runs docker compose watch, which builds and serves the site inside a container.

The initial startup may take several minutes while Hugo downloads modules and builds the site. Once ready, the site will be available at http://localhost:1313/.

Using Gitpod

  • Ensure you have an account on Gitpod and add the Gitpod extension to your browser.
  • Open your forked Meshery repository on GitHub.
  • Click on the “Gitpod” button in the top right corner of the repository page (it is only visible with the Gitpod browser extension installed).
  • After opening the project on Gitpod, change to the docs directory.

    cd docs
  • Install dependencies and serve the site.

    make setup make site

You should be able to access the site on port 1313. If you want to access it in your localhost read the docs for port-forwarding using ssh.

Using GitHub Codespaces

  • Ensure you have an account on GitHub
  • Open your forked Meshery repository on GitHub.
  • Click on the “Code” button of your forked repository it will give you the option to open the project in GitHub Codespaces.
  • After opening the project on GitHub Codespaces, change to the docs directory.

    cd docs
  • Install dependencies and serve the site.

    make setup make site

You should be able to access the site on port 1313. If you want to access it in your localhost just click the code button on your forked repository and select open with Visual Studio Code under your GitHub Codespace this will launch a GitHub Codespace instance in your local machine and connects with the remote GitHub Codespace environment after that run cd docs then make setup && make site and it will start the development server on port 1313.

Make Necessary Changes

  • Make changes as required based on the issue you are solving.
  • Ensure to verify that your changes reflect correctly by serving the site locally using make site.
  • Before writing or restructuring a page, decide whether it is a tutorial, a how-to guide, a concept, or reference. See Choosing a Content Type.

Create a Pull Request

  • After making changes, don’t forget to commit with the sign-off flag (-s)!

    git commit -s -m "my commit message w/signoff"
  • Once all changes have been committed, push the changes.

    git push origin [branch-name]
  • Then on GitHub, navigate to the Meshery repository and create a pull request from your recently pushed changes!


Using the features of Meshery Docs

Linking to Pages and Assets

Internal content pages use Hugo’s ref shortcode:

[About]({{< ref "about.md" >}})

Page-bundle assets use standard relative paths. For assets adjacent to index.md or _index.md, or inside that page bundle:

![Architecture](./images/your-image.webp)
<img src="./images/your-image.webp" />

A page that carries its own images belongs in a leaf bundle - <page>/index.md beside <page>/images/, the way concepts/architecture/operator/ is laid out. A plain <page>.md publishes at <page>/, one level below the directory it was written in, so a relative path from it to a sibling images/ directory 404s. Either move the page into a leaf bundle or reference the image from static/.

Global shared assets under static/ use the static shortcode:

{{< static "images/logo.png" >}}

Do not use raw root-relative page links like [About](/about/). External links (starting with http://, https://, mailto:, tel:, #) should be kept unchanged.

Clipboard Feature

Most popular clipboard plugins like Clipboard JS require the manual creation of a new ID for each code snippet. A different approach is used here. For code snippets, we either use html tags or markdown in the following manner:

<pre class="codeblock-pre"><div class="codeblock">
<code class="clipboardjs">code_snippet_here</code>
</div></pre>

You can also use the code shortcode created for this feature to make it easy to use. It can be used by passing the code snippet to it.

If the code snippet does not contain any special characters then, it can be used directly as below:

{{< code code="code_snippet_here" >}}

If the code snippet has special characters then use backtick delimiters:

{{< code code=`code_snippet_here` >}}

Don’t use code shortcode when the snippet is in between an ordered list, this breaks the order and next item in the list will start numbering from 1. Instead, use <pre class="codeblock-pre">...</pre> method described above.

A full block:

```code snippet```

Inline formatting:

	
		`code snippet`: `code snippet`
	

Language specific:

	
		(language name)
code snippet

	

Whenever the code tags are detected, the clipboard javascript file is automatically loaded. Each code element is given a custom id and a clipboard-copy icon to copy the content.

Documentation Contribution Flow Summary

The following is a concise summary of the steps to contribute to Meshery documentation.

  1. Create a fork, if you have not already, by following the steps described here
  2. In the local copy of your fork, navigate to the docs folder. cd docs
  3. Create and checkout a new branch to make changes within git checkout -b <my-changes>
  4. Edit/add documentation. vi <specific page>.md
  5. Add redirect link on the old page (only when a new page is created that replaces the old page). In Hugo, use the aliases frontmatter field.
  6. Run site locally to preview changes. make site
  7. Commit, sign-off, and push changes to your remote branch. git push origin <my-changes>
  8. Open a pull request (in your web browser) against the repo: https://github.com/meshery/meshery.

The sidebar is generated from the content tree under content/en/. There is no navigation data file to edit: a page appears in the sidebar because of where its file lives.

  • A directory with an _index.md is a section. It shows as a parent entry in the sidebar.
  • Pages and subdirectories inside that directory show as its children. Nesting directories nests sidebar entries.

For example, these files:

content/en/group1/_index.md
content/en/group1/thing1/_index.md
content/en/group1/thing1/subthing1_1.md
content/en/group1/thing1/subthing1_2.md
content/en/group1/thing2.md
content/en/group1/thing3.md

produce this sidebar:

    Group 1
      Thing 1
       Subthing 1.1
       Subthing 1.2
      Thing 2
      Thing 3

Use front matter to control how a page or section is listed:

FieldEffect
titleThe sidebar label, unless linkTitle is set.
linkTitleA shorter label for the sidebar. The page heading still uses title.
weightOrder within the parent section, lowest first. Entries with the same weight are sorted by title. An entry with no weight counts as 0, so it sorts after negative weights and before positive ones.
toc_hide: trueKeeps the page or section out of the sidebar. The page is still published.
---
title: Contributing to Meshery Docs
linkTitle: Docs
weight: 20
---

To add a page to the sidebar, create the Markdown file in the section it belongs to and set weight if its position matters. The sidebar itself is rendered by layouts/partials/sidebar-tree.html.

Alerts

	
		{{% alert color="info" title="Here is another!" %}}
{{% /alert %}}
	

Just for fun, here are all the types:

alert shortcode

Meshery Docs uses the alert shortcode (provided by the Docsy theme) to provide consistent formatting for notes, warnings, and various informative callouts intended for the readers.

To use the alert shortcode feature in our documentation include the following code:

	
		{{% alert color="info" title="Here is another!" %}}
{{% /alert %}}
	

Other supported alert colors include warning, danger,success,primary, secondary, light, dark .

Image Handling

Control image display in documentation pages using the following methods.

Default Image Size in Markdown Format

Using the Markdown image syntax:

	
		[![Image Title](../../../assets/img/your-image.png)](../../../assets/img/your-image.png)
	

This renders as:

	
		<a href=\"/assets/img/your-image.png\">
    <img src=\"/assets/img/your-image.png\" alt=\"Image Title\">
</a>
	

Effect:

  • Image is displayed at its original resolution, limited by global CSS (max-width: 90vw; max-height: 90vh; height: auto; width: auto;)
  • On larger screens (min-width: 1200px), image width can be up to 1200px
  • Clickable, opening in Lightbox if the format is supported

Custom Image Size (for Control)

If you need to specify dimensions, use:

	
		<a href=\"/assets/img/your-image.png\">
    <img src=\"/assets/img/your-image.png\" style=\"width:500px; height:auto;\" alt=\"Image Title\">
</a>
	

Effect:

  • Image width is fixed at 500px, maintaining aspect ratio
  • If 500px exceeds 90vw, it will be constrained to 90vw
  • Clickable, opening in Lightbox for full-size viewing

Quotes

You can include block quotes to emphasize text.

Here is an example. Isn’t this much more prominent to the user?

Development

Adding Integration Specific Information to Individual Integration Pages

Integration pages (example) are automatically generated, however, integration specific documentation is often needed.

modelscustominfo collection holds custom markdown files. Follow these steps:

  1. Create a file inside the modelscustominfo collection.
  2. Ensure the file includes frontmatter with the title key, set to the title of the integration.

The content that follows the frontmatter in this file will be automatically parsed and rendered on the integration page

Example:

file: modelscustominfo/aad.md

---
title: Azure Active Directory (AAD)
---
<h2>Azure Active Directory (AAD)</h2>

In this example, the heading “Azure Active Directory” will be displayed on the integration page: Azure Active Directory Integration Page

Suggested Reading

Disable suggested reading by setting the suggested-reading frontmatter variable to false.

Editable Intra-page Table of Contents Toolbar

Control the display of this intra-page navigator with either page level or layout level frontmatter variables:

display-toolbar

Set to true (make “editable” toolbar visible) or false (hide “editable” toolbar)

if conditional

In Hugo templates, conditionals are written using Go template syntax:

	
		{{ if eq .Params.title "Awesome Shoes" }}
  These shoes are awesome!
{{ end }}
	

If the condition is true, the output would be:

    These shoes are awesome!

range loop

The range action iterates over a collection. It is written in the following manner:

	
		{{ range .Pages }}
  {{ .Title }}
{{ end }}
	

The output produced by the above code snippet would list the titles of all pages in the current section.

Comment

In Hugo templates, comments are written using Go template comment syntax:

	
		{{/* This is a comment */}}
	

Any content inside {{/* */}} will not be rendered in the output.

Partial

Partials are used to include reusable template fragments. They are written in the following manner:

	
		{{ partial "header.html" . }}
	

Shortcode

Shortcodes are reusable content snippets that can be used in Markdown files. They are written in the following manner:

	
		{{</* shortcode-name param="value" */>}}
	

Variable

In Hugo templates, variables are defined using the := operator:

	
		{{ $variable1 := true }}
	

Two helpful resources:

  1. Hugo Docs - https://gohugo.io/documentation/
  2. Go Template Docs - https://pkg.go.dev/text/template