LLM Outline For GitHub Refactor

1. Workflow Isolation & Coexistence Strategy

To develop, test, and distribute the GitHub-based version without altering your personal, offline workflow, apply a strict separation of concerns utilizing environment detection and file overrides.

                  ┌──────────────────────────────┐
                  │   Common build_site.py Core  │
                  └──────────────┬───────────────┘
                                 │
                 Is "config.local.yaml" present?
                                 │
                ┌────────────────┴────────────────┐
                ▼ YES                             ▼ NO
     [Personal Offline Mode]            [GitHub Public Mode]
     - Load absolute paths              - Load relative repository paths
     - Execute local WSL rsync          - Output to root-relative "./dist"
     - Run locally on host F:\          - Deployment handled by CI runner

2. GitHub-Based Template Repository Structure

The distributed public version must be packaged as a clean, standardized repository template that a non-technical user can clone or duplicate.

markdown-notes-template/
├── .github/
│   └── workflows/
│       └── deploy.yml          # GitHub Actions CI/CD deployment pipeline
├── src/                        # Input directory for user's Markdown files
│   ├── index.md                # Homepage of the notes site
│   └── navigation_menu.md      # Simplified markdown navigation source
├── assets/                     # Front-end design assets
│   ├── css/                    # Custom overrides & Pico.css
│   └── templates/              # Pandoc HTML layout templates
├── system/                     # Critical files hidden from typical user paths
│   ├── favicons/
│   ├── robots.txt
│   └── .htaccess               # Kept for standard Apache compatibility if needed
├── requirements.txt            # Python dependencies (e.g., PyYAML)
├── build_site.py               # Path-abstracted Python compiler script
└── config.yaml                 # Repository-relative configuration defaults

3. Pathing & Script Refactoring Plan

The code base in build_site.py requires restructuring to transition from host-specific configurations to environment-aware pathing.

import os
import yaml

# Determine repository root directory
REPO_ROOT = os.path.dirname(os.path.abspath(__file__))

# Determine which configuration file to load
local_config_path = os.path.join(REPO_ROOT, "config.local.yaml")
default_config_path = os.path.join(REPO_ROOT, "config.yaml")

if os.path.exists(local_config_path):
    with open(local_config_path, "r") as f:
        config = yaml.safe_load(f)
    print("Running in Local Personal Mode.")
else:
    with open(default_config_path, "r") as f:
        config = yaml.safe_load(f)
    print("Running in Public GitHub Mode.")

# Convert relative configuration paths to absolute paths at runtime
SRC_DIR = os.path.abspath(os.path.join(REPO_ROOT, config.get("src", "./src")))
DST_DIR = os.path.abspath(os.path.join(REPO_ROOT, config.get("dst", "./dist")))

def sync_to_server():
    # Only run if explicitly authorized by local configuration override
    if config.get("local_deploy_enabled", False):
        print("Executing local deployment commands...")
        # Invoke your existing WSL/rsync command logic here
    else:
        print("Skipping local deployment. Asset compilation complete.")

4. GitHub Actions CI/CD Pipeline

To remove the need for local execution, local Python configurations, Pandoc local binaries, and terminal commands for the end-user, create a GitHub Actions workflow file.

Save the following configuration inside .github/workflows/deploy.yml:

name: Deploy Markdown Site

on:
  push:
    branches:
      - main  # Runs on every push to the main branch

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

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build_and_deploy:
    environment:
      name: github-pages
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

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

      - name: Install Python Dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt

      - name: Install Pandoc
        uses: pandoc/actions/setup@v1
        with:
          version: '3.1.11' # Explicit stable version tag

      - name: Run Build Script
        run: python build_site.py

      - name: Index Site with Pagefind
        run: npx pagefind --site dist

      - name: Upload Pages Artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: dist

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

5. Implementation Roadmap for Dual Workflows

To execute this architectural shift successfully, complete the tasks in the following order:

1. Clean up scripts: Refactor your local build_site.py file to resolve paths dynamically relative to __file__ rather than using hardcoded D: or F: strings.
2. Isolate settings: Extract your personal folder locations and server synchronization settings into a new config.local.yaml file inside your development folder.
3. Verify Gitignore: Add config.local.yaml to your global or local .gitignore.
4. Confirm absolute offline functionality: Execute python build_site.py on your machine. Confirm that the script detects config.local.yaml, compiles your files, and executes the local WSL rsync step correctly.
5. Create the public repository: Create a clean, separate folder and initialize a new git repository (markdown-notes-template). Copy the refactored build_site.py and the base config.yaml (which uses ./src and ./dist) into this folder.
6. Add templates: Copy the .github/workflows/deploy.yml pipeline and standard default assets to the new public repository.
7. Test public execution: Run git push to trigger the GitHub Pages compilation. Confirm the public pipeline compiles and indexes using Pages, independent of your offline architecture.