- 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
_posts
directory. - The filename must be in the format
YYYY-MM-DD-title.md
. - 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.
For example:-
---
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/uploads
directory with a descriptive name for future reference.
Tip: We suggest using cwebp for converting the images to WebP.
Style Guide
- Headings should follow a proper hierarchy.
- Links must be in bold, commands in bold and backticks.
For example:-
[**example**](https://example.com/)
[**`apx`**](https://github.com/Vanilla-OS/apx)
Which will have the following outputs:- example, apx
-
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.
For example:-
- 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:-
**_Note_**:-
.
Testing the guide locally using Jekyll, Bundler
- You can install Jekyll from this page and Bundler can be installed from this page. Or you can follow these steps in Vanilla OS.
- Clone your forked repository using
git
orgh
. - Add the guide to the correct destination in the cloned directory.
- Run
bundler install
to install necessary packages (This step is required only once and doesn’t require re-running it in future. You must have a Gemfile in the repository for this to work). - Run
bundler exec jekyll build
to build the page to./_site
once. Then you can either test the pages manually or use thejekyll serve
command. - Run
bundler exec jekyll serve
to build your site any time a source file changes and serve it locally.- Navigate to
http://127.0.0.1:4000/
orhttp://localhost:4000/
in your browser to preview and test the page.
- Navigate to
- Now, commit the changes using
git
and create a PR in GitHub.
Tip:-
- You can test your pages on your phone using
bundler exec jekyll serve --host=<ip>
. - Using
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<ip>:4000
. - For example, if the IP you used is
192.168.0.123
, you will need to visit192.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:-
Archiving guides
- 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.
Discussions
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.