mkdocs.yml

site_name: daviddwlee84/dotfiles
site_description: Documentation for daviddwlee84/dotfiles
site_url: https://daviddwlee84.github.io/dotfiles/
repo_url: https://github.com/daviddwlee84/dotfiles
repo_name: daviddwlee84/dotfiles
edit_uri: edit/main/docs/
# Docs under `docs/` often link to sibling *source* files in the repo
# (dot_config/..., pitfalls/..., backlog/...) with relative `../../..` paths.
# Those render correctly on GitHub but MkDocs can't resolve them into site
# pages. Downgrade to INFO so --strict still catches genuinely broken
# internal links / missing anchors / etc.
validation:
  links:
    not_found: info
    # TODO (backlog/mkdocs-anchor-drift.md): raise to `warn` once the ~20
    # existing stale section-anchor links in tools/worktrunk.md, tools/sesh.md,
    # zsh/aliases.md, tools/tmux/README.md, tools/pre-commit.md are fixed.
    anchors: info
theme:
  name: material
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  features:
    - navigation.sections
    - navigation.expand
    - navigation.top
    - navigation.indexes
    - search.suggest
    - search.highlight
    - search.share
    - content.code.copy
    - content.code.annotate
    - toc.follow
  language: en
plugins:
  # Social cards: generates a per-page OG/Twitter preview image and injects
  # og:* / twitter:* meta so links unfurl as rich cards (Discord/Slack/X).
  # Requires the [imaging] extra (cairosvg/pillow) + system cairo/pango —
  # see pyproject.toml `docs` extra and the CI social-cards apt step.
  - social:
      cards_layout_options:
        background_color: "#3f51b5" # Material indigo 500, matches theme.palette
        # Noto Sans TC covers Latin + Traditional-Chinese (79 zh-TW page
        # titles) + → / fullwidth punctuation. Roboto/Noto Sans (Latin-only)
        # render CJK and → as tofu boxes. Do NOT switch to a Latin-only family.
        font_family: Noto Sans TC
  - i18n:
      docs_structure: suffix
      fallback_to_default: true
      reconfigure_material: true
      reconfigure_search: true
      languages:
        - locale: en
          name: English
          default: true
        - locale: zh-TW
          name: 繁體中文 (zh-TW)
          nav_translations:
            # Top-level sections
            Home: 首頁
            Playbooks: 工作流程
            Tools: 工具
            "System admin": 系統管理
            Repo Internals: 本 Repo 內部
            Infrastructure: 基礎建設
            Tutorials: 教學
            Input methods: 輸入法
            Misc: 雜項
            For Maintainers: 給維護者
            # System admin subsections / leaves
            Overview (audit hierarchy): 概觀（審計層級）
            Sessions and login (Level 0): Session 與登入 (Level 0)
            sudo auditing (Level 1): sudo 審計 (Level 1)
            Process accounting (Level 2): Process accounting (Level 2)
            auditd framework (Level 3): auditd 框架 (Level 3)
            Firewall and network exposure: Firewall 與網路曝險面
            "Scheduled jobs (cron / timers / launchd)": "排程任務（cron / timer / launchd）"
            Disk / filesystem monitoring: Disk / filesystem 監控
            Hardware monitoring (homelab): 硬體監控（homelab）
            Service health: Service health
            Atuin vs audit: Atuin vs audit
            Cookbook (scenario recipes): Cookbook（場景食譜）
            Helpers in this repo: 本 repo 提供的 helper
            auditd role (opt-in): auditd role（可選）
            Wi-Fi latency spikes: Wi-Fi 延遲尖刺
            # Tools subsections
            "Shell & terminal": Shell 與終端機
            "Sessions & worktrees": Session 與 worktree
            "Editor & agents": 編輯器與 agent
            "Git & DevOps": Git 與 DevOps
            Productivity: 生產力
            chezmoi conventions: chezmoi 慣例
            # Repo Internals subsections
            Initial setup: 初次設定
            # Tools / leaf entries (titles defined in nav)
            Workflow (sesh + worktrunk + tmux): 開發工作流程 (sesh + worktrunk + tmux)
            Linux GUI apps (.deb / Snap / AppImage): Linux GUI 應用程式 (.deb / Snap / AppImage)
            Inline AI suggestions (aisuggest): 行內 AI 建議 (aisuggest)
            Overview: 概觀
            Keybindings: 鍵位
            Themes: 主題
            Vim integration: Vim 整合
            Clipboard: 剪貼簿
            Television (tv): Television (tv)
            btop (system monitor): btop (系統監控)
            TV vs fzf: TV vs fzf
            Glow (markdown reader): Glow (Markdown 閱讀器)
            Gum (shell prompts): Gum (shell prompt 工具箱)
            VHS (terminal demo recorder): VHS (終端機示範錄影器)
            Freeze (code → image): Freeze (程式碼 → 圖片)
            ffmpeg (audio / video toolkit): ffmpeg (音訊 / 影片工具箱)
            ImageMagick (image swiss army knife): ImageMagick (圖片瑞士刀)
            ExifTool (image / video metadata): ExifTool (圖片 / 影片 metadata)
            libvips (high-throughput image processing): libvips (高吞吐圖片處理)
            SSH agent: SSH agent
            Agent overlays (Claude/OpenCode/Codex/Cursor): Agent overlays (Claude/OpenCode/Codex/Cursor)
            Agent pane discovery (tv agent-panes + recon): Agent pane 探索 (tv agent-panes + recon)
            Agent skills: Agent skills
            Claude Code keybindings: Claude Code 鍵位
            Language servers (LSP): 語言伺服器 (LSP)
            SpecStory internals: SpecStory 內部運作
            git diff workflow: git diff 工作流程
            lazygit (history-surgery recipes): lazygit（歷史手術速查表）
            GitHub CLI (gh) auth: GitHub CLI (gh) 認證
            actionlint (GitHub Actions linter): actionlint（GitHub Actions 檢查器）
            Infrastructure-as-Code: Infrastructure-as-Code
            Containers: 容器
            Container config map: 容器設定對應
            Networking: 網路
            Services: 服務
            "Tunnels (ngrok / cloudflared)": Tunnels（ngrok / cloudflared）
            dotnet tools: dotnet 工具
            td / sidecar: td / sidecar
            Web reader: 網頁讀取器
            Log tools: Log 工具
            SMS (Huawei router): 簡訊 (Huawei 路由器)
            reyee (Ruijie router): reyee (Ruijie 路由器)
            ping-monitor (latency spikes): ping-monitor (延遲尖刺)
            yth (YouTube history): yth (YouTube 觀看歷史)
            chezmoi prefixes: chezmoi prefixes
            chezmoi templating: chezmoi templating
            Mirrors (Chinese CDN): 鏡像 (中國 CDN)
            # Zsh / Neovim leaves
            "Aliases & functions": 別名與函式
            Completions: 補全
            Floating TUI: 浮動 TUI
            "Copy reference (@file:line)": "複製檔案 reference (@file:line)"
            # Repo Internals leaves
            Architecture: 架構
            "POSIX, sh, bash, zsh: what's portable": "POSIX、sh、bash、zsh：什麼可攜"
            Cheatsheet: 備忘錄
            Bootstrap (curl|sh): Bootstrap (curl|sh)
            Ansible customization: Ansible 客製化
            Upgrades: 升級
            "Tool managers (who installs what)": "工具管理器（誰安裝什麼）"
            Testing: 測試
            Sudo session: Sudo session
            Vim mode (catalog + opt-out): Vim 模式（總覽與停用）
            Fleet apply: Fleet apply
            fleet-apply vs fabric: fleet-apply vs fabric
            chezmoiscripts layout: chezmoiscripts 佈局
            Instant-LLM-fix prior art: Instant-LLM-fix 前作
            Manual setup record: 手動設定紀錄
            Apply to new machine: 套用到新機器
            # Infrastructure leaves
            Virtualization: 虛擬化
            Compute scheduling: 運算排程
            Shared storage: 共享儲存
            Shared home / identity: 共享 home / 身份
            # Tutorials leaves
            Bitwarden SSH agent: Bitwarden SSH agent
            Setup SSH key on remote: 在遠端設定 SSH 金鑰
            # Input methods leaves
            macOS system switching: macOS 系統層切換
            # Misc leaves
            GLIBC and musl (binary compat): GLIBC 與 musl (二進制相容性)
            Keyboard shortcuts (global): 鍵盤快捷鍵 (全域)
            Linux package sources: Linux 套件來源
            Locale: Locale
  - search
  - llmstxt:
      full_output: llms-full.txt
      markdown_description: >
        Cross-platform dotfiles (chezmoi + ansible) tuned for coding-agent workflows on macOS / Ubuntu. Covers tmux, zsh, OSC 133 shell integration, aicapture (aifix / aiexplain / aiblock), sesh, fleet-apply.

      sections:
        Landing:
          - index.md
        Tools:
          - tools/aicapture.md
          - tools/ai-agents-benchmark.md
          - tools/zsh-inline-ai.md
          - tools/tmux/README.md
          - tools/sesh.md
          - tools/clipboard.md
          - tools/agent-overlays.md
        Playbooks:
          - playbooks/workflow.md
        Repo internals:
          - this_repo/architecture.md
          - this_repo/fleet-apply.md
          - this_repo/instant-llm-fix-prior-art.md
  - copy-to-llm:
      repo_url: "https://daviddwlee84.github.io/dotfiles/"
      button_hover_color: "var(--md-primary-fg-color)"
      toast_bg_color: "var(--md-primary-fg-color)"
extra_css:
  - assets/copy-to-llm/copy-to-llm.css
  - assets/copy-to-llm/copy-to-llm-custom.css
extra_javascript:
  - assets/copy-to-llm/copy-to-llm.js
markdown_extensions:
  - admonition
  - attr_list
  - def_list
  - footnotes
  - tables
  - md_in_html
  - toc:
      permalink: true
      # Preserve Unicode in heading slugs so zh-TW headings get readable
      # anchors like `#冷啟動消除` instead of `_7` / `_8` numeric fallbacks.
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets:
      base_path:
        - .
        - docs
        - docs/_snippets
      check_paths: true
  - pymdownx.tabbed:
      alternate_style: true
nav:
  - Home: index.md
  - Playbooks:
      - Workflow (sesh + worktrunk + tmux): playbooks/workflow.md
      - Linux GUI apps (.deb / Snap / AppImage): playbooks/linux-gui-apps.md
      - niri compositor (opt-in): playbooks/niri.md
      - auditd role (opt-in): playbooks/auditd.md
      - mDNS / Bonjour diagnostics: playbooks/mdns-diagnostics.md
      - Wi-Fi latency spikes: playbooks/wifi-latency-spikes.md
  - Tools:
      - tools/aicapture.md
      - AI agent benchmark (Haiku/OpenRouter/Ollama): tools/ai-agents-benchmark.md
      - Inline AI suggestions (aisuggest): tools/zsh-inline-ai.md
      - tmux:
          - Overview: tools/tmux/README.md
          - Keybindings: tools/tmux/keybindings.md
          - Themes: tools/tmux/themes.md
          - Vim integration: tools/tmux/vim.md
      - herdr (tmux alternative, trial): tools/herdr.md
      - Shell & terminal:
          - Ghostty: tools/ghostty.md
          - Warp: tools/warp.md
          - Starship: tools/starship.md
          - Clipboard: tools/clipboard.md
          - System audio & media control (sys*): tools/media-control.md
          - XDG: tools/xdg.md
          - Fzf: tools/fzf.md
          - Atuin (shell history): tools/atuin.md
          - btop (system monitor): tools/btop.md
          - Television (tv): tools/tv.md
          - TV vs fzf: tools/tv-vs-fzf.md
          - Glow (markdown reader): tools/glow.md
          - Gum (shell prompts): tools/gum.md
          - VHS (terminal demo recorder): tools/vhs.md
          - Freeze (code → image): tools/freeze.md
          - ffmpeg (audio / video toolkit): tools/ffmpeg.md
          - ImageMagick (image swiss army knife): tools/imagemagick.md
          - ExifTool (image / video metadata): tools/exiftool.md
          - libvips (high-throughput image processing): tools/libvips.md
      - Sessions & worktrees:
          - Sesh: tools/sesh.md
          - Worktrunk: tools/worktrunk.md
          - Workmux: tools/workmux.md
          - SSH agent: tools/ssh-agent.md
      - Editor & agents:
          - Agent overlays (Claude/OpenCode/Codex/Cursor): tools/agent-overlays.md
          - Agent pane discovery (tv agent-panes + recon): tools/agent-panes-discovery.md
          - Agent quota warmup (agent-warmup): tools/agent-warmup.md
          - Agent skills: tools/agent-skills.md
          - Claude Code keybindings: tools/claude-code-keybindings.md
          - Copilot → Claude Code proxy: tools/copilot-claude-proxy.md
          - Language servers (LSP): tools/lsp.md
          - OpenCode: tools/opencode.md
          - specify-cli: tools/specify_cli.md
          - SpecStory: tools/specstory.md
          - SpecStory internals: tools/specstory-internals.md
          - Codexbar: tools/codexbar.md
          - LLM: tools/llm.md
      - Git & DevOps:
          - git diff workflow: tools/git_diff_workflow.md
          - lazygit (history-surgery recipes): tools/lazygit.md
          - GitHub CLI (gh) auth: tools/gh-cli.md
          - pre-commit: tools/pre-commit.md
          - actionlint (GitHub Actions linter): tools/actionlint.md
          - Infrastructure-as-Code: tools/infrastructure-as-code.md
          - Containers: tools/containers.md
          - Container config map: tools/container-config-map.md
          - AppImage: tools/appimage.md
          - Networking: tools/networking.md
          - Services: tools/services.md
          - Tailscale: tools/Tailscale.md
          - Tunnels (ngrok / cloudflared): tools/tunnels.md
          - dotnet tools: tools/dotnet-tools.md
      - Productivity:
          - td / sidecar: tools/td_sidecar.md
          - Super Productivity: tools/super-productivity.md
          - Web reader: tools/web-reader.md
          - Log tools: tools/log-tools.md
          - Notebooks (Jupyter / Marimo / kernels): tools/notebooks.md
          - SMS (Huawei router): tools/sms.md
          - mi-router (Xiaomi router): tools/mi-router.md
          - reyee (Ruijie router): tools/reyee.md
          - ping-monitor (latency spikes): tools/ping-monitor.md
          - "Pueue (pqsum + fleet pueue)": tools/pueue.md
          - "fleet exec": tools/fleet-exec.md
          - "fleet hosts": tools/fleet-hosts.md
          - "yth (YouTube history)": tools/yth.md
          - direnv: tools/direnv.md
          - macOS swap & memory: tools/macos-swap.md
      - chezmoi conventions:
          - chezmoi prefixes: tools/chezmoi-prefixes.md
          - chezmoi templating: tools/chezmoi-templating.md
          - JSON Schema: tools/json-schema.md
          - Mirrors (Chinese CDN): tools/mirrors.md
  - System admin:
      - Overview (audit hierarchy): sysadmin/README.md
      - Sessions and login (Level 0): sysadmin/sessions.md
      - sudo auditing (Level 1): sysadmin/sudo-audit.md
      - Process accounting (Level 2): sysadmin/process-accounting.md
      - auditd framework (Level 3): sysadmin/auditd.md
      - Firewall and network exposure: sysadmin/firewall.md
      - Scheduled jobs (cron / timers / launchd): sysadmin/scheduled-jobs.md
      - Disk / filesystem monitoring: sysadmin/disk.md
      - Hardware monitoring (homelab): sysadmin/hardware.md
      - Service health: sysadmin/services-health.md
      - Atuin vs audit: sysadmin/atuin-vs-audit.md
      - Cookbook (scenario recipes): sysadmin/cookbook.md
      - Helpers in this repo: sysadmin/helpers.md
  - Shells:
      - "Adhoc & secrets (user-local override layer)": shells/adhoc-and-secrets.md
      - Architecture (3-tier shell/zsh/bash + future fish/powershell): shells/architecture.md
      - "POSIX, sh, bash, zsh: what's portable": shells/posix.md
      - Bash bootstrap (oh-my-bash + ble.sh): shells/bash.md
      - "Xonsh (experimental tertiary Python-shell)": shells/xonsh.md
      - Aliases & functions (zsh/bash): shells/aliases.md
      - "History (bash, zsh, atuin overview, multi-user audit)": shells/history.md
      - Keybindings & keys-picker: shells/keybindings.md
      - "Emacs-style line editing: origin & must-know subset": shells/emacs-line-editing.md
  - Zsh:
      - Completions: zsh/zsh-completions.md
      - "Plugins (oh-my-zsh + custom + UX upgrades evaluated)": zsh/oh-my-zsh-plugins.md
      - SSH login banner (MOTD): zsh/motd.md
  - Neovim:
      - Floating TUI: neovim/floating-tui.md
      - "Copy reference (@file:line)": neovim/copy-reference.md
  - Repo Internals:
      - Architecture: this_repo/architecture.md
      - Config file conventions (XDG, .d/, override layers): this_repo/config-conventions.md
      - Cheatsheet: this_repo/cheatsheet.md
      - Bootstrap (curl|sh): this_repo/bootstrap.md
      - Ansible customization: this_repo/ansible_customization.md
      - Upgrades: this_repo/upgrades.md
      - "Tool managers (who installs what)": this_repo/tool-managers.md
      - uv bootstrap & per-machine upgrade dispatch: this_repo/uv-bootstrap.md
      - Testing: this_repo/testing.md
      - Sudo session: this_repo/sudo-session.md
      - Vim mode (catalog + opt-out): this_repo/vim-mode.md
      - Fleet apply: this_repo/fleet-apply.md
      - fleet-apply vs fabric: this_repo/fleet-apply-vs-fabric.md
      - Azure dev VM (az-dev-vm): this_repo/az-dev-vm.md
      - chezmoiscripts layout: this_repo/chezmoiscripts-layout.md
      - Instant-LLM-fix prior art: this_repo/instant-llm-fix-prior-art.md
      - Initial setup:
          - Manual setup record: this_repo/initial_setup/0_ManualSetupRecord.md
          - Apply to new machine: this_repo/initial_setup/1_ApplyToNewMachine.md
      - Scripts:
          - import_ssh_to_bw.sh: this_repo/scripts/import_ssh_to_bw.sh.md
  - Infrastructure:
      - Overview: infra/README.md
      - Linux toolchain baseline (glibc / libstdc++ / kernel / gcc): infra/linux-toolchain-baseline.md
      - RHEL ecosystem & CentOS migration: infra/rhel-ecosystem.md
      - Debian ecosystem (Debian / Ubuntu / Raspberry Pi OS): infra/debian-ecosystem.md
      - Virtualization: infra/virtualization.md
      - Compute scheduling: infra/compute-scheduling.md
      - Shared storage: infra/shared-storage.md
      - Shared home / identity: infra/shared-home-identity.md
  - Tutorials:
      - Bitwarden SSH agent: tutorials/bitwarden_ssh_agent.md
      - Setup SSH key on remote: tutorials/setup_ssh_key_on_remote.md
  - Input methods:
      - Overview: input_methods/README.md
      - macOS system switching: input_methods/macos-system-switching.md
  - Misc:
      - GLIBC and musl (binary compat): glibc-and-musl.md
      - Keyboard shortcuts (global): keyboard-shortcuts.md
      - Linux package sources: linux-package-sources.md
      - Locale: locale.md
  - For Maintainers: for-maintainers.md
extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/daviddwlee84/dotfiles
# `_snippets/` are meant to be included via pymdownx.snippets, never
# rendered as their own page. `not_in_nav` suppresses the INFO warning.
not_in_nav: |
  /_snippets/