Migrate to uv

.github/workflows/build-test.yaml

@@ -32,7 +32,7 @@ on:
     branches-ignore: [ master ]  # Run on all branches except master
 
 env:
-  PYTHON_VERSION: 3.x
+  PYTHON_VERSION: 3.14
 
 jobs:
   build:
@@ -44,20 +44,22 @@ jobs:
         with:
           fetch-depth: 1
 
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
       - name: Set up Python runtime
         uses: actions/setup-python@v5
         with:
           python-version: ${{ env.PYTHON_VERSION }}
-          cache: 'pip'
 
-      - name: Install Python dependencies
-        run: pip install -r requirements.txt
+      - name: Install dependencies
+        run: uv sync
 
       - name: Build Site
         env:
           GOOGLE_ANALYTICS_KEY: ${{ secrets.GOOGLE_ANALYTICS_KEY }}
         run: |
-          mkdocs build -f mkdocs.ci.yml
+          uv run mkdocs build -f mkdocs.ci.yml
           echo "Build completed successfully!"
 
       - name: Check build output

.github/workflows/ci.yaml

@@ -5,7 +5,7 @@ on:
     branches: [ master ]
 
 env:
-  PYTHON_VERSION: 3.x
+  PYTHON_VERSION: 3.14
 
 jobs:
   build:
@@ -17,19 +17,21 @@ jobs:
         with:
           fetch-depth: 0  # Required for git-revision-date-localized-plugin
 
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
       - name: Set up Python runtime
         uses: actions/setup-python@v5
         with:
           python-version: ${{ env.PYTHON_VERSION }}
-          cache: 'pip'  # This will cache pip dependencies
 
-      - name: Install Python dependencies
-        run: pip install -r requirements.txt
+      - name: Install dependencies
+        run: uv sync
 
       - name: Build Site
         env:
           GOOGLE_ANALYTICS_KEY: ${{ secrets.GOOGLE_ANALYTICS_KEY }}
-        run: mkdocs build -f mkdocs.ci.yml
+        run: uv run mkdocs build -f mkdocs.ci.yml
 
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v3

CLAUDE.md

@@ -15,21 +15,22 @@ Personal technical blog and knowledge base built with MkDocs Material theme, dep
 
 ### Initial Setup
 ```bash
-make install              # Creates .venv and installs dependencies from requirements.txt
-source .venv/bin/activate # Activate venv manually after install
+make install              # Installs dependencies with uv sync (creates .venv automatically)
 ```
 
 ### Development
 ```bash
-mkdocs serve              # Run local dev server at http://127.0.0.1:8000
+uv run mkdocs serve       # Run local dev server at http://127.0.0.1:8000
 make readme               # Regenerate README.md, docs/blog/index.md, and docs/blog/tags.md
 make tags                 # Regenerate only docs/blog/tags.md
 ```
 
+Note: No need to manually activate venv - use `uv run` prefix or Makefile targets.
+
 ### Build
 ```bash
-mkdocs build              # Build with mkdocs.yml (local config)
-mkdocs build -f mkdocs.ci.yml  # Build with CI config (includes production plugins)
+uv run mkdocs build              # Build with mkdocs.yml (local config)
+uv run mkdocs build -f mkdocs.ci.yml  # Build with CI config (includes production plugins)
 ```
 
 ### Cleanup
@@ -189,7 +190,8 @@ Optional floating thumbnail images displayed on the right side of content.
 ### Configuration
 - `mkdocs.yml` - Base MkDocs configuration
 - `mkdocs.ci.yml` - CI configuration (inherits base)
-- `requirements.txt` - Python dependencies
+- `pyproject.toml` - Python dependencies (managed by uv)
+- `uv.lock` - Dependency lock file (committed for reproducible builds)
 - `Makefile` - Development commands
 - `docs/assets/css/extra.css` - Custom CSS (includes thumbnail styling)
 

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help venv install clean serve readme tags
+.PHONY: help install clean serve readme tags
 
 all: help
 
@@ -8,11 +8,6 @@ WHITE  := $(shell tput -Txterm setaf 7)
 CYAN   := $(shell tput -Txterm setaf 6)
 RESET  := $(shell tput -Txterm sgr0)
 
-VENV = .venv
-ACTIVATE = $(VENV)/bin/activate
-PYTHON = $(VENV)/bin/python3
-PIP = $(VENV)/bin/pip3
-
 ## Help:
 
 help: ## Show this help
@@ -28,32 +23,24 @@ help: ## Show this help
 
 ## Local Setup:
 
-venv: ## Init virtual environment
-	@echo "Creating python virtual environment in '.venv' folder..."
-	@python3 -m venv .venv
-
-# !!! this does NOT work. Requires additional Makefile magic
-# activate: ## Activate local virtual environment
-# 	@eval $(echo ". .venv/bin/activate")
-
-install: venv ## Install dependecies
-	@echo "Installing python packages..."
-	@$(PIP) install -r requirements.txt
+install: ## Install dependencies and create venv
+	@echo "Installing dependencies with uv..."
+	@uv sync
 	@echo
-	@echo Run the following command to activate virtual environment:
-	@echo . .venv/bin/activate
+	@echo "✓ Dependencies installed in .venv/"
+	@echo "Note: No need to manually activate venv - use 'uv run' or Makefile targets"
 
-clean: ## Cleaning previous python virtual environment
-	@echo "Cleaning previous python virtual environment '.venv'..."
+clean: ## Remove .venv directory
+	@echo "Cleaning .venv..."
 	@rm -rf .venv
 
 ## Development environment:
 
 serve: ## Run mkdocs server
-	mkdocs serve --livereload
+	uv run mkdocs serve --livereload
 
 tags: ## Generate tags index
-	python3 scripts/generate-tags.py
+	uv run python scripts/generate-tags.py
 
 readme: tags ## Generate blog index and tags
-	python3 scripts/generate-blog-index.py
+	uv run python scripts/generate-blog-index.py

pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "mind-flow"
+version = "0.1.0"
+description = "Personal technical blog and knowledge base"
+requires-python = ">=3.14"
+dependencies = [
+    "click>=8.2.1,<8.3.0", # --- Bugfix: Pin Click to <8.3.0 due to livereload regression ---
+    "mkdocs-material>=9.6",
+    "mdx_truly_sane_lists>=1.3",
+    "mkdocs-awesome-pages-plugin>=2.10",
+    "mkdocs-git-revision-date-localized-plugin>=1.4",
+    "mkdocs-minify-plugin>=0.8",
+    "mkdocs-rss-plugin>=1.17",
+]