Skip to content

Usage Guide

This guide provides instructions on how to start the mkdocs site for testing and how to integrate it into GitHub Pages.

Starting the mkdocs Site for Testing

  1. Install Dependencies: Ensure you have uv installed. If not, install it using the following command: 

    curl -sSL https://astral.sh/uv/install.sh | sh

  2. Initialize the Project: Navigate to the project directory and initialize the project: 

    uv init

  3. Install Dependencies: Install the required dependencies: 

    uv add -D

  4. Serve the mkdocs Site: Start the mkdocs development server: 

    uv run mkdocs serve

  5. Access the Site: Open your web browser and navigate to http://127.0.0.1:8000 to view the documentation site.

Integrating the mkdocs Site into GitHub Pages

  1. Build the Site: Build the mkdocs site to generate the static files: 

    uv run mkdocs build

  2. Deploy to GitHub Pages: Deploy the generated site to GitHub Pages. You can use the ghp-import tool to do this: 

    uv run ghp-import -n -p -f site

  3. Configure GitHub Pages: Go to your GitHub repository settings, navigate to the "Pages" section, and configure the source to use the gh-pages branch.

  4. Custom Domain (Optional): If you have a custom domain, add it to the CNAME file in the docs directory. For example: 

    your.custom.domain

  5. Verify Deployment: After deployment, verify that your site is live by navigating to your GitHub Pages URL or your custom domain.

Custom Theme

To create a beautiful and elegant custom theme, you can add custom CSS to the docs/theme directory. For example, create a custom_theme.css file with your custom styles and reference it in the mkdocs.yml file: 

theme:
  name: material
  custom_dir: docs/theme
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: "indigo"
      accent: "indigo"
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: "indigo"
      accent: "indigo"
  font:
    text: "Roboto"
    code: "Roboto Mono"
  features:
    - navigation.tabs
    - navigation.top
    - toc.integrate
    - content.code.annotate
    - content.code.copy
    - content.code.expand
    - content.code.tabs
    - content.tabs.link
    - search.suggest
    - search.highlight
    - search.share
  extra_css:
    - custom_theme.css

Add your custom styles to the custom_theme.css file to give your documentation a distinct and elegant feel.