Contribute to Handbook
Learn how to contribute to Vanilla OS Handbook.
Thank you for your interest in our project. This guide will help you with writing articles.
The Handbook uses Jekyll and GitHub pages for generating the website.
Handbook progress with a to-do list is present at our GitHub project.
Prerequisites for Writing a guide
A basic knowledge of Markdown is required for writing posts.
Writing a guide
If you want to write a guide for the handbook, follow these instructions:-
- Add the new article to the
- The filename must be in the format
- See markdownlint for best markdown practices.
- The guide must use the following structure at the beginning:
--- title: description: date: YYYY-MM-DD layout: article authors: - 1st author GitHub username - 2nd author GitHub username - ... published: true ---
- You must fill in your article’s metadata here.
--- title: Installing a package description: Learn how to install a package in Vanilla OS date: 2023-01-13 layout: article authors: - MonsterObserver published: true ---
- Add your GitHub username with the co-author’s username(s) in the author’s field to have working links when the post is published.
- Ensure images are in WebP format and placed in a dedicated directory under the
assets/uploadsdirectory with a descriptive name for future reference.
Tip: We suggest using cwebp for converting the images to WebP.
Headings should follow a proper hierarchy.
Links must be in bold, commands in bold and backticks.
Buttons in applications can be highlighted using double quotes (“”). For example, the Install button gets highlighted as the “Install” button.
Menus, command names and directories must be enclosed with backticks (`).
For displaying commands, we suggest code blocks with the correct shell or programming language.
- To update your Vanilla OS system now, run the following command:- "```bash sudo vso trigger-update --now ```" (Note: " isn't required, and is used for quoting the syntax here)
The code block will have the following output:-
sudo vso trigger-update --now
Some terms like “Note:” and “Tip:” should be highlighted with bold and italics. For example:-
Testing the guide locally using Jekyll, Bundler
Clone your forked repository using
Add the guide to the correct destination in the cloned directory.
jekyll build to build the page to
./_site once. Then you can either test the pages manually or use the
jekyll serve command.
jekyll serve to build your site any time a source file changes and serve it locally.
http://localhost:4000/ in your browser to preview and test the page.
Now, commit the changes using
git and create a PR in GitHub.
You can test your pages on your phone using
jekyll serve --host=<ip>.
0.0.0.0 instead of a specific IP binds port 4000 to any interface, which is prone to be blocked by your routers firewalls. That’s why we recommended using a particular IP address with the
--host flag. After executing the command in any browser on your phone, go to this address
For example, if the IP you used is
192.168.0.123, you will need to visit
192.168.0.123:4000 on your mobile.
Embedding GitHub Gists
GitHub gists are allowed for referencing custom mods and scripts in posts.
For example, embedding this
<script src="https://gist.github.com/kbdharun/feca3da0c8213ae2b5cd02f3ea8e380c.js"></script> will have the following output:-
Removing guides and images from the repository isn’t advised.
For outdated articles and posts, we suggest changing the publishing status to
false in the header, which removes it from the Glossary’s listing and RSS feed.
For outdated images, it is recommended to move them to the handbook-archive repository to prevent space.
For discussions regarding the handbook, go to the
#docs-writing channel in the official Discord server. For Discussions regarding translations go to the
#translations channel. Alternatively, you can collaborate with the docs team on our Matrix room.