Updating Documentation¶

This guide explains how to update the bytefreezer documentation.

Overview¶

Documentation is written in Markdown and built using MkDocs with the Material theme. The built docs are served as static files from the main UI application.

Directory Structure¶

bytefreezer/
├── docs/                      # Documentation source
│   ├── docs/                  # Markdown files
│   │   ├── index.md
│   │   ├── getting-started/
│   │   ├── deployment/
│   │   ├── user-guide/
│   │   ├── api/
│   │   └── contributing/
│   ├── mkdocs.yml            # MkDocs configuration
│   └── venv/                 # Python virtual environment
└── ui/
    ├── public/docs/          # Built documentation (generated)
    └── scripts/build-docs.sh # Build script

Updating Content¶

1. Edit Markdown Files¶

Edit files in /home/andrew/workspace/bytefreezer/docs/docs/:

# Example: Edit the getting started guide
vi docs/docs/getting-started/quick-start.md

2. Add New Pages¶

Create a new .md file in the appropriate directory:

# Example: Add a new guide
vi docs/docs/user-guide/new-feature.md

Then add it to the navigation in mkdocs.yml:

nav:
  - User Guide:
    - New Feature: user-guide/new-feature.md

3. Preview Changes (Optional)¶

Run the MkDocs development server to preview changes:

cd /home/andrew/workspace/bytefreezer/docs
./venv/bin/mkdocs serve -a 0.0.0.0:3001

View at http://localhost:3001

4. Build and Deploy¶

Run the build script to build and copy docs to the UI:

cd /home/andrew/workspace/bytefreezer/ui
./scripts/build-docs.sh

The script:

Builds MkDocs to static HTML
Copies output to ui/public/docs/
Docs are now available at /docs in the UI

Configuration¶

mkdocs.yml¶

Key configuration options:

site_name: bytefreezer
site_url: https://bytefreezer.com/docs/

theme:
  name: material
  palette:
    - scheme: slate      # Dark mode (default)
    - scheme: default    # Light mode

nav:
  - Home: index.md
  - Getting Started:
    - Overview: getting-started/index.md
    # Add new pages here

nav:
  - Section Name:
    - Page Title: path/to/page.md
    - Another Page: path/to/another.md

Markdown Features¶

MkDocs Material supports:

Admonitions¶

!!! note
    This is a note.

!!! warning
    This is a warning.

!!! tip
    This is a tip.

Code Blocks¶

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

Tables¶

| Column 1 | Column 2 |
|----------|----------|
| Value 1  | Value 2  |

Tabs¶

=== "Tab 1"
    Content for tab 1

=== "Tab 2"
    Content for tab 2

Deploying to Demo Site¶

After updating documentation, deploy to bytefreezer.com using AWX:

1. Build Docs¶

cd /home/andrew/workspace/bytefreezer/ui
./scripts/build-docs.sh

2. Commit Changes¶

cd /home/andrew/workspace/bytefreezer/ui
git add public/docs/
git commit -m "Update documentation"
git push

3. Build Docker Image¶

The UI Dockerfile includes public/docs/, so docs are bundled with the UI container.

# Build is typically done via CI or manually:
docker build -t bytefreezer/ui:latest .
docker push bytefreezer/ui:latest

4. Deploy via AWX¶

Log in to AWX
Navigate to Templates
Run "ByteFreezer UI - Deploy to k3s"
Playbook: kubernetes/deploy.yml
Wait for deployment to complete

5. Verify¶

Check the docs are live at https://bytefreezer.com/docs

Troubleshooting¶

Build Errors¶

If the build fails, check:

Python venv exists: ls docs/venv/
MkDocs installed: docs/venv/bin/mkdocs --version
Valid YAML in mkdocs.yml

Missing Pages¶

If a page returns 404:

Check the file exists in docs/docs/
Check it's listed in mkdocs.yml nav
Rebuild with ./scripts/build-docs.sh

Styles Not Loading¶

Check site_url in mkdocs.yml matches your deployment URL.