Demo card 1
Contribution Guidelines
About 2015 wordsAbout 7 min
AdvancedVuepressWeb-DevWiki
2025-06-09
This is a guideline for editing, styling, and formatting when editing Tuxie's Wiki. Please read and comply with these guidelines as it could jeopardise your opportunity in being a contributor.
Formatting
File naming convention
We'll be using kebab-case to name files within the working directory.
Examples
- kebab-case-is-the-best.txt
- tuxies-wiki.svg
- we-bare-bears.png
- become-a-contributor.md
Titles, file names, & permalinks
Titles of articles should use title case.
Examples
- Firefox Guide
- Linux Guide
- Become a Contributor
The name of the file should be derived from the name of the article (if it is one) and be informative. The permalink should derive from the distinguishable directory of the file.
Examples
Gnome Guide @ /docs/notes/linux-guides/gnome.md
--> /linux-guides/gnome/
Terminal Customisation (Bash) @ /docs/guides/terminal-customisation-bash.md
--> /guides/terminal-customisation-bash/
Article tagging
Articles are tagged in the yaml header of each .md file to dynamically categorise them.
---
tags:
- Advanced
- Firefox
- Browser
- Productivity
# ... code omitted ...
---Use the following as a rough guideline of how to tag your article. It is recommended you do not exceed 4 tags.
Recommended level: Beginner, Intermediate, Advanced.
Specific program: e.g. Gnome, Firefox, virt-manager, bash.
Category of program: e.g. Browser, OS, VM, Terminal. Category of guide: Fixes, Ricing, Productivity, Web-Dev, Wiki.
Language
English guides are written in non-Oxford Standard GB English (en-gb). Keep in mind the universal language standard for code is US English despite the guides being in Standard GB English.
Use professional, concise, and effective language that avoids unnecessary complexity. Our mission is to effectively transfer information and convey ideas, not write for high academia.
Use 'we' in universal articles. Use 'I' in blogs.
Code formatting
Formatting is not strictly monitored as long as the output is clean (i.e. the generated content is pretty).
The use of the Prettier extension in VS Code or an equivalent would be appreciated.
Use article permalinks when referring to internal pages and assets (placed in the .public folder). This makes project structuring more maintainable.
Code Structure
In some occasions, we encounter usage of nested formatting tools such as details and steps within one another. In similar cases, we should always follow the rule of adding an additional ":" to the outer tool. Below is an example illustrating this point.
The rule is simple: every container must have more colons than any container nested inside it. Count from the innermost container outward, adding one colon at each level.
Count from the inside out
Start with the innermost container at ::: (3 colons — the minimum). Each container wrapping it gets one more colon. Never skip a level.
| Nesting level | Colons | Example |
|---|---|---|
| Innermost | ::: | :::note, :::card |
| One level up | :::: | ::::details, ::::collapse |
| Two levels up | ::::: | :::::steps, :::::demo-wrapper |
| Three levels up | :::::: | ::::::details |
A common mistake is writing a container with the same or fewer colons than something inside it — this breaks rendering. If a container does not close correctly, check that its colon count is strictly greater than all containers nested within it.
See code..
<!-- ":::::" demo-wrapper-->
::::: demo-wrapper
<!-- "::::" for details-->
::::details
<!-- ":::" for steps-->
:::steps
- I use arch btw
- I'm Lunear btw
:::
::::
:::::Example output
- I use arch btw
- I'm Lunear btw
Icons
We'll follow the following hierarchy for icons:
Core website components
mdi >> ic >> others
We prefer to keep navigational and core components clean, without colours.
Cards
fluent-emoji >> fluent-emojis >> devicon >> logos >> others
Cards would preferably be catchy and fun.
Tabs
devicon >> logos >> mdi >> ic >> simple-icons >> others
Similar to core components, they should be clean and informative; some colour would be nice, though.
How to add an icon...
Format: ::emoji:name =size /color::
size refers to the px size
/color refers to the hex value
See code...
::mdi:linux =50 /#000000::
::mdi:fedora =32 /#3f7ac3::
::fluent-emoji:party-popper::Document components
Callout container
If the content you will be putting in the callout container is relatively short, simply make it the title of the callout.
See code...
:::important This is an announcement for everybody: I love Linux!
:::
:::tip Everybody loves some pro tips :\)
:::This is an annoucement for everybody: I love Linux!
Everybody loves some pro tips :)
Card & card grid
You can use card to serve as a decorative callout container. Use card-grid to indicate the author(s), maintainer(s), and contributor(s) of an article.
For what icons to use, refer to icons section.
See code...
::::card-grid
:::card title="Demo card 1" icon="fluent-emoji-flat:card-index"
:::
:::card title="Demo card 2" icon="fluent-emoji-flat:card-index"
::::Demo card 2
Code
Use code to indicate files, programs, and directories. Simply surround the text you want to "codify" with backticks (`).
See code...
`fzf` is a program that allows for fuzzy searching in the cli.fzf is a program that allows for fuzzy searching in the cli.
Code block & inline code
Always wrap programs, applications, and directories in inline code (`) for better legibility. Do not use both highlight and inline code together — if the term is technical (a program, command, path, or config value), use inline code only. Reserve highlighting for non-technical emphasis in prose.
See code...
Go to `~/Documents`
`Gnome Extension Manager` allows you to manage Gnome extensions.
`fastfetch` is pretty cool!Go to ~/Documents
Gnome Extension Manager allows you to manage Gnome extensions.
fastfetch is pretty cool!
Always wrap code around code block (```) for better legibility and styling consistency.
See code...
```bash
# this is some example bash code
sudo dnf update
```# this is some example bash code
sudo dnf updateCode tabs
Use code tabs to:
- Indicate changes are made in a specific file (indicated by the file name). Check Plume Theme Documentations for details on code highlighting.
- To not use unnecessary space when displaying multiple files.
See code...
::::code-tabs
@tab Hello.java
```java
public class Hello {
public static void main(String[] args) {
System.out.println("Hello world");
}
}
```
@tab example.md
```md
---
author: aier
permalink: /testing/aier/
---
# Title text
Content text... Content text... Content text...
Content text...
```
::::public class Hello {
public static void main(string[] args) {
Public.out.println("Hello world");
}
}---
author: aier
permalink: /testing/aier/
---
# Title text
Content text... Content text... Content text...
Content text...Demo wrapper
Use demo wrapper to show the product of something.
See code...
:::demo-wrapper
Content text...
:::Content text...
See code...
:::demo-wrapper img

:::
Details & collapse
Use details to collapse content that you don't want taking up a large amount of screen space.
See code...
:::details
The following is a picture of Ice Bear from We Bare Bears.

:::Details
The following is a picture of Ice Bear from We Bare Bears. 
When you have to use multiple details containers, use collapse instead.
Always pair collapse with a card unless the only content is a photo. If it has any text pair it with a card as such:
See code...
::::collapse accordion
- Use a card for mixed media and sole text.
:::card
The following is a picture of Ice Bear from We Bare Bears.

:::
- Card can be omitted in the case of a singular image.

::::Use a card for mixed media and sole text.
The following is a picture of Ice Bear from We Bare Bears.

Card can be omitted in the case of a singular image.

Headings
Heading 1 (#) does not appear in the table of contents, only use it in rare cases where Heading 2 (##) does not fit use-case.
Keep the keywords of Heading 2 (##) and 3 (###) bold. If the heading is relatively short, make the entire heading bold for better distinction from regular text and Heading 4 (####)
Heading 4 (####) does not appear on the table of contents, use it for minor titles/sections within larger topics
We prefer titlecase for Heading 2 (implicitly Heading 1), and NOT using titlecase in lower headings.
See example...
## **Heading 2**
### **Heading 3.1 would look like this**
### **Heading 3.2 would look like this**
## **Ricing Gnome** in 2025 with my friends
### **Heading 3.1 would look like this** if it was super duper long and has a lot of text
### **Heading 3.2 would look like this** if it was super duper long and has a lot of text
Highlighting
Use highlighting (==) to emphasise text, especially in paragraphs.
Highlights will replace bolding entirely.
Do not use highlighting in titles such as headings, step module titles, or collapse module titles.
See code...
Linux is known for being ==flexible, secure, and stable==.
It is ==open-source=={.important}, meaning its source code is freely available for anyone to view, modify, and distribute.
This fosters a ==collaborative global community== that continuously improves the system.
==Default==
==Info=={.info}
==Note=={.note}
==Tip=={.tip}
==Warning=={.warning}
==Danger=={.danger}
==Important=={.important}
Steps
Use "-" to auto-generate steps instead of manually numbering them. It helps maintenance and editing much easier.
Keep the keywords of your step titles bold. If the step title is relatively short, make the entire title bold for better distinction from content text.
Do not use bold in step description content — use highlighting (==) for any emphasis instead.
See code...
:::steps
- **This is a step**
Content...
- **This is another step**
This is even more content...
- **This is yet another step** but it is longer and you probably only want to make keywords bold
This is yet even more content...
:::This is a step
Content...
This is another step
This is even more content...
This is yet another step but it is longer and you probably only want to make keywords bold
This is yet even more content...
Tabs
Use tabs for showing multiple options to not use up unnecessary space.
The default tab order is Fedora, Debian/Ubuntu, Arch. Always follow this order when all three distros are present.
See code...
:::tabs
@tab ::devicon:fedora:: Fedora
```bash
sudo dnf install timeshift
```
@tab ::devicon:debian:: Debian/Ubuntu
```bash
sudo apt install timeshift
```
@tab ::devicon:archlinux:: Arch
```bash
pacman -S timeshift
```
:::sudo dnf install timeshiftsudo apt install timeshiftpacman -S timeshiftCode Tree
Use code tree for specifying file structures and/or to specify the content of many files under the same directory.
See code...
::::code-tree title="Some Python Project" height="400px" entry="src/main.py"
```python title="src/visualization/some-files.py"
e = mc^2
# Some more python code...
```
```python title="src/algorithms/algorithms.py"
Some impressive algorithm
```
```python title="src/main.py"
Some python code
```
```json title="dataset.json"
{
"data1": "Hello world",
"data2": {
"data3": "My name is Lunear"
}
}
```
::::src
visualization
some-files.py
algorithms
algorithms.py
main.py
dataset.json
e = mc^2
# Some more python code...Some impressive algorithmSome python code{
"data1": "Hello world",
"data2": {
"data3": "My name is Lunear"
}
}Contributors
Changelog
fa6be-Enhance contribution guidelines with detailed nesting rules for formatting tools and clarify tab order for package installation commands.onde047-Updated guidelines to be more clear with bolding instructions.on3d2f3-Updated guidelines for more clarity.onb8300-Updated guideline for consistency in bolding and highlighting, as well as including an article‑tagging section and a language‑usage section.on00c9a-#39 Reformat project so each markdown file has their own asset subfolder in the public asset folder.on41235-GB Englishon7c162-Consistent grammar.on2348f-Grammatical adjustmentson08511-Fixed formatting issueon336cc-Modifed highlighting section under contribution guidelines to maintain consistencyon77d41-Updated highlighting section under contribution guidelines to emphasize highlight use and its replacement for bold.on35118-Grammar and Spell Checks for the entire Webondc097-Moving to GitHub Development.on5f55a-Flatpak icons addedon0ba7f-Wordingon53f77-Added Code structureon6c937-Updated icon, heading, nad highlight guidelineson90b93-Improved icons guideline clarityona0c49-Updated steps and inline code guidelineon0228f-Refactor documentation for improved clarity and consistency in formattingonb67e5-Refactor code structure for improved readability and maintainabilityon57cf3-Minor fixesonf1456-Updated guidelines and fixed inconsistencyon3bf15-Added linking guideline.on9537b-Update terminal customization and guides to include devicons for Linux distributionson6e7b8-Fix formatting for code tree sections in contribution guidelinesone3681-Vuepress guide completed, Added code-tree to guidlines, arch guide modified.on603ab-Remove redundant header sections from demo wrapper examples for improved clarityon2783c-Add code section with usage examples for clarity and consistency in contribution guidelinesondaeb8-Enhance documentation by adding missing line breaks, updating demo wrappers to include images, and refining contribution guidelines for clarity and consistency.on3daf8-Add guidelines for callout containers and enhance code tabs section for clarityonf84c0-Enhance contribution guidelines by adding 'details' containers for better code examples and readability; improve structure and consistency throughout the document.on1c174-Revise contribution guidelines for clarity and structure; enhance file naming, permalink, and code formatting sections, and add examples for better understanding.on9c3a8-Contributions under its own category under About.on9004c-Guideline links.onf752b-Added more details to guidelines.on9d94b-maintainers tag added and guideline page addedon