Doc Site Improvements

[strawgate]

Our current doc sites has no nav bar, table of contents, etc. What can we do to make the docs easier to navigate while still leveraging github pages?

ex https://strawgate.com/py-key-value/stores.html

[claude]

Claude finished @strawgate's task —— View job

---

Documentation Improvements Investigation Complete ✓

tl;dr

The current MkDocs Material setup is missing key navigation features. Enable toc.integrate, toc.follow, navigation.tabs.sticky, and navigation.instant in your mkdocs.yml to add sidebar table of contents, sticky navigation tabs, and improved user experience while maintaining full GitHub Pages compatibility.

---

Recommendation

Add the following navigation features to your mkdocs.yml configuration:

theme:
  features:
    - navigation.tabs
    - navigation.tabs.sticky    # NEW: Keep tabs visible while scrolling
    - navigation.sections
    - navigation.expand
    - navigation.top
    - navigation.tracking
    - navigation.instant        # NEW: SPA-like navigation for faster page loads
    - toc.integrate            # NEW: Embed table of contents in left sidebar
    - toc.follow               # NEW: Auto-scroll sidebar to active section
    - search.suggest
    - search.highlight
    - content.code.copy
    - content.code.annotate

These changes will add:

• ✅ Persistent table of contents in the left sidebar (addresses your "no table of contents" concern)
• ✅ Sticky navigation tabs that stay visible while scrolling (addresses "no nav bar" concern)
• ✅ Automatic sidebar scrolling to keep the active section visible
• ✅ Instant page navigation for a smoother, faster browsing experience
• ✅ 100% GitHub Pages compatible - no additional infrastructure required

Findings

Current Configuration Analysis

What you have now:

• MkDocs with Material theme ✓
• Basic navigation tabs (navigation.tabs) ✓
• Navigation sections and expansion ✓
• GitHub Pages deployment workflow ✓

What's missing:

• ❌ Table of contents integration (toc.integrate) - TOC is not visible in sidebar
• ❌ Sticky tabs (navigation.tabs.sticky) - tabs disappear when scrolling
• ❌ TOC following (toc.follow) - sidebar doesn't scroll to active section
• ❌ Instant navigation (navigation.instant) - full page reloads on navigation

How Each Feature Helps

1. toc.integrate: Embeds the table of contents directly in the left sidebar navigation (for viewports >1220px). This gives users a persistent overview of the current page's structure.

2. toc.follow: Automatically scrolls the sidebar to keep the active section visible as users scroll through the page.

3. navigation.tabs.sticky: Makes the top navigation tabs "stick" below the header when scrolling, so users always have access to main navigation.

4. navigation.instant: Enables SPA-like behavior - pages load via XHR without full page reloads, making navigation faster and smoother.

Verified Compatibility

All recommended features are:

• ✅ Built into MkDocs Material (no plugins needed)
• ✅ Compatible with GitHub Pages
• ✅ Well-documented and stable
• ✅ Used by thousands of projects

Detailed Action Plan

Implementation Steps

1. Update mkdocs.yml (lines 25-34):

   # Add these four new features to the existing list:
   features:
     - navigation.tabs
     - navigation.tabs.sticky    # Add this line
     - navigation.sections
     - navigation.expand
     - navigation.top
     - navigation.tracking
     - navigation.instant        # Add this line
     - toc.integrate            # Add this line
     - toc.follow               # Add this line
     - search.suggest
     - search.highlight
     - content.code.copy
     - content.code.annotate

2. Test locally (recommended):

   uv run --extra docs mkdocs serve
   # Visit http://localhost:8000 to preview changes

3. Verify the changes:

   • Navigate to any documentation page
   • Confirm table of contents appears in left sidebar
   • Scroll down and verify navigation tabs stay visible
   • Check that sidebar auto-scrolls to active section
   • Test navigation between pages (should be instant)

4. Deploy:

   git add mkdocs.yml
   git commit -m "docs: enable TOC integration and sticky navigation tabs"
   git push

   The existing GitHub Actions workflow will automatically deploy to GitHub Pages.

Optional Enhancements

If you want even more navigation improvements:

• navigation.path: Shows breadcrumb navigation above page title
• navigation.indexes: Allows section overview pages (NOTE: incompatible with toc.integrate)
• navigation.footer: Adds prev/next page links at bottom

Related Issues and Pull Requests

Repository	Issue/PR	Relevance
strawgate/py-key-value	#124 - More detailed documentation	Implemented MkDocs with Material theme and mkdocstrings for API documentation
strawgate/py-key-value	#156 - Add GitHub Actions workflow for documentation deployment	Added the current docs deployment workflow
strawgate/py-key-value	#173 - GH Docs Pages dont render class info	Fixed mkdocstrings rendering issues
strawgate/py-key-value	#189 - Review docs links	Fixed missing documentation links

Related Files

Repository	File	Relevance	Sections
strawgate/py-key-value	mkdocs.yml	Main MkDocs configuration file that needs to be updated with new navigation features	25-34
strawgate/py-key-value	.github/workflows/docs.yml	GitHub Actions workflow that deploys documentation to GitHub Pages	1-36

Related Webpages

Name	URL	Relevance
Setting up navigation - Material for MkDocs	https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/	Official documentation for all navigation features, including toc.integrate, toc.follow, and navigation.tabs.sticky
Material for MkDocs	https://squidfunk.github.io/mkdocs-material/	Main documentation site for the Material theme used by this project

---

Problems Encountered During Investigation

None - all investigation tools and resources were accessible and provided comprehensive information.

---

[strawgate]

@claude make a pr

[claude]

Claude finished @strawgate's task —— View job • claude/issue-194-20251102-0006 • Create PR ➔

---

Implementing Documentation Navigation Improvements

Tasks

• Gather project context and understand repository structure
• Read current mkdocs.yml configuration
• Add recommended navigation features to mkdocs.yml
• Commit and push changes
• Provide PR creation link

---

Summary

I've successfully implemented the documentation navigation improvements by adding four new features to your mkdocs.yml configuration:

1. navigation.tabs.sticky - Keeps navigation tabs visible while scrolling
2. navigation.instant - Enables SPA-like navigation for faster page loads
3. toc.integrate - Embeds the table of contents in the left sidebar
4. toc.follow - Auto-scrolls sidebar to the active section

These changes address the navigation concerns raised in issue #194 by providing:

• ✅ Persistent table of contents in the sidebar
• ✅ Sticky navigation tabs that remain accessible while scrolling
• ✅ Automatic sidebar scrolling to track your position
• ✅ Faster page transitions with instant navigation

All features are built into MkDocs Material and fully compatible with GitHub Pages - no additional infrastructure required.

What Changed

File modified: mkdocs.yml (lines 25-38)

• Added 4 new feature flags to the existing configuration
• All other settings remain unchanged

---

•

[strawgate]

@claude it doesn't really look like that worked

[claude]

Claude finished @strawgate's task —— View job

---

Documentation Navigation Issue - Solution Found

Root Cause

The MkDocs configuration is correct and the documentation IS being built successfully with all the navigation features, but GitHub Pages is serving the wrong content.

The Problem:

• ✅ MkDocs builds with Material theme and deploys to the gh-pages branch
• ❌ GitHub Pages is configured to serve from /docs directory on main branch (legacy Jekyll)
• 🔍 Result: strawgate.com/py-key-value shows Jekyll-rendered pages instead of MkDocs

Evidence:

<meta name="generator" content="Jekyll v3.10.0" />

The deployed site is using Jekyll, not the MkDocs Material theme with your navigation features.

---

Solution

I've identified the fix but encountered a permission issue - I cannot modify workflow files due to GitHub App restrictions. Here's what needs to be done:

Option 1: Update GitHub Pages Settings (Simplest)

Manually change the GitHub Pages source in repository settings:

1. Go to Settings → Pages
2. Under "Build and deployment" → "Source"
3. Change from "Deploy from a branch: main /docs"
4. To "GitHub Actions"

This will make GitHub Pages serve the MkDocs-built content that's already being generated.

Option 2: Update the Workflow (Recommended)

Update .github/workflows/docs.yml to use GitHub's official Pages deployment action. This automatically configures Pages to use GitHub Actions as the source.

Click to see the updated workflow file

name: Deploy Documentation

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.10'

      - name: Install uv
        uses: astral-sh/setup-uv@v5
        with:
          enable-cache: true

      - name: Install all packages and dependencies
        run: uv sync --all-packages --group dev

      - name: Build documentation
        run: uv run --extra docs mkdocs build

      - name: Setup Pages
        uses: actions/configure-pages@v5

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: './site'

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Key changes:

• Split into separate build and deploy jobs
• Use actions/configure-pages, upload-pages-artifact, and deploy-pages
• Updated permissions for Pages deployment
• This automatically configures GitHub Pages to use GitHub Actions

---

Why This Happened

The docs workflow has been successfully building and deploying MkDocs to the gh-pages branch, but GitHub Pages was still configured to serve from the old location (main:/docs), which contains markdown files that GitHub Pages renders with Jekyll.

Once you apply either solution, the MkDocs Material site with all the navigation features will be properly displayed.

---

Problems Encountered

• Workflow modification blocked: GitHub App does not have workflows permission, preventing me from updating .github/workflows/docs.yml directly. This is a security restriction to prevent unauthorized workflow modifications.

---

• claude/issue-194-20251102-1827