Skip to content

Editing This Documentation

How This Site Works

This documentation site is built using MkDocs with the Material for MkDocs theme. All content is written in Markdown — a simple formatting language designed to be easy to read and write, even in its raw form.

The source files live in a GitHub repository: hourcar-mn/hourcar-docs. When changes are merged into the main branch, Cloudflare Pages automatically rebuilds the site and publishes the updated version. The site is protected by Cloudflare Access, so only staff authenticated with their @hourcar.org Microsoft 365 account can view it.

You don't need to understand any of the hosting infrastructure to contribute. You just need to be able to edit Markdown files and get your changes into the GitHub repository — and there are two ways to do that.

Option 1: Edit Directly on GitHub

This is the quickest way to make changes and doesn't require installing anything on your computer. It works well for fixing typos, updating information, or making straightforward edits to existing pages.

Getting Access

You'll need an invitation to the HOURCAR GitHub organization. Contact IT if you don't have access yet.

Making an Edit

  1. Navigate to the page you want to edit on this documentation site.
  2. Click the pencil icon (edit button) near the top of the page. This will take you directly to the file on GitHub.
  3. Click the pencil icon on GitHub to open the editor.
  4. Make your changes. The file is written in Markdown — see the Markdown reference section below if you need help with formatting.
  5. When you're done, click Commit changes. GitHub will ask you to write a short description of what you changed.
  6. Select Create a new branch and then Propose changes. This creates a pull request — a proposal for your changes to be reviewed and merged into the live site.
  7. IT will review and merge your pull request. Once merged, the site updates automatically.

Tip

If you're making a small, obvious fix (like correcting a typo), you can mention that in the commit message and it can be merged quickly. For bigger changes, a brief description of what you changed and why is helpful.

Option 2: Edit Locally

Editing locally gives you a live preview of your changes before they go live, which is helpful for larger contributions, new pages, or anything involving formatting that you want to verify visually. This requires some initial setup but provides a much better editing experience for frequent contributors.

Software You'll Need

Install the following from Company Portal:

  • Python — required to run MkDocs
  • Visual Studio Code — the text editor you'll use to write and edit files
  • Git — version control, used to sync your changes with GitHub

VS Code has built-in Git support, so you won't need any additional software to manage your changes.

These aren't required but will make your life easier:

Initial Setup

These steps only need to be done once.

  1. Clone the repository — Open VS Code and press Ctrl+Shift+P to open the Command Palette. Type Git: Clone and press Enter. Paste the repository URL:

    https://github.com/hourcar-mn/hourcar-docs.git

    Choose a location on your computer to save it (e.g., your Documents folder). VS Code will download the repository and offer to open it.

  2. Sign in to GitHub — VS Code will prompt you to sign in to GitHub when you first interact with the repository. Follow the prompts to authenticate with your GitHub account.

  3. Install dependencies — Open a terminal in VS Code (Terminal > New Terminal) and run:

    python -m pip install -r requirements.txt

    This installs MkDocs and the plugins the site uses.

Editing and Previewing

  1. Open the terminal in VS Code and start the local preview server:

    python -m mkdocs serve

  2. Open http://localhost:8000 in your browser (or the URL printed in the terminal). You'll see a local copy of the documentation site.

  3. Open and edit any .md file in the docs/ folder. Every time you save, the preview will automatically refresh with your changes.

  4. When you're happy with your edits, move on to submitting your changes.

Submitting Your Changes

Git tracks changes to files and lets multiple people collaborate without overwriting each other's work. Here are the key concepts:

  • Commit — a snapshot of your changes, with a short message describing what you did
  • Branch — a separate copy of the codebase where you can make changes without affecting the live site
  • Pull request — a proposal to merge your branch into main, where others can review your changes before they go live
  • Push — uploading your commits from your computer to GitHub

Here's the workflow, all done within VS Code:

  1. Create a branch — In the bottom-left corner of VS Code, click the branch name (likely main). Select Create new branch and give it a descriptive name (e.g., update-fleet-docs).

  2. Commit your changes — Open the Source Control panel (the branch icon in the left sidebar, or Ctrl+Shift+G). You'll see a list of files you've changed. Write a short summary of what you did in the message box and click Commit.

  3. Push to GitHub — After committing, click Publish Branch (or Sync Changes if you've pushed before) to upload your changes to GitHub.

  4. Open a pull request — VS Code may prompt you to create a pull request. You can also go to the hourcar-docs repository on GitHub where you'll see a banner offering to create a pull request for your branch. Add a brief description of your changes.

  5. Get it reviewed and merged — IT will review your pull request. Once approved and merged, the live site updates automatically.

Markdown Reference

Markdown is designed to be readable even in its raw form. Here are the most common things you'll need:

Text Formatting

**bold text**
*italic text*
~~strikethrough~~

Headings

# Page Title (H1)
## Section (H2)
### Subsection (H3)

Use headings to organize content hierarchically. Each page should have one # heading at most — use ## and below for sections within the page.

[link text](https://example.com)
[link to another doc page](path/to/page.md)

Lists

- Bullet item
- Another item
    - Nested item

1. Numbered item
2. Another item

Images

![alt text](path/to/image.png)

Tables

| Column 1 | Column 2 |
| -------- | -------- |
| Cell 1   | Cell 2   |
| Cell 3   | Cell 4   |

Callout Boxes (Admonitions)

This site supports special callout boxes for tips, warnings, and notes:

!!! note
    This is a note callout.

!!! warning
    This is a warning callout.

!!! tip
    This is a tip callout.

Note

This is what a note callout looks like when rendered.

Further Reading

For a complete Markdown reference, see the Markdown Guide. For Material for MkDocs-specific features like callouts, tabs, and more, see the Material for MkDocs documentation.

Site Structure

Documentation files are organized in the docs/ folder. The folder structure mirrors the navigation of the site:

docs/
├── index.md                  # Home page
├── general/                  # General staff info
├── Tools.md                  # Shared tools and links
├── Member-Services/          # Member Services docs
├── Fleet/                    # Fleet operations
├── Vehicles/                 # Vehicle reference
└── tech/                     # IT and technical docs
    ├── IT/                   # IT procedures
    ├── technical/            # Technical reference
    ├── configurations/       # Vulog configurations
    ├── data/                 # Database and API docs
    ├── procedures/           # IT procedures
    └── vulog-apps/           # App downloads and setup

To add a new page, create a new .md file in the appropriate folder. It will automatically appear in the site navigation.

Getting Help

If you run into issues or have questions about contributing, contact IT at support@hourcar.org or open a Jira ticket. We're happy to walk you through the process.