64 lines
3.6 KiB
Markdown
64 lines
3.6 KiB
Markdown
# 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](https://www.mkdocs.org/).
|
|
|
|
## 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:
|
|
```yaml
|
|
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](https://www.mkdocs.org/)
|
|
* **MkDocs Material Theme**: [Official Material for MkDocs Documentation](https://squidfunk.github.io/mkdocs-material/)
|
|
* **Your Site's Authoring Guide**: Check out `guides/authoring-content.md` in your `mkdocs/docs/` directory.
|