Contributing to Meshery Docs

Before contributing, please review the Documentation Contribution Flow. In the following steps you will set up your development environment, fork and clone the repository, run the site locally, and finally commit, sign-off, and push any changes made for review.

Meshery Documentation Design Specification

See the Meshery Documentation Design Specification which serves to provide an overview of the tooling and approach used to create Meshery’s documentation and it information architecture.

Documentation Framework

Meshery documentation is made of these components:

Set up your development environment


The Meshery Docs site is built using Jekyll - a simple static site generator. Jekyll can be installed on different platforms like Windows, Linux, and MacOS by the following steps

For Windows

Note: Windows users can run Jekyll by following the Windows Installation Guide and also installing Ruby Version Manager RVM. RVM is a command-line tool which allows you to work with multiple Ruby environments on your local machine. Alternatively, if you’re running Windows 10 version 1903 Build 18362 or higher, you can upgrade to Windows Subsystem for Linux WSL and run Jekyll in Linux instead.

  • Fire up your WSL VM and install the ruby version manager (RVM):
sudo apt update sudo apt install curl g++ gnupg gcc autoconf automake bison build-essential libc6-dev \ libffi-dev libgdbm-dev libncurses5-dev libsqlite3-dev libtool \ libyaml-dev make pkg-config sqlite3 zlib1g-dev libgmp-dev \ libreadline-dev libssl-dev sudo gpg --keyserver hkp:// --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 curl -sSL | sudo bash -s stable sudo usermod -a -G rvm `whoami`

If gpg --keyserver gives an error, you can use:

sudo gpg --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3


sudo gpg2 --keyserver hkp:// --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB

Restart your WSL VM before moving forward.

  • For installing Ruby, run:

      rvm install ruby
      rvm --default use ruby 2.7.5
      gem update
      gem install jekyll bundler
  • Update the Gemfile located in meshery/docs directory
      ruby '3.0.2'

    Note: In place of 3.0.2 add your installed version

  • Also add this to the next line in the Gemfile
      gem 'wdm','>=0.1.0' if Gem.win_platform?

    Note: This is just a workaround for your local machine so do not commit or push the modified Gemfile or Gemfile.lock during Pull Requests

  • Next, go to this folder on your device C:\Ruby24-x64\lib\ruby\gems\2.4.0\gems\eventmachine-1.2.5-x64-mingw32\lib

  • Add require 'em/pure_ruby' in the first line of the eventmachine.rb file

For Linux

  • Prerequisites
sudo apt-get update sudo apt-get install autoconf bison build-essential libssl-dev libyaml-dev libreadline6-dev zlib1g-dev libncurses5-dev libffi-dev libgdbm3 libgdbm-dev

Installing rbenv

  • Cloning the rbenv repository
git clone ~/.rbenv

Note: Change bashrc with your shell specific rc file, for eg: if you are using zsh then the filename is zshrc.

  • Setting the path
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
  • rbenv init
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
  • Reload your bashrc
source ~/.bashrc
  • Check installation
type rbenv

Install Ruby

  • rbenv install version
rbenv install 3.2.2
  • To list all the versions that can be installed
rbenv install --list
  • Set which Ruby version you want to use
rbenv global version
  • Check Ruby installation
ruby -v

For MacOS

Note: In case of any installation issues, use the discussion forum.

Get the code

git clone
  • Change to the docs directory
cd docs
  • Install any Ruby dependencies
gem install bundler bundle install

Note: If you are a Mac user you do not need to install the Ruby dependencies, after moving on to the docs directory, you can serve the site.

Serve the site

  • Serve the code locally
make docs
  • If that gives an error run:
bundle exec jekyll serve --drafts --config _config_dev.yml

From the Makefile, this command is actually running $ bundle exec jekyll serve --drafts --livereload --config _config_dev.yml. If this command causes errors try running the server without Livereload with this command: $ bundle exec jekyll serve --drafts --config _config_dev.yml. Just keep in mind you will have to manually restart the server to reflect any changes made without Livereload. There are two Jekyll configuration, jekyll serve for developing locally and jekyll build when you need to generate the site artefacts for production.

Using Docker

If you’ve Docker and make installed in your system, then you can serve the site locally

make docker

This doesn’t require the need for installing Jekyll and Ruby in your system

But, you need to make sure that GNU make is working in your system (might not work in Windows)


While performing the above step, if you’re facing errors with a message like below…

Your ruby version is x.x.x but your Gemfile specified 2.7.x

This is because Jekyll always considers the exact version of Ruby unlike JavaScript.

So, you need to follow either of the three steps to resolve this problem;

  • Install the required Ruby version by using rvm or by any means given above
  • Alternatively, if you have Docker installed, then type make docker-docs to view the changes
  • If you’re unable to install the required Ruby version, then manually configure the Gemfile as below (not recommended! Do only if above two steps fail):
source ""
ruby '2.7.5' //to any version you have installed

Automatically the Gemfile.lock will update once the make docs is given (for Windows, run bundle exec jekyll serve if WSL2 isn’t present)

WARNING: If you have followed the third step then please don’t commit the changes made on Gemfile and Gemfile.lock in your branch to preserve integrity, else the CI action will fail to generate the site preview during PR.

Using Gitpod

  • Make sure to 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 (only visible with the Gitpod browser extension installed).

About Gitpod

Gitpod will automatically clone and open the repository for you in a browser-based version of Visual Studio Code. It will also automatically build the project for you on opening and comes with Docker and other tools pre-installed making it one of the fastest ways to spin up an environment for Meshery.
  • After opening the project on Gitpod, change to the docs directory
cd docs
  • Serve the code locally
make docs

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

Make Necessary Changes

  • Make changes as required by the issue you are solving
  • Be sure check that your changes appear correctly locally by serving the site using make docs


  • If the issue requires making new doc page that replaces the old page, please don’t forget to add a redirect link on the old page. This redirect link field should have the link of the new page created.

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

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 component created for this feature to make it easy to use. It can be used by including code.html and then passing the code snippet to it.

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

{% include code.html code="code_snippet_here" %}.

If the code snippet has special characters then we need to capture it first in variable code_content like this,

{% capture code_content%}code_snippet_here{% endcapture %}

and then pass it to the component like this,

{% include code.html code=code_content %}.

That’s it.

NOTE: Don’t use code component when the snippet is in between an ordered list, it breaks the order and next item in the list will have numbering from 1. So better use <pre class="codeblock_pre">...</pre> method above instead when the snippet is in between an ordered list.

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

NOTE: For contributing mesheryctl reference section, refer Contributing CLI

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)
  6. Run site locally to preview changes. make docs
  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:

Sidebars use toc to create a table of contents. It is written in the following manner:

  - title: Group 1
      - page: Thing 1
        url: /thing1.html
      - page: Thing 2
        url: /thing2.html
      - page: Thing 3
        url: /thing3.html

The output of the code snippet would be:

    Group 1
      Thing 1
      Thing 2
      Thing 3

In this example, Group 1 is a parent section within the Table of Contents, and Thing 1, Thing 2, and Thing 3 are children of Group 1. This is a direct hierarchy with a single level of children under the parent.

Grandchildren are added in the sidebars in the following manner:

  - title: Group 1
      - page: Thing 1
        url: /thing1.html
          - page: Subthing 1.1
            url: /subthing1_1.html
          - page: Subthing 1.2
            url: /subthing1_2.html
      - page: Thing 2
        url: /thing2.html
      - page: Thing 3
        url: /thing3.html

The output of the code snippet would be:

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

Here, Subthing 1.1 and Subthing 1.2 are the grandchildren of Thing 1.

In docs/_includes/sidebar.html contains three levels of navigation hierarchy.

  • Parent: It serves as a top level category for related content.
  • Children: They are immediate subsections or topics that fall under the parent section.
  • Grandchildren: They are nested under Thing 1 and provide a more detailed breakdown of information within the child section. Grandchildren are used to organize content further, offering a more detailed structure for a specific topic.

These sections create a hierarchical and organized navigation experience for readers.


What is an alert?

An alert is a box that can stand out to indicate important information. You can choose from levels success, warning, danger, info, and primary. This example is an info box, and the code for another might look like this:
{% include alert.html type="info" title="Here is another!" %}

Just for fun, here are all the types:


This is a warning


This alerts danger!


This alerts success


This is useful information.


This is a primary alert


This is a secondary alert


This is a light alert


This is a dark alert


Meshery Docs has a common include file alert.html, to provide consistent formatting for notes, warnings, and various informative callouts intended for the readers.

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

  {% include alert.html type="info" title="Here is another!" %}

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


You can include block quotes to emphasize text.

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


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:


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

if conditional

This executes the block of code only if the given condition is true. It is executed in the following manner:

{% if product.title == 'Awesome Shoes' %} These shoes are awesome! {% endif %}

If the condition is true, the output would be:

    These shoes are awesome!

for loop

The for statement executes a block of code repeatedly. It is wriiten in the following manner:

{% for names in collection.names %} {{ name.title }} {% endfor %}

The output produced by the above code snippet:

    Sam Ham Ethan


Comments allow to leave a block of code unattended, any statements between opening and closing comment would not be executed.


The above tag is used to insert a already rendered file within the current template. It is written in the following manner:

{% include file.html %}


The assign tag is used to create a new variable. It is written in the following manner:

{% assign variable1 = true %}

Suggested Reading

Two helpful resources:

  1. Liquid Docs -
  2. Jekyll Docs -