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.

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