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.

Documentation Framework

Meshery documentation is made of these components:

  • Framework - Jekyll
  • Theme - https://github.com/vsoch/docsy-jekyll
  • Repo - https://github.com/layer5io/meshery/tree/master/docs
  • DNS - https://meshery.layer5.io/docs
  • 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

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.

Alternatively, if you are running Windows 10, you may install the Windows Subsystem for Linux:

  • WSL1 for Windows build version 1607 or higher.

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
    $ bundle install
    

Serve the site

  • Serve the code locally
    $ make site
    

    Note: From the Makefile, this command is actually running $ bundle exec jekyll serve --drafts --livereload. There are two Jekyll configuration, jekyll serve for developing locally and jekyll build when you need to generate the site artifacts for production.

Create a Pull Request

  • After making changes, don’t forget to commit with the sign-off flag (-s)!
    $ 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><code>
     code snippet
   </code></pre>

<pre> tags are optional unless the code snippet is in a paragraph format

Or

code snippet          or         ```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. Run site locally to preview changes. make site
  6. Commit, sign-off, and push changes to your remote branch. git push origin <my-changes>
  7. Open a pull request (in your web browser) against the repo: https://github.com/layer5io/meshery.

Suggested Reading