Skip to content
Login Changemaker Archive. Learn more

# MkDocs with Material Theme: Your Documentation Powerhouse

Changemaker V5 utilizes MkDocs with the Material theme to build this very documentation site. MkDocs is a fast, simple, and downright gorgeous static site generator that's geared towards building project documentation with Markdown.

## Key Features of MkDocs & Material Theme

- Simple Markdown Syntax: Write documentation in plain Markdown files.
- Fast and Lightweight: Generates static HTML files that load quickly.
- Material Design: A clean, modern, and responsive design out-of-the-box.
- Highly Customizable: Extensive configuration options for themes, navigation, plugins, and more.
- Search Functionality: Built-in search makes it easy for users to find information.
- Plugin Ecosystem: Extend MkDocs with various plugins (e.g., for blog functionality, social cards, diagrams).
- Live Reload Server: `mkdocs serve` provides a development server that automatically reloads when you save changes.

## Documentation

For more detailed information about MkDocs, visit the official documentation.

## Editing This Site (Your Changemaker Documentation)

All content for this documentation site is managed as Markdown files within the `mkdocs/docs/` directory of your Changemaker project.

### How to Edit or Add Content:

1. Access Code Server: As outlined on the homepage and in the Code Server documentation, log into Code Server. Your password is in `configs/code-server/.config/code-server/config.yaml`.
2. Navigate to the `docs` Directory:
   - In Code Server's file explorer, open your Changemaker project folder (e.g., `/home/bunker-admin/Changemaker/`).
   - Go into the `mkdocs/docs/` subdirectory.
3. Find or Create Your Page:
   - To edit an existing page: Navigate to the relevant `.md` file (e.g., `apps/code-server.md` to edit the Code Server page, or `index.md` for the homepage content if not using `home.html` override directly).
   - To create a new page: Create a new `.md` file in the appropriate location (e.g., `apps/my-new-app.md`).
4. Write in Markdown: Use standard Markdown syntax. Refer to the `guides/authoring-content.md` for tips on Markdown and MkDocs Material specific features.
5. Update Navigation (if adding a new page):
   - Open `mkdocs/mkdocs.yml`.
   - Add your new page to the `nav:` section to make it appear in the site navigation. For example:

         nav:
           - Home: index.md
           - ...
           - Applications:
             - ...
             - My New App: apps/my-new-app.md # Add your new page here
           - ...

6. Save Your Changes: Press `Ctrl+S` (or `Cmd+S` on Mac) in Code Server.
7. Preview Changes:
   - The MkDocs development server (if you've run `mkdocs serve` in a terminal within your `mkdocs` directory) will automatically rebuild the site and your browser should refresh to show the changes.
   - The typical URL for the local development server is `http://localhost:8000` or `http://127.0.0.1:8000`.

### Site Configuration

The main configuration for the documentation site is in `mkdocs/mkdocs.yml`. Here you can change: * `site_name`, `site_description`, `site_author` * Theme features and palette * Markdown extensions * Navigation structure (`nav`) * Plugins

## Further Information

- MkDocs: Official MkDocs Documentation
- MkDocs Material Theme: Official Material for MkDocs Documentation
- Your Site's Authoring Guide: Check out `guides/authoring-content.md` in your `mkdocs/docs/` directory.