Contributing to Meshery Docs

Important

Before contributing, please review the Documentation Contribution Flow.

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.

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 built using the following components:

Framework - Jekyll
Theme - https://github.com/vsoch/docsy-jekyll
Repo - https://github.com/meshery/meshery/tree/master/docs
Site - https://docs.meshery.io
AWS API GW - an instance is configured to redirect from docs.meshery.io to cloud.layer5.io, because of the repo location of where the docs currently reside.

Set up your development environment

Jekyll

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://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3
curl -sSL https://get.rvm.io | 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://pool.sks-keyservers.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB %}

Restart your WSL VM before moving forward to install Ruby.

To install Ruby, run:


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

Don't Commit Gemfile

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, navigate to the following folder 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

Note

The latest versions of Debian-based OS’es do not support libgdbm3, so if you encounter an issue with it’s installation, try replacing libgdbm3 with libgdbm5 or libgdbm6.

Installing rbenv

Cloning the rbenv repository


git clone https://github.com/rbenv/rbenv.git ~/.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
```

Note

After installing rbenv, you need to install the ruby-build plugin to use the rbenv install command. This step is necessary for both package manager and manual installations of rbenv.

Install ruby-build as an rbenv plugin


git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build

Install Ruby

rbenv install version
```
rbenv install 3.2.6
```
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

Use docs here Jekyll installation

Note

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

Get the code

Fork and then clone the Meshery repository


git clone https://github.com/YOUR-USERNAME/meshery

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 runs $ bundle exec jekyll serve --drafts --livereload --config _config_dev.yml. If this command results in an error, try running the server without Livereload using the command: $ bundle exec jekyll serve --drafts --config _config_dev.yml. Note that you will have to manually restart the server to reflect any changes made without Livereload. There are two Jekyll configurations, jekyll serve for local development and jekyll build to generate site artefacts for production deployment.

Using Docker

If you’ve Docker and make installed in your system, then you can serve the site locally. This doesn’t require the need to install Jekyll and Ruby in your system.

This may not work in Windows.

Run the following command from the docs folder, else it will fail.

make docker

Troubleshooting Note

While performing any of the above steps, if you receive an error about mismatching ruby versions similar to the example below, follow one of the steps mentioned below.

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

The reason for this error is because Jekyll always considers the exact version of Ruby unlike JavaScript.

Install the required Ruby version by using rvm or by any means given above.
If you’re unable to install the required Ruby version, then manually configure the Gemfile (This is not recommended and should be done only if the above steps fail). Modify the ruby version inside the Gemfile similar to the example below:
```
source "https://rubygems.org"
ruby '3.1.1' //Change to the version you have installed
```

The Gemfile.lock will be updated automatically once the make docs command is run. (For Windows, run bundle exec jekyll serve if WSL2 isn’t present)

Don't Commit Gemfile

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

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

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 launch, comes with Docker and other tools pre-installed, making it one of the fastest ways to spin up a development 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.

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

About Github Codespaces

Github Codespaces will automatically clone and open the repository for you in a browser-based version of Visual Studio Code. It comes with pre-installed tools which are quiet helpful to spin up the development environment for Meshery.

After opening the project on Github Codespaces, 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 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 docs and it will start the development server on port 4000.

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

Note

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!

See the Meshery Documentation Google Doc for additional reference.

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 as below:


code_snippet_here

If the code snippet has special characters then it must be captured first in a variable, and then pass it to the component:


code_snippet_here

Don’t use code component 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

Note

For contributing mesheryctl reference section, refer Contributing CLI

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

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

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

    toc:
  - title: Group 1
    subfolderitems:
      - 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:

    toc:
  - title: Group 1
    subfolderitems:
      - page: Thing 1
        url: /thing1.html
        subfolderitems:
          - 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.

Alerts

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:


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

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

alert.html

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

Create a file inside the modelscustominfo collection.
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

`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

Comment

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

Include

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 \" }}%}

Assign

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


{{ \"{% assign variable1 = true \" }}%}

Two helpful resources:

Liquid Docs - https://shopify.github.io/liquid/
Jekyll Docs - https://jekyllrb.com/docs/

Contributing to Meshery Docs

Important

Meshery Documentation Design Specification

Documentation Framework

Set up your development environment

Jekyll

For Windows

Note

Don't Commit Gemfile

For Linux

Note

Installing rbenv

Note

Note

Install Ruby

For MacOS

Note

Get the code

Note

Serve the site

Using Docker

Troubleshooting Note

Don't Commit Gemfile

Using Gitpod

About Gitpod

Using Github Codespaces

About Github Codespaces

Make Necessary Changes

Note

Create a Pull Request

Using the features of Meshery Docs

Clipboard Feature

Documentation Contribution Flow Summary

Note

Navigation Table of Contents in Sidebar (toc)

Alerts

What is an alert?

alert.html

Image Handling

Default Image Size in Markdown Format

Custom Image Size (for Control)

Quotes

Development

Adding Integration Specific Information to Individual Integration Pages

Suggested Reading

Editable Intra-page Table of Contents Toolbar

if conditional

for loop

Comment

Include

Assign

`if` conditional

`for` loop