docs/static/v0.8/project/contributing/contributing-docs/index.html
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.
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.
Meshery documentation is built using the following components:
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
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):
To install Ruby, run:
Update the Gemfile located in meshery/docs directory
Also add this to the next line in the 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
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.
Change bashrc with your shell specific rc file, for eg: if you are using zsh then the filename is zshrc.
Setting the path
rbenv init
Reload your bashrc
Check installation
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.
rbenv install version
To list all the versions that can be installed
Set which Ruby version you want to use
Check Ruby installation
In case of any installation issues, use the discussion forum.
Fork and then clone the Meshery repository
Change to the docs directory
Install any Ruby dependencies
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 code locally.
If that gives an error run:
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`
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.
rvm or by any means given above.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: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)
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.
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.
Serve the code locally.
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.
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.
Serve the code locally.
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 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.
After making changes, don’t forget to commit with the sign-off flag (-s)!
Once all changes have been committed, push the changes.
Then on Github, navigate to the Meshery repository and create a pull request from your recently pushed changes!
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 CLI](/v0.8/project/contributing/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](CONTRIBUTING-gitflow.md)
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](#commit-signing), and push changes to your remote branch. `git push origin <my-changes>`
8. 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:
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:
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 warning
#### danger
This alerts danger!
#### success
This alerts success
#### info
This is useful information.
#### primary
This is a primary alert
#### secondary
This is a secondary alert
#### light
This is a light alert
#### dark
This is a dark alert
#### alert.html
Meshery Docs has a common include file [alert.html](https://github.com/meshery/meshery/blob/master/docs/_includes/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` .
### Image Handling
Control image display in documentation pages using the following methods.
#### Default Image Size in Markdown Format
Using the Markdown image syntax:
[](/assets/img/your-image.png)
This renders as:
`<a href="/assets/img/your-image.png">
</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">
</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](https://docs.meshery.io/extensibility/integrations/aws)) are automatically generated, however, integration specific documentation is often needed.
[modelscustominfo](https://github.com/meshery/meshery/tree/master/docs/_modelscustominfo) collection holds custom markdown files. Follow these steps:
1. Create a file inside the `modelscustominfo` collection.
2. 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`
In this example, the heading “ Azure Active Directory ” will be displayed on the integration page: Azure Active Directory Integration Page
Disable suggested reading by setting the suggested-reading frontmatter variable to false.
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 conditionalThis 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 loopThe 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 %}`
Two helpful resources: