Changemaker/mkdocs/docs/apps/mkdocs-material.md

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

• 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.