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 SpecificationSee 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.
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
JekyllThe Meshery Docs site is built using Jekyll - a simple static site generator. You can learn more about Jekyll and setting up your development environment in the [Jekyll Docs](https://jekyllrb.com/docs/).
- First install Ruby, then install Jekyll and Bundler.
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 servefor developing locally and
jekyll buildwhen 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!
- See the Meshery Documentation Google Doc for additional reference.
Using the features of Meshery Docs
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
code snippet or ```code snippet```
Documentation Contribution Flow Summary
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.
- Create and checkout a new branch to make changes within
git checkout -b <my-changes>
- Edit/add documentation.
vi <specific page>.md
- Run site locally to preview changes.
- 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/layer5io/meshery.
- Contributing to Meshery UI
- Meshery Contributing Guidelines
- Contributing to Meshery Docs
- Contributing to Meshery CLI
- Contributing to Meshery Adapters
- Contributing to Meshery using git