MkDocs deployment guide

This project uses MkDocs to publish the photography learning programme as a static site. The configuration is defined in mkdocs.yml, with source pages stored under docs/ and generated output written to site/.

Project configuration

The current MkDocs setup is intentionally simple:

  • Source content directory: docs/
  • Build output directory: site/
  • Theme: mkdocs
  • Navigation is managed in mkdocs.yml

The key settings are:

site_name: Photography Learning Programme
docs_dir: docs
site_dir: site
theme:
  name: mkdocs

Local setup

Create a virtual environment and install the site dependencies:

cd "C:\Users\vilmo\Documents\Photography"
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Local preview

Run the development server to preview changes live in the browser:

mkdocs serve

Then open the local URL reported by MkDocs, usually:

http://127.0.0.1:8000/

This is the best way to check formatting, links and navigation while editing content.

Production build

To build the static site without serving it locally:

mkdocs build

This generates the HTML files under site/ and validates that the Markdown pages render without errors.

Cloudflare Pages deployment

This project is deployed to Cloudflare Pages rather than GitHub Pages because GitHub Pages is only available for public repositories. Cloudflare Pages supports the same static output model and fits this private project setup.

Set the project to deploy from the repository root with these settings:

  • Framework preset: None
  • Build command:
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
mkdocs build
  • Build output directory: site

Cloudflare will build the site from the repository contents and publish the generated static files from site/.

Local validation before deployment

Before pushing changes to Cloudflare, validate the site locally:

mkdocs build --strict

This ensures the Markdown, navigation and configuration all render correctly before publication.

Cloudflare deployment workflow

  1. Push updates to the repository
  2. Cloudflare Pages triggers a new build
  3. Build command installs the Python dependency and runs MkDocs
  4. The generated site/ directory is published to the live site

Useful deployment checklist

  • Ensure requirements.txt includes the MkDocs version required by the project
  • Confirm all referenced Markdown files exist under docs/
  • Verify navigation entries in mkdocs.yml match actual file names
  • Check links after editing pages or moving files
  • Rebuild before publishing to catch broken references or invalid YAML
  • Keep the Cloudflare Pages build command aligned with the project setup

Troubleshooting

Broken navigation or missing pages

If a page does not appear or a link fails, verify:

  • The Markdown file exists in docs/
  • The path in mkdocs.yml matches the filename exactly
  • Any spaces or punctuation in file names are reflected correctly in the nav configuration

Site does not build

Run:

mkdocs build --strict

This catches config problems and broken page references more aggressively than the default build.

Notes for this repository

This project stores the learning programme as Markdown under docs/ and publishes a static site through Cloudflare Pages. GitHub Pages was not used because the project is kept private; Cloudflare provides the deployment path that matches the repository and hosting requirements.