125 lines
2.6 KiB
Markdown
125 lines
2.6 KiB
Markdown
# MkDocs Material
|
|
|
|
Modern documentation site generator with live preview.
|
|
|
|
## Overview
|
|
|
|
MkDocs Material is a powerful documentation framework built on top of MkDocs, providing a beautiful Material Design theme and advanced features for creating professional documentation sites.
|
|
|
|
## Features
|
|
|
|
- Material Design theme
|
|
- Live preview during development
|
|
- Search functionality
|
|
- Navigation and organization
|
|
- Code syntax highlighting
|
|
- Mathematical expressions support
|
|
- Responsive design
|
|
- Customizable themes and colors
|
|
|
|
## Access
|
|
|
|
- **Development Port**: 4000
|
|
- **Development URL**: `http://localhost:4000`
|
|
- **Live Reload**: Automatically refreshes on file changes
|
|
|
|
## Configuration
|
|
|
|
### Main Configuration
|
|
|
|
Configuration is managed through `mkdocs.yml` in the project root.
|
|
|
|
### Volumes
|
|
|
|
- `./mkdocs`: Documentation source files
|
|
- `./assets/images`: Shared images directory
|
|
|
|
### Environment Variables
|
|
|
|
- `SITE_URL`: Base domain for the site
|
|
- `USER_ID`: User ID for file permissions
|
|
- `GROUP_ID`: Group ID for file permissions
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
mkdocs/
|
|
├── mkdocs.yml # Configuration file
|
|
├── docs/ # Documentation source
|
|
│ ├── index.md # Homepage
|
|
│ ├── services/ # Service documentation
|
|
│ ├── blog/ # Blog posts
|
|
│ └── overrides/ # Template overrides
|
|
└── site/ # Built static site
|
|
```
|
|
|
|
## Writing Documentation
|
|
|
|
### Markdown Basics
|
|
|
|
- Use standard Markdown syntax
|
|
- Support for tables, code blocks, and links
|
|
- Mathematical expressions with MathJax
|
|
- Admonitions for notes and warnings
|
|
|
|
### Example Page
|
|
|
|
```markdown
|
|
# Page Title
|
|
|
|
This is a sample documentation page.
|
|
|
|
## Section
|
|
|
|
Content goes here with **bold** and *italic* text.
|
|
|
|
### Code Example
|
|
|
|
```python
|
|
def hello_world():
|
|
print("Hello, World!")
|
|
```
|
|
|
|
!!! note
|
|
This is an informational note.
|
|
```
|
|
|
|
## Building and Deployment
|
|
|
|
### Development
|
|
|
|
The development server runs automatically with live reload.
|
|
|
|
### Building Static Site
|
|
|
|
```bash
|
|
docker exec mkdocs-changemaker mkdocs build
|
|
```
|
|
|
|
The built site will be available in the `mkdocs/site/` directory.
|
|
|
|
## Customization
|
|
|
|
### Themes and Colors
|
|
|
|
Customize appearance in `mkdocs.yml`:
|
|
|
|
```yaml
|
|
theme:
|
|
name: material
|
|
palette:
|
|
primary: blue
|
|
accent: indigo
|
|
```
|
|
|
|
### Custom CSS
|
|
|
|
Add custom styles in `docs/stylesheets/extra.css`.
|
|
|
|
## Official Documentation
|
|
|
|
For comprehensive MkDocs Material documentation:
|
|
- [MkDocs Material](https://squidfunk.github.io/mkdocs-material/)
|
|
- [MkDocs Documentation](https://www.mkdocs.org/)
|
|
- [Markdown Guide](https://www.markdownguide.org/)
|