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 meshery.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 stepsFor 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
OR
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 supportlibgdbm3
, 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
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
- 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 andjekyll 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.
info
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.
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:
{% include code.html code="code_snippet_here" %}
`
If the code snippet has special characters then it must be captured first in variable code_content
, and then pass it to the component.
{% capture code_content%}code_snippet_here{% endcapture %}
{% include code.html code=code_content %}
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 CLIThe 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.
Navigation Table of Contents in Sidebar (toc)
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:{% include alert.html type="info" title="Here is another!" %}
Just for fun, here are all the types:
warning
This is a warningdanger
This alerts danger!success
This alerts successinfo
This is useful information.primary
This is a primary alertsecondary
This is a secondary alertlight
This is a light alertdark
This is a dark alertalert.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.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
.
Quotes
You can include block quotes to emphasize text.
Here is an example. Isn’t this much more prominent to the user?
Development
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
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/
Suggested Reading
- Build & Release (CI) - Details of Meshery's build and release strategy.
- Contributing to Meshery Adapters - How to contribute to Meshery Adapters
- Contributing to Meshery CLI - How to contribute to Meshery Command Line Interface.
- Contributing to Meshery's End-to-End Tests using Cypress - How to contribute to End-to-End Tests using Cypress.
- Contributing to Meshery Docker Extension - How to contribute to Meshery Docker Extension
- How to write MeshKit compatible errors - How to declare errors in Meshery components.
- Contributing to Meshery using git - How to contribute to Meshery using git
- Meshery CLI Contributing Guidelines - Design principles and code conventions.
- Contributing to Model Components - How to contribute to Meshery Model Components
- Contributing to Model Relationships - How to contribute to Meshery Models Relationships, Policies...
- Contributing to Models - How to contribute to Meshery Models, Components, Relationships, Policies...
- Contributing to Meshery Server Events - Guide is to help backend contributors send server events using Golang.
- Contributing to Meshery UI - Notification Center - How to contribute to the Notification Center in Meshery's web-based UI.
- Contributing to Meshery UI - Sistent - How to contribute to the Meshery's web-based UI using sistent design system.
- Contributing to Meshery's End-to-End Tests - How to contribute to End-to-End Tests using Playwright.
- Contributing to Meshery UI - How to contribute to Meshery UI (web-based user interface).
- Contributing to Meshery Server - How to contribute to Meshery Server
- Setting up Meshery Development Environment on Windows - How to set up Meshery Development Environment on Windows