Contribution Guidelines

About 1688 wordsAbout 6 min

Contributions

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 jeopardize 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 Customization (Bash) @ /docs/guides/terminal-customization-bash.md

--> /guides/terminal-customization-bash/

Code formatting

We're not strict with our code formatting as long as the output of your code is clean (i.e. the generated content is pretty).

We'd appreciate it if you use the Prettier extension in VS Code or an equivalent to format your code, though.

Use relative links over permalinks when refering to internal pages to make the development smoother, when possible.

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.

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 coponents clean, without colors.

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 color 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 annoucement 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 1

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.

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 update

Code 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) {

    Public.out.println("Hello world");
  }
}
```

@tab example.md

```md
---
author: aier
permalink: /testing/aier/
---

# Title text

Content text... Content text... Content text...

Content text...
```

::::

Hello.java

public class Hello {

  public static void main(string[] args) {

    Public.out.println("Hello world");
  }
}

example.md

---
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
![Tuxie's Wiki](./assets/tuxies-wiki.png)
:::

Tuxie's Wiki

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.
![Ice Bear](./assets/ice-bear.jpg)

:::

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.

  ![Ice Bear](./assets/ice-bear.jpg)

  :::

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

  ![Ice Bear](./assets/ice-bear.jpg)

::::

Use a card for mixed media and sole text.

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 usecase.
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 not using titlecase in 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

Headings

Highlighting

Use highlighting (==) to emphasize text, especially in paragraphs.

Do not use highlighting in titles such as haedings, step module titles, or collapse module titles.

See code...

Linux is known for being flexible, secure, and stable. It is open-source, 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.

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.

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.

See code...

:::tabs

@tab ::devicon:debian:: Debian/Ubuntu

```bash
sudo apt install timeshift
```

@tab ::devicon:fedora:: Fedora

```bash
sudo dnf install timeshift
```

@tab ::devicon:archlinux:: Arch

```bash
pacman -S timeshift
```

:::

Debian/Ubuntu

sudo apt install timeshift

Fedora

sudo dnf install timeshift

Arch

pacman -S timeshift

Code 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"
  }
}
```

::::

Some Python Project

src

visualization

some-files.py

algorithms

algorithms.py

main.py

dataset.json

src/visualization/some-files.py
e = mc^2

# Some more python code...
src/algorithms/algorithms.py
Some impressive algorithm
src/main.py
Some python code
dataset.json
{
  "data1": "Hello world",
  "data2": {
    "data3": "My name is Lunear"
  }
}

Changelog

8/11/25, 2:48 PM

View All Changelog

5f55a-Flatpak icons addedon 8/11/25
0ba7f-Wordingon 8/10/25
53f77-Added Code structureon 8/9/25
6c937-Updated icon, heading, nad highlight guidelineson 7/16/25
90b93-Improved icons guideline clarityon 7/15/25
a0c49-Updated steps and inline code guidelineon 7/15/25
0228f-Refactor documentation for improved clarity and consistency in formattingon 7/15/25
b67e5-Refactor code structure for improved readability and maintainabilityon 7/12/25
57cf3-Minor fixeson 6/26/25
f1456-Updated guidelines and fixed inconsistencyon 6/26/25
3bf15-Added linking guideline.on 6/26/25
9537b-Update terminal customization and guides to include devicons for Linux distributionson 6/25/25
6e7b8-Fix formatting for code tree sections in contribution guidelineson 6/13/25
e3681-Vuepress guide completed, Added code-tree to guidlines, arch guide modified.on 6/13/25
603ab-Remove redundant header sections from demo wrapper examples for improved clarityon 6/12/25
2783c-Add code section with usage examples for clarity and consistency in contribution guidelineson 6/12/25
daeb8-Enhance documentation by adding missing line breaks, updating demo wrappers to include images, and refining contribution guidelines for clarity and consistency.on 6/12/25
3daf8-Add guidelines for callout containers and enhance code tabs section for clarityon 6/12/25
f84c0-Enhance contribution guidelines by adding 'details' containers for better code examples and readability; improve structure and consistency throughout the document.on 6/12/25
1c174-Revise contribution guidelines for clarity and structure; enhance file naming, permalink, and code formatting sections, and add examples for better understanding.on 6/12/25
9c3a8-Contributions under its own category under About.on 6/11/25
9004c-Guideline links.on 6/10/25
f752b-Added more details to guidelines.on 6/10/25
9d94b-maintainers tag added and guideline page addedon 6/10/25