docs(site): scaffold MkDocs Material homepage

.github/workflows/docs.yml

@@ -0,0 +1,51 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment; cancel in-progress runs for the same ref.
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install MkDocs Material
+        run: pip install mkdocs-material
+
+      - name: Build site
+        run: mkdocs build --strict
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -32,6 +32,9 @@ temp/
 # Logs
 *.log
 
+# MkDocs build output
+site/
+
 # Local machine files
 *.local
 *.local.*

mkdocs.yml

@@ -0,0 +1,61 @@
+site_name: fnayou/dotfiles
+site_description: Personal dotfiles, terminal workflow, shell configuration and development environment.
+site_url: https://fnayou.github.io/dotfiles/
+repo_url: https://github.com/fnayou/dotfiles
+repo_name: fnayou/dotfiles
+
+docs_dir: website
+
+theme:
+  name: material
+  palette:
+    scheme: slate
+    primary: blue
+    accent: blue
+  features:
+    - navigation.sections
+    - navigation.expand
+    - navigation.top
+    - search.suggest
+    - search.highlight
+    - content.code.copy
+    - content.tabs.link
+
+extra_css:
+  - assets/stylesheets/catppuccin-macchiato.css
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+
+nav:
+  - Home: index.md
+  - Getting Started:
+      - Overview: getting-started.md
+      - Installation: installation.md
+      - Philosophy: philosophy.md
+  - Features:
+      - Overview: features/index.md
+      - Shell (Zsh): features/shell.md
+      - Git: features/git.md
+      - Terminal: features/terminal.md
+      - Editor (Neovim): features/editor.md
+      - Packages: features/packages.md
+      - Scripts: features/scripts.md
+  - Usage:
+      - Overview: usage/index.md
+      - Daily Workflow: usage/daily-workflow.md
+      - Aliases: usage/aliases.md
+      - Functions: usage/functions.md
+      - Taskfile: usage/taskfile.md
+  - Reference:
+      - Overview: reference/index.md
+      - Repository Structure: reference/repository-structure.md
+      - GNU Stow Workflow: reference/stow.md
+      - Shell Dependencies: reference/shell-dependencies.md
+      - Supported Systems: reference/supported-systems.md
+      - Troubleshooting: reference/troubleshooting.md
+  - Screenshots: screenshots.md

website/assets/stylesheets/catppuccin-macchiato.css

@@ -0,0 +1,52 @@
+/*
+ * Catppuccin Macchiato (Blue accent) — Material for MkDocs override.
+ * First-pass palette. Applies on the dark (slate) scheme.
+ * Palette reference: https://github.com/catppuccin/catppuccin
+ */
+
+[data-md-color-scheme="slate"] {
+  /* Base surfaces */
+  --md-default-bg-color:            #24273a; /* Base */
+  --md-default-fg-color:            #cad3f5; /* Text */
+  --md-default-fg-color--light:     #b8c0e0; /* Subtext1 */
+  --md-default-fg-color--lighter:   #a5adcb; /* Subtext0 */
+  --md-default-fg-color--lightest:  #6e738d; /* Overlay0 */
+
+  /* Primary / accent — Blue */
+  --md-primary-fg-color:            #8aadf4; /* Blue */
+  --md-primary-fg-color--light:     #91d7e3; /* Sky */
+  --md-primary-fg-color--dark:      #7dc4e4; /* Sapphire */
+  --md-primary-bg-color:            #1e2030; /* Mantle (text on primary) */
+  --md-primary-bg-color--light:     #cad3f5;
+
+  --md-accent-fg-color:             #8aadf4; /* Blue */
+  --md-accent-fg-color--transparent: rgba(138, 173, 244, 0.1);
+  --md-accent-bg-color:             #1e2030;
+
+  /* Code surfaces */
+  --md-code-bg-color:               #1e2030; /* Mantle */
+  --md-code-fg-color:               #cad3f5; /* Text */
+
+  /* Links */
+  --md-typeset-a-color:             #8aadf4; /* Blue */
+
+  /* Footer / header use Mantle for contrast against Base */
+  --md-footer-bg-color:             #1e2030;
+  --md-footer-bg-color--dark:       #181926; /* Crust */
+}
+
+/* Header bar — Mantle instead of full Blue for a calmer look */
+[data-md-color-scheme="slate"] .md-header {
+  background-color: #1e2030;
+  color: #cad3f5;
+}
+
+[data-md-color-scheme="slate"] .md-tabs {
+  background-color: #181926; /* Crust */
+}
+
+/* Inline code chips */
+[data-md-color-scheme="slate"] .md-typeset code {
+  background-color: #363a4f; /* Surface0 */
+  color: #cad3f5;
+}

website/features/editor.md

@@ -0,0 +1,58 @@
+# Editor (Neovim)
+
+The `stow/common/nvim/` package provides a [kickstart.nvim](https://github.com/nvim-lua/kickstart.nvim)-based
+Neovim configuration, themed Catppuccin Macchiato (blue accent `#8aadf4`) to match the rest of the
+terminal. It's meant to replace plain `vim` for quick local edits and server maintenance, while still
+being a full, learnable setup.
+
+Curated from `stow/common/nvim/README.md`. There is no separate setup guide for this package yet.
+
+![Neovim editing a file with the Catppuccin Macchiato colorscheme](../assets/images/nvim-editor.png)
+*Neovim editing inside the dotfiles repository.*
+
+## What it configures
+
+- Stock kickstart `init.lua`, kept close to upstream (LSP servers + treesitter languages edited).
+- Plugins managed by [lazy.nvim](https://github.com/folke/lazy.nvim), pinned via `lazy-lock.json`.
+- Feature files under `lua/custom/plugins/`: Catppuccin colorscheme, snacks picker, neo-tree file
+  explorer, flash jump motions, indent guides, and filetype scoping.
+
+Target path is `~/.config/nvim` (XDG), identical on macOS and Arch — only the system dependencies
+differ per platform.
+
+## Dependencies
+
+LSP servers are installed **inside** Neovim by [Mason](https://github.com/mason-org/mason.nvim)
+(`:Mason`), but they need runtimes and a few CLI tools on the system first — `neovim`, `ripgrep`,
+`fd`, `node`, `python` + `pipx`, a C compiler, and the `tree-sitter` CLI.
+
+Print the install commands (nothing installs automatically):
+
+```bash
+task deps:brew    # macOS
+task deps:arch    # Arch
+```
+
+!!! info "tree-sitter CLI"
+    nvim-treesitter builds parsers by shelling out to the `tree-sitter` binary. On macOS, Homebrew's
+    `tree-sitter` formula ships the library only, so install the CLI via `npm install -g tree-sitter-cli`.
+    Without it, parser builds fail with `ENOENT ... (cmd): 'tree-sitter'`. See the package README for
+    the full rationale.
+
+## Install
+
+This package uses the standard Stow workflow (no `--no-folding` needed):
+
+```bash
+stow --dir=stow/common --target="$HOME" --simulate nvim
+```
+
+⚠️  MANUAL STEP — review dry-run output before running
+
+```bash
+stow --dir=stow/common --target="$HOME" nvim
+```
+
+## Related
+
+- [Shell Dependencies](../reference/shell-dependencies.md) · [GNU Stow Workflow](../reference/stow.md)

website/features/git.md

@@ -0,0 +1,87 @@
+# Git
+
+The `stow/common/git/` package provides a portable Git configuration — settings, aliases, and a
+global ignore file — without touching your identity or any secrets.
+
+This page is curated from the repository's `docs/guides/git-setup.md`.
+
+## What it manages
+
+Three files, stowed into `~/.config/git/`:
+
+| File | Purpose |
+|---|---|
+| `config-common` | Portable settings — editor, colors, pull strategy, merge conflict style, diff options |
+| `aliases` | Git aliases — shorthand for common operations |
+| `ignore` | Global ignore patterns — OS artifacts, editor files, logs |
+
+!!! info "Your identity stays yours"
+    This package **never** manages `~/.gitconfig`. `user.name`, `user.email`, signing keys,
+    credentials, and any `[includeIf]` work config stay in your own `~/.gitconfig`. The managed files
+    are wired in via `[include]` entries — your existing config is preserved.
+
+## Install
+
+Verify prerequisites (`git`, `stow`, `task`):
+
+```bash
+task check
+```
+
+Dry-run (this package requires `--no-folding`):
+
+```bash
+task dry-run AREA=common PACKAGE=git
+# or directly:
+stow --dir=stow/common --target="$HOME" --no-folding --simulate git
+```
+
+Expect three `LINK:` lines and no conflicts. Then apply:
+
+⚠️  MANUAL STEP — review dry-run output before running
+
+```bash
+stow --dir=stow/common --target="$HOME" --no-folding git
+```
+
+## Wire it into `~/.gitconfig`
+
+Stowing only places the symlinks. A bootstrap task adds the `[include]` entries to `~/.gitconfig`.
+Preview first — it changes nothing:
+
+```bash
+task git:bootstrap:dry-run
+```
+
+Then apply:
+
+⚠️  MANUAL STEP — review dry-run output before running
+
+```bash
+task git:bootstrap
+```
+
+!!! note "Safe by construction"
+    `task git:bootstrap` creates a **timestamped backup** of `~/.gitconfig` before any change, and only
+    **appends** the include entries — it never removes or overwrites existing content. Running it a
+    second time detects the entries already present and skips them.
+
+Set your identity directly (never managed by this repository):
+
+⚠️  MANUAL STEP — replace placeholders with your own values
+
+```bash
+git config --global user.name "Your Name"
+git config --global user.email "your-email@example.com"
+```
+
+## Verify
+
+```bash
+git config --global --get-all include.path   # shows the two managed includes
+git config --global core.excludesfile        # ~/.config/git/ignore
+```
+
+## Related
+
+- [GNU Stow Workflow](../reference/stow.md) · [Installation](../installation.md)

website/features/index.md

@@ -0,0 +1,21 @@
+# Features
+
+What the repository configures, grouped by area. Each area maps to one or more Stow packages under
+`stow/common/`. Install them independently — none requires the others.
+
+| Area | Tools / packages | Page |
+|---|---|---|
+| **Shell** | Layered Zsh config (path, history, plugins, tools, prompt, per-OS layers) | [Shell](shell.md) |
+| **Git** | Portable config, aliases, global ignore (no secrets) | [Git](git.md) |
+| **Terminal** | Alacritty terminal, Herdr multiplexer | [Terminal](terminal.md) |
+| **Editor** | Neovim (Lua, Catppuccin Macchiato) | [Editor](editor.md) |
+| **Packages** | bat, eza, and the Claude Code status line | [Packages](packages.md) |
+| **Scripts** | Helper scripts, e.g. OS maintenance | [Scripts](scripts.md) |
+
+!!! note "One package per tool"
+    Everything here is a separate Stow package. You can stow the shell without git, git without
+    alacritty, and so on. See [Installation](../installation.md) for the dry-run-first workflow and
+    [GNU Stow Workflow](../reference/stow.md) for the mechanics.
+
+A shared thread across the visual tools (alacritty, bat, eza, oh-my-posh, neovim) is the
+**Catppuccin Macchiato** palette with a blue accent, so the terminal looks consistent across them.