Skip to content

Contributor Quick-Start Guide

Welcome! This guide will help you write your first guide in 15 minutes.

Quick Setup

# 1. Fork and clone
git clone https://github.com/<your-username>/guides.git
cd guides

# 2. Install dependencies
pip install -r requirements.txt

# 3. Start local server
./setup-docs.sh
mkdocs serve

Open http://localhost:8000 to preview your changes.

Write Your First Guide

Step 1: Create the File

Create a new .md file in the appropriate directory:

# Example: Create a guide about process management
touch "Linux Essentials/process-management.md"

Step 2: Use the Template

Copy this template into your new file:

---
difficulty: beginner
time_estimate: 20 minutes
prerequisites:
  - Basic command line familiarity
learning_outcomes:
  - What the reader will be able to do after reading
tags:
  - linux
  - process-management
---

# Your Guide Title

Brief introduction - what this guide covers and why it matters (2-3 sentences).

---

## Overview

Explain the core concept. Include practical examples.

```bash
# Example command
command --option argument
```

---

## Common Tasks

### Task One

Step-by-step instructions with code examples.

### Task Two

More practical examples.

---

## Troubleshooting

Address common issues and solutions.

---

## Further Reading

- [Official Documentation](https://example.com) - Brief description
- [Related Resource](https://example.com) - Brief description

---

**Previous:** [Previous Guide](previous-guide.md) | **Next:** [Next Guide](next-guide.md) | [Back to Index](README.md)

Step 3: Wire It Up

A new guide needs more than a nav entry. Update all of these, or the guide will render without its metadata banner and stay invisible to the topic index:

  1. mkdocs.yml - add it to nav:
nav:
  - Linux Essentials:
    - ...existing guides...
    - Process Management: Linux Essentials/process-management.md
  1. assets/javascripts/lib/topics.js - add it to the topic's guide list.
  2. The section README.md - add a topic card with data-guide and data-topic attributes.
  3. .github/ISSUE_TEMPLATE/content-improvement.yml - add it to the guide dropdown.
  4. The previous guide's nav footer - add the Next: link pointing at your guide.

Tip

Inserting a guide between two existing ones? Update both neighbours - the previous guide's Next: link and the next guide's Previous: link.

Step 4: Preview and Test

mkdocs serve
# Open http://localhost:8000
# Click around to verify links work

Style Essentials

Element Format
Commands `backticks`
Key terms Bold on first use
File paths `/path/to/file`
Sections ## Heading + --- separator

Use Admonitions

!!! tip
    Helpful advice here.

!!! warning
    Potential pitfall here.

!!! danger
    Critical warning here.

Add Interactive Components

Place these after the content they test, not before it.

Quick Quiz Example

<div class="interactive-quiz" data-config="{&quot;question&quot;: &quot;Your question here?&quot;, &quot;type&quot;: &quot;multiple-choice&quot;, &quot;options&quot;: [{&quot;text&quot;: &quot;Wrong answer&quot;, &quot;feedback&quot;: &quot;Why it&#39;s wrong.&quot;}, {&quot;text&quot;: &quot;Correct answer&quot;, &quot;correct&quot;: true, &quot;feedback&quot;: &quot;Why it&#39;s correct.&quot;}]}"><noscript><p><strong>Your question here?</strong> (requires JavaScript)</p></noscript></div>

Terminal Simulation Example

<div class="interactive-terminal" data-config="{&quot;title&quot;: &quot;Demo Title&quot;, &quot;steps&quot;: [{&quot;command&quot;: &quot;your-command&quot;, &quot;output&quot;: &quot;expected output&quot;, &quot;narration&quot;: &quot;Explain what happened.&quot;}]}"><noscript><p><strong>Demo Title</strong> (requires JavaScript)</p></noscript></div>

Submit Your Guide

  1. Run the check: 
    ./verify.sh

This is the same gate CI runs. For a docs-only change, the build step alone is enough:

./setup-docs.sh && mkdocs build --strict

  1. Commit with proper prefix: 

    git add .
git commit -m "docs: add process management guide"

  2. Push and open PR: 

    git push origin your-branch-name

  3. Open pull request on GitHub with:

  4. Clear title describing your change
  5. Brief description of what you added/fixed

Checklist Before Submitting

  • [ ] File follows the guide template, including the YAML frontmatter
  • [ ] All five wiring steps done (nav, topics.js, section README, issue template, neighbour footers)
  • [ ] Code examples tested and working
  • [ ] ./verify.sh passes
  • [ ] Commit message starts with docs:

Need Help?

  • Check CONTRIBUTING.md for the full style guide, the interactive component reference, and licensing details
  • Open an issue for questions
  • Review existing guides for examples

You're ready! Start writing and submit your first pull request.

Comments