Skip to content

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.

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