Contributing To Garnet Wiki

Comprehensive reference for contributing to garnet wiki covering essential concepts, practical examples, and production best practices.

Contributing to the Garnet Wiki is the primary way engineers, maintainers, and collaborators shape the project’s knowledge base. Whether you’re fixing a typo, adding a new tutorial, or restructuring a guide, this process ensures every page is precise, discoverable, and aligned with the project’s standards. You’ll contribute when you first join the team, when you encounter a gap in documentation, or when you’re asked to improve a page after a code review. The workflow is consistent, predictable, and grounded in the tools the team already uses.

Setting Up Your Contribution Environment

Before writing or editing, ensure your local setup matches the Garnet Wiki’s expectations. The wiki is built using a static site generator and hosted on a cloud file server with version control. All edits happen via Git, and the source is stored in a repository at https://github.com/garnet-wiki/garnet-wiki.

Start by cloning the repository and checking out the main branch:

git clone https://github.com/garnet-wiki/garnet-wiki.git
cd garnet-wiki
git checkout main

Install the required tools: node (v18 or later), npm, and mkdocs (a static site generator for documentation). The project uses mkdocs with the material theme and a mkdocs.yml configuration file.

Ensure your mkdocs.yml is up to date:

site_name: Garnet Wiki
site_url: https://wiki.garnet.dev
site_description: The central knowledge hub for Garnet project
site_author: Garnet Engineering Team
theme:
  name: material
  palette:
    primary: blue
    accent: deep-purple
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.top
    - search.highlight
    - search.share
    - content.code.copy
    - content.tabs
    - content.code.annotate
    - navigation.instant
  logo: assets/logo.svg
nav:
  - Home: index.md
  - Guides: guides/index.md
  - How To: how-to/index.md
  - Reference: reference/index.md
plugins:
  - search
  - git-revision-date-localized
  - sitemap
extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/garnet-wiki/garnet-wiki
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/garnetwiki

Run the local server to preview your changes:

mkdocs serve

This starts a development server at http://localhost:8000, which automatically rebuilds pages on file changes. You can now edit Markdown files in the docs/ directory and see live previews.

Writing and Editing Pages

Each page in the Garnet Wiki is a Markdown file with a .md extension. The top of every page contains a YAML front matter block, which controls metadata like title, description, and navigation order.

When creating a new page, use the following template:

---
title: How To: Use Git in Garnet Wiki
description: A step-by-step guide to contributing using Git, from setup to PR review.
tags: [git, contribution, how-to]
toc: true
toc_title: Contents
---

The toc field enables a table of contents, which is automatically generated and displayed on the left sidebar. The toc_title field sets the heading label above the TOC.

For complex pages, use headings to structure content. The hierarchy should follow these rules:

Use > for callouts, and ::: for custom blocks:

> **Tip:** Always commit with a descriptive message.
>
> Use `git commit -m "feat: add search feature in user profile"` for feature changes.
>
> **Note:** The `mkdocs.yml` file is the single source of truth for site configuration.

::: tip
Use the `mkdocs serve` command to preview changes locally before pushing.
:::

::: danger
Failing to run `mkdocs build` before pushing causes missing assets and broken links.
:::

Adding Code and Configuration Examples

When documenting code, always use fenced code blocks with syntax highlighting. The default language is plaintext, but use the following:

For example, when documenting a configuration file:


[database]
host = "localhost"
port = 5432
name = "garnet_production"
username = "garnet"
password = "secret"

[server]
host = "0.0.0.0"
port = 8080
workers = 4
debug = true

[logging]
level = "info"
format = "json"
file = "logs/garnet.log"

For command-line output, use bash blocks with $ for prompts:

$ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git commit -m <message>..." to commit)

	modified:   docs/contributing.md
	new file:   docs/how-to/use-git.md

Untracked files:
  (use "git add <file>..." to include in what will be committed)

	assets/images/logo.svg

no changes added to commit (use "git add" and/or "git commit")

Reviewing and Improving Existing Pages

When you find a page that needs improvement, follow the contribution lifecycle:

  1. Fork the repository on GitHub.
  2. Create a new branch with a descriptive name:
   git checkout -b fix/typo-in-getting-started
  1. Edit the page, making changes in your local environment.
  2. Preview your changes using mkdocs serve.
  3. Commit your changes with a clear message:
   git commit -m "docs: fix typo in Getting Started guide"
  1. Push your branch to your fork:
   git push origin fix/typo-in-getting-started
  1. Create a pull request (PR) from your branch to garnet-wiki/main.

In the PR description, include:

Common Pitfalls in PRs

Testing Your Changes

Before merging, verify that your changes render correctly and are consistent with the project’s style.

Run the build command:

mkdocs build

This creates a site/ directory with the complete static site. Check that:

Use mkdocs serve to verify the live preview, and test the search functionality by typing into the search bar.

Critical Failure Modes

Merging and Publishing

When a PR is approved, the maintainer merges it into main. The following actions occur automatically:

The new version becomes live at https://wiki.garnet.dev within minutes.

Post-Merge Checklist

After merging, ensure the following:

Advanced Contributions

For deeper involvement, contribute to the structure and style of the wiki itself.

Creating a New Guide Section

To add a new section like How To, create a directory docs/how-to/ and add an index.md file:

---
title: How To
description: Step-by-step instructions for common tasks in Garnet.
nav_order: 2
---

Then, add individual how-to pages inside, each with nav_order to control the display order.

Adding a Custom Theme Feature

The Garnet Wiki uses the Material theme. To extend it:

  1. Create a theme/ directory in the project root.
  2. Add a custom.css file with additional styles.
  3. Include a custom.js file for client-side logic.
  4. Update mkdocs.yml to load the files:
theme:
  name: material
  custom_dir: theme
  language: en

Using the Search Index

The search is powered by mkdocs-search plugin. The index is built during mkdocs build and stored in site/search/. To improve search relevance:

---
title: Debugging Production Guide
description: Troubleshooting issues in production environments.
tags: [debugging, production, guide]
keywords: debugging, production, troubleshooting, logs, monitoring
---

Final Notes

Contributing to the Garnet Wiki is not just about writing content. It is about maintaining consistency, clarity, and usability across a growing knowledge base. Every edit should follow the same conventions: correct front matter, proper code blocks, clear structure, and thorough testing. When you contribute, you ensure that the next engineer finds exactly what they need—without confusion, without guesswork, and without friction.

This page was rewritten on 18 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.