This directory contains the documentation for Watchflow, built with MkDocs and the Material theme. Docs are maintainer-first and tech-forward: speak to engineers, not marketing; anchor Watchflow as the immune system for the repo, not another AI tool.
- Python 3.12+
- uv (recommended) or pip
-
Install dependencies
# Install all dependencies including docs (recommended) uv sync # Or install just the docs dependencies uv add mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin mkdocs-minify-plugin pymdown-extensions # Alternative: using pip (if uv is not available) pip install -e ".[docs]"
-
Start the development server
mkdocs serve
-
Open your browser
- Navigate to http://127.0.0.1:8000
- The site will automatically reload when you make changes
# Build the site
mkdocs build
# Build and serve
mkdocs serve- Use standard Markdown syntax
- Leverage Material theme features like admonitions, tabs, and code blocks
- Include code examples with proper syntax highlighting
-
Be clear and concise
- Use simple, direct language
- Break complex topics into digestible sections
- Include practical examples
-
Stay consistent
- Follow the established tone and style
- Use consistent terminology (see glossary.md)
- Maintain consistent formatting
-
Include examples
- Provide real-world use cases
- Include code snippets and configuration examples
- Show before/after scenarios
-
Cross-reference
- Link to related sections
- Reference the glossary for technical terms
- Include "Next Steps" sections
Use admonitions to highlight important information:
!!! note "Note"
This is a note with important information.
!!! warning "Warning"
This is a warning about potential issues.
!!! tip "Tip"
This is a helpful tip for users.
!!! example "Example"
This is an example of how to do something.Use syntax highlighting for code blocks:
```python
def example_function():
return "Hello, World!"# Configuration example
service:
type: NodePort
port: 8000
## Contributing
### Adding New Pages
1. **Create the markdown file** in the appropriate directory
2. **Update navigation** in `mkdocs.yml`
3. **Add cross-references** to related pages
4. **Test locally** with `mkdocs serve`
### Updating Existing Pages
1. **Make your changes** in the markdown file
2. **Test locally** to ensure formatting is correct
3. **Update any cross-references** if needed
4. **Commit with a descriptive message**
### Pull Request Process
1. **Fork the repository**
2. **Create a feature branch**
3. **Make your changes**
4. **Test locally**
5. **Submit a pull request**
## Deployment
The documentation is automatically deployed to GitHub Pages when changes are pushed to the `main` branch. The deployment is handled by the [GitHub Actions workflow](../.github/workflows/docs.yml).
### Manual Deployment
```bash
# Build the site
mkdocs build
# Deploy to GitHub Pages (if configured)
mkdocs gh-deploy
The documentation is configured via mkdocs.yml in the root directory. Key configuration options:
- Theme: Material theme with custom styling
- Navigation: Hierarchical structure with sections
- Plugins: Search, git revision dates, minification
- Extensions: Various Markdown extensions for enhanced features
Site not building
- Check for syntax errors in markdown files
- Verify all referenced files exist
- Check the mkdocs.yml configuration
Styling issues
- Ensure Material theme is properly installed
- Check for custom CSS conflicts
- Verify theme configuration in mkdocs.yml
Navigation problems
- Check the nav structure in mkdocs.yml
- Ensure all referenced files exist
- Verify file paths are correct
For questions about the documentation, please open an issue or start a discussion on GitHub.