Documentation Guide — MkDocs¶

This project uses MkDocs with the Material theme to generate professional documentation from markdown files. This guide explains how to work with the documentation system.

What is MkDocs?¶

MkDocs is a static site generator that transforms markdown files into a beautiful, searchable documentation website with:

Navigation sidebar automatically generated
Search functionality across all pages
Professional theme (Material for MkDocs)
Mobile-friendly responsive design
Version control friendly — docs are just markdown files

Quick Reference¶

View Documentation Locally¶

# Install documentation dependencies
uv sync --group docs

# Serve docs with live reload (default port 8000)
uv run mkdocs serve

# Use custom port to avoid conflicts with the API
uv run mkdocs serve --dev-addr localhost:8001

Then open http://localhost:8001 in your browser. Changes to markdown files will automatically reload!

Build Static Site¶

# Build HTML site to site/ folder
uv run mkdocs build

# Build with verbose output
uv run mkdocs build --verbose

# Clean build (remove site/ first)
uv run mkdocs build --clean

Deploy to GitHub Pages¶

# Deploy to GitHub Pages (gh-pages branch)
uv run mkdocs gh-deploy

# Deploy with custom commit message
uv run mkdocs gh-deploy --message "Update documentation"

Note: The project has automated deployment via GitHub Actions, so you typically don't need to run this manually.

Project Structure¶

Trump-Rally-Speeches-NLP-Chatbot/
├── docs/                    # All documentation files
│   ├── index.md            # Homepage
│   ├── faq.md              # Frequently asked questions
│   ├── guides/             # Getting started & step-by-step tutorials
│   │   ├── quickstart.md
│   │   ├── deployment.md
│   │   └── documentation.md    # This file
│   ├── development/        # Development workflow & tooling
│   │   ├── testing.md
│   │   ├── linting.md
│   │   └── ...
│   └── reference/          # API & feature documentation
│       ├── architecture.md
│       ├── rag-features.md
│       ├── topic-extraction.md
│       └── entity-analytics.md
├── mkdocs.yml              # MkDocs configuration
└── site/                   # Generated HTML (not committed)

How to Add or Edit Documentation¶

1. Edit Existing Pages¶

Simply edit any .md file in the docs/ folder. If you have mkdocs serve running, changes will appear instantly in your browser.

2. Add New Pages¶

Step 1: Create a new markdown file in the appropriate folder:

# Example: Add a new getting started guide
New-Item docs/guides/my-new-guide.md

Step 2: Add the page to navigation in mkdocs.yml:

nav:
  - Home: index.md
  - Getting Started:
      - Quickstart: guides/quickstart.md
      - My New Guide: guides/my-new-guide.md  # Add this line

Step 3: Preview with mkdocs serve and verify it appears in the sidebar.

Edit the nav section in mkdocs.yml:

nav:
  - Home: index.md
  - FAQ: faq.md

  - Getting Started:
      - Quickstart: guides/quickstart.md
      - Deployment: guides/deployment.md
      - Documentation: guides/documentation.md

  - Development:
      - Testing: development/testing.md
      - Linting: development/linting.md

  - Reference:
      - Architecture: reference/architecture.md
      - RAG Features: reference/rag-features.md
      - Topic Analysis: reference/topic-extraction.md
      - Entity Analytics: reference/entity-analytics.md

The order in mkdocs.yml determines the order in the sidebar.

Configuration Reference¶

Port Configuration¶

By default, MkDocs serves on port 8000. To change:

# Serve on port 8001
uv run mkdocs serve --dev-addr localhost:8001

# Serve on all interfaces (for network access)
uv run mkdocs serve --dev-addr 0.0.0.0:8001

Theme Customization¶

Edit mkdocs.yml to customize the theme:

theme:
  name: material
  palette:
    # Light mode
    - scheme: default
      primary: indigo      # Change primary color
      accent: indigo       # Change accent color

Available colors: red, pink, purple, deep purple, indigo, blue, light blue, cyan, teal, green, light green, lime, yellow, amber, orange, deep orange

Add a Logo¶

Add your logo image to docs/assets/images/
Update mkdocs.yml:

theme:
  name: material
  logo: assets/images/logo.png
  favicon: assets/images/favicon.ico

Add Custom CSS or JavaScript¶

Create files:
docs/stylesheets/extra.css
docs/javascripts/extra.js
Update mkdocs.yml:

extra_css:
  - stylesheets/extra.css

extra_javascript:
  - javascripts/extra.js

Markdown Features¶

MkDocs with Material theme supports rich markdown features:

Admonitions (Call-out Boxes)¶

!!! note
    This is a note admonition.

!!! warning
    This is a warning admonition.

!!! tip
    This is a tip admonition.

??? example "Collapsible Example"
    This content is collapsed by default.

Note

This is a note admonition.

Warning

This is a warning admonition.

Code Blocks with Syntax Highlighting¶

```python
def hello_world():
    print("Hello, World!")
```

```bash
uv run pytest
```

Tabbed Content¶

=== "Python"
    ```python
    print("Hello from Python")
    ```

=== "PowerShell"
    ```powershell
    Write-Host "Hello from PowerShell"
    ```

PythonPowerShell

print("Hello from Python")

Write-Host "Hello from PowerShell"

Task Lists¶

- [x] Completed task
- [ ] Incomplete task
- [ ] Another task

Completed task
Incomplete task
Another task

Tables¶

| Feature | Supported |
|---------|-----------|
| Search  | ✅        |
| Mobile  | ✅        |
| Dark Mode | ✅      |

Feature	Supported
Search	✅
Mobile	✅
Dark Mode	✅

Mermaid Diagrams¶

```mermaid
graph LR
    A[User] --> B[API]
    B --> C[RAG Service]
    C --> D[ChromaDB]
```

graph LR
    A[User] --> B[API]
    B --> C[RAG Service]
    C --> D[ChromaDB]

Deployment¶

Automated Deployment (Recommended)¶

The project includes a GitHub Action that automatically deploys documentation to GitHub Pages when you push to the main branch.

How it works:

You push changes to main
GitHub Actions builds the docs
Deploys to GitHub Pages automatically
Live at: https://justakris.github.io/Trump-Rally-Speeches-NLP-Chatbot/

Configuration: See .github/workflows/deploy-docs.yml

Manual Deployment¶

If you need to deploy manually:

# Deploy to GitHub Pages
uv run mkdocs gh-deploy

This command:

Builds the site (mkdocs build)
Commits the site/ folder to the gh-pages branch
Pushes to GitHub

Note: Ensure you have push access to the repository.

Troubleshooting¶

Port Already in Use¶

If port 8000 is already in use by your API:

uv run mkdocs serve --dev-addr localhost:8001

Check mkdocs.yml navigation and ensure:

The file path is correct (relative to docs/)
The file exists
The file has a .md extension

Changes Not Appearing¶

Check terminal for build errors
Hard refresh browser (Ctrl+Shift+R)
Restart mkdocs serve

Build Warnings¶

WARNING - Doc file 'path/to/file.md' contains a link to 'broken-link.md'

This means you have a broken internal link. Fix the link or remove it.

Images Not Loading¶

Ensure images are in docs/ folder and use relative paths:

![Architecture](../assets/images/architecture.png)

Best Practices¶

1. Organize by Purpose¶

guides/ — Getting started, step-by-step tutorials
development/ — Development workflow, tooling, code quality
reference/ — API documentation, technical specs, feature references

2. Use Clear Titles¶

Good: # Testing Guide — pytest and Coverage Bad: # Testing

3. Add Metadata¶

At the top of each page, you can add metadata:

---
title: Testing Guide
description: How to run tests and check coverage
---

4. Link Between Pages¶

Use relative links to link between docs:

See the [Quickstart Guide](../guides/quickstart.md) for setup instructions.

Avoid deeply nested navigation (max 2-3 levels).

6. Test Before Committing¶

Always run mkdocs build before committing to catch broken links and errors:

uv run mkdocs build --strict

The --strict flag turns warnings into errors.

CI/CD Integration¶

GitHub Actions Workflow¶

The project includes automated documentation deployment. See .github/workflows/deploy-docs.yml:

name: Deploy Documentation

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - 'mkdocs.yml'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

Triggers¶

Documentation deploys automatically when:

You push to main
Changes are in docs/ folder or mkdocs.yml

Resources¶

MkDocs Documentation: https://www.mkdocs.org/
Material for MkDocs: https://squidfunk.github.io/mkdocs-material/
Markdown Guide: https://www.markdownguide.org/
Live Documentation: https://justakris.github.io/Trump-Rally-Speeches-NLP-Chatbot/

Summary¶

To work with docs:

Edit markdown files in docs/
Run uv run mkdocs serve --dev-addr localhost:8001 to preview
Commit and push to main
GitHub Actions deploys automatically

Need help? Open an issue on GitHub or check the MkDocs documentation.