feat(tf/ot): New pages style guide and useful commands

.markdownlint.yaml

@@ -2,7 +2,7 @@
 # https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
 default: true
 
-# Line length — match other linters at 120, ignore code blocks/tables.
+# Line length: match other linters at 120, ignore code blocks/tables.
 MD013:
   line_length: 120
   code_blocks: false

Makefile

@@ -1,4 +1,4 @@
-# boilplate — local dev convenience targets
+# boilplate: local dev convenience targets
 # Run `make help` to see what's available.
 #
 # All Python work is done through `uv`, which manages the .venv automatically.

README.md

@@ -1,6 +1,6 @@
 # boilplate
 
-A personal stash of copy-paste-ready snippets for things I keep rewriting —
+A personal stash of copy-paste-ready snippets for things I keep rewriting:
 Terraform/Terragrunt, GitHub Actions, containers, Kubernetes, Postgres, and so
 on. Built primarily for me, but published in case anyone else finds bits of it
 useful:
@@ -22,7 +22,7 @@ useful:
 | `.pre-commit-config.yaml`    | [pre-commit](https://pre-commit.com/) hooks (hygiene + `zensical build` + lychee).                             |
 | `lychee.toml`                | [lychee](https://lychee.cli.rs/) link-checker config (used by pre-commit and CI).                              |
 | `.editorconfig`              | Whitespace defaults across editors.                                                                            |
-| `Makefile`                   | Convenience targets — run `make help`.                                                                         |
+| `Makefile`                   | Convenience targets: run `make help`.                                                                         |
 | `terragrunt/`                | Legacy Terragrunt example. Modern patterns live in [`docs/terraform/terragrunt/`](docs/terraform/terragrunt/). |
 | `.github/workflows/`         | `ci.yml` (PR checks), `deploy.yml` (Pages deploy on push to `main`), `links.yml` (lychee on PR + weekly cron). |
 
@@ -33,7 +33,7 @@ manages Python versions and the virtual env). Everything else goes through the
 Makefile:
 
 ```sh
-make install      # uv sync — create .venv and install deps
+make install      # uv sync: create .venv and install deps
 make hooks        # install pre-commit git hooks (one-time)
 make serve        # live-reload dev server at http://localhost:8000
 make build        # build site into ./site
@@ -58,7 +58,7 @@ One-time setup in the repo settings:
 
 1. Add a Markdown file under `docs/<topic>/`.
 2. Reference it in the `nav` block in [`zensical.toml`](zensical.toml).
-3. Add front-matter, including `tags:` (block-style YAML — flow-style
+3. Add front-matter, including `tags:` (block-style YAML: flow-style
    `[a, b]` collides with Zensical's reference-link parser):
 
    ```yaml

docs/api/pagination.md

@@ -1,12 +1,12 @@
 ---
-title: Pagination — cursor vs offset
+title: Pagination: cursor vs offset
 description: Cursor and offset pagination patterns for REST APIs.
 status: stub
 tags:
   - api
 ---
 
-# Pagination — cursor vs offset
+# Pagination: cursor vs offset
 
 !!! note "Stub page"
     When to use which, with copy-paste implementations.

docs/assets/external-links.js

@@ -14,7 +14,7 @@
           a.target = '_blank';
           a.rel = 'noopener noreferrer';
         }
-      } catch (_) { /* malformed URL — ignore */ }
+      } catch (_) { /* malformed URL: ignore */ }
     });
   }
 

docs/assets/extra.css

@@ -1,5 +1,5 @@
 /* ==========================================================================
-   boilplate — muted dark-grey + sage-green palette
+   boilplate: muted dark-grey + sage-green palette
    ========================================================================== */
 
 /* Brand greens */
@@ -17,7 +17,7 @@
 }
 
 /* --------------------------------------------------------------------------
-   Light mode — warm off-white with sage accents
+   Light mode: warm off-white with sage accents
    -------------------------------------------------------------------------- */
 [data-md-color-scheme="default"] {
   --md-primary-fg-color:        var(--bp-green-500);
@@ -44,7 +44,7 @@
 }
 
 /* --------------------------------------------------------------------------
-   Dark mode — warm dark grey with sage accents
+   Dark mode: warm dark grey with sage accents
    -------------------------------------------------------------------------- */
 [data-md-color-scheme="slate"] {
   --md-hue: 200;
@@ -77,7 +77,7 @@
 }
 
 /* --------------------------------------------------------------------------
-   Header polish — solid muted bar in dark mode (no harsh primary stripe)
+   Header polish: solid muted bar in dark mode (no harsh primary stripe)
    -------------------------------------------------------------------------- */
 [data-md-color-scheme="slate"] .md-header {
   background-color: #1a1d20;
@@ -114,7 +114,7 @@
 [data-md-color-scheme="default"] .md-tabs__link--active { color: var(--bp-green-600); }
 
 /* --------------------------------------------------------------------------
-   Code blocks — slightly inset, subtle border, monospaced clarity
+   Code blocks: slightly inset, subtle border, monospaced clarity
    -------------------------------------------------------------------------- */
 .md-typeset pre > code,
 .md-typeset .highlight pre {
@@ -138,7 +138,7 @@
   padding: 0.1em 0.35em;
 }
 
-/* Copy button — subtler */
+/* Copy button: subtler */
 .md-clipboard {
   color: var(--md-default-fg-color--lighter);
 }
@@ -164,7 +164,7 @@
   padding-bottom: 0.3em;
 }
 
-/* Links — accent on hover */
+/* Links: accent on hover */
 .md-typeset a {
   text-decoration: none;
   border-bottom: 1px solid transparent;
@@ -176,7 +176,7 @@
 }
 
 /* --------------------------------------------------------------------------
-   Admonitions / callouts — quieter colors that fit the palette
+   Admonitions / callouts: quieter colors that fit the palette
    -------------------------------------------------------------------------- */
 [data-md-color-scheme="slate"] .md-typeset .admonition,
 [data-md-color-scheme="slate"] .md-typeset details {
@@ -191,7 +191,7 @@
 }
 
 /* --------------------------------------------------------------------------
-   Tables — calmer, no zebra fight with the bg
+   Tables: calmer, no zebra fight with the bg
    -------------------------------------------------------------------------- */
 .md-typeset table:not([class]) {
   border: 1px solid var(--md-default-fg-color--lightest);
@@ -204,7 +204,7 @@
 }
 
 /* --------------------------------------------------------------------------
-   Search box — no harsh primary background
+   Search box: no harsh primary background
    -------------------------------------------------------------------------- */
 [data-md-color-scheme="slate"] .md-search__form {
   background-color: #22262a;
@@ -220,7 +220,15 @@
 }
 
 /* --------------------------------------------------------------------------
-   Footer — muted, no jarring color block
+   Page tags: breathing room above the tag chips so they don't butt up
+   against the article content.
+   -------------------------------------------------------------------------- */
+nav.md-tags {
+  margin-top: 2.5rem;
+}
+
+/* --------------------------------------------------------------------------
+   Footer: muted, no jarring color block
    -------------------------------------------------------------------------- */
 .md-footer-meta {
   background-color: #0f1214;

docs/containers/distroless.md

@@ -13,6 +13,6 @@ tags:
 
 ## Planned content
 
-- gcr.io/distroless/* — language-specific bases
-- cgr.dev/chainguard — wolfi-based, frequently rebuilt
+- gcr.io/distroless/*: language-specific bases
+- cgr.dev/chainguard: wolfi-based, frequently rebuilt
 - Debugging distroless (`:debug` tag, ephemeral containers)

docs/containers/dockerfile-go.md

@@ -1,13 +1,13 @@
 ---
-title: Go — static binary, distroless
+title: Go: static binary, distroless
 description: Multi-stage Dockerfile producing a static Go binary on a distroless runtime.
 status: stub
 tags:
   - docker
   - go
 ---
 
-# Go — static binary, distroless
+# Go: static binary, distroless
 
 !!! note "Stub page"
     Single-binary Go services in a tiny image.

docs/containers/dockerfile-node.md

@@ -1,13 +1,13 @@
 ---
-title: Node — multi-stage, pnpm
+title: Node: multi-stage, pnpm
 description: Multi-stage Dockerfile for Node services with pnpm and a slim runtime stage.
 status: stub
 tags:
   - docker
   - node
 ---
 
-# Node — multi-stage, pnpm
+# Node: multi-stage, pnpm
 
 !!! note "Stub page"
     Production Node images with pnpm or npm, no dev deps.

docs/containers/dockerfile-python.md

@@ -1,13 +1,13 @@
 ---
-title: Python — multi-stage with uv
+title: Python: multi-stage with uv
 description: Multi-stage Dockerfile for Python services using uv and a slim runtime stage.
 status: stub
 tags:
   - docker
   - python
 ---
 
-# Python — multi-stage with uv
+# Python: multi-stage with uv
 
 !!! note "Stub page"
     Small, reproducible Python images using uv for dependency install.

docs/data/dbt-skeleton.md

@@ -1,6 +1,6 @@
 ---
 title: dbt project skeleton
-description: Opinionated dbt project skeleton — sources, staging, marts, and tests.
+description: Opinionated dbt project skeleton: sources, staging, marts, and tests.
 status: stub
 tags:
   - data

docs/data/postgres-conventions.md

@@ -14,7 +14,7 @@ tags:
 
 ## Planned content
 
-- Primary keys: UUID v7 vs identity vs serial — when each wins
+- Primary keys: UUID v7 vs identity vs serial: when each wins
 - Audit columns: created_at / updated_at / created_by + trigger
 - Soft delete: deleted_at vs separate archive table
 - Naming: snake_case, plural tables, FK suffix

docs/data/postgres-indexes.md

@@ -1,6 +1,6 @@
 ---
 title: Postgres indexing & partitioning
-description: When and how to add indexes — B-tree, partial, GIN, and covering indexes.
+description: When and how to add indexes: B-tree, partial, GIN, and covering indexes.
 status: stub
 tags:
   - data
@@ -14,7 +14,7 @@ tags:
 
 ## Planned content
 
-- Composite indexes — column order rules
+- Composite indexes: column order rules
 - Partial indexes
 - GIN indexes for jsonb / array / full-text
 - Range partitioning by time + pg_partman

docs/github-actions/oidc-aws.md

@@ -1,6 +1,6 @@
 ---
 title: OIDC → AWS (no static keys)
-description: Authenticate GitHub Actions to AWS via OIDC — no long-lived access keys.
+description: Authenticate GitHub Actions to AWS via OIDC: no long-lived access keys.
 status: stub
 tags:
   - github-actions
@@ -17,4 +17,4 @@ tags:
 - IAM identity provider creation (one-time per account)
 - IAM role with sub-claim conditions: branch, environment, tag, PR
 - `aws-actions/configure-aws-credentials` invocation
-- Common 'Not authorized' debugging — what to check
+- Common 'Not authorized' debugging: what to check

docs/github-actions/reusable-workflows.md

@@ -1,6 +1,6 @@
 ---
 title: Reusable workflows
-description: Reusable workflow patterns — inputs, secrets, permissions, and composite actions.
+description: Reusable workflow patterns: inputs, secrets, permissions, and composite actions.
 status: stub
 tags:
   - github-actions

docs/hygiene/index.md

@@ -1,6 +1,6 @@
 ---
 title: Repo hygiene
-description: Repo hygiene snippets — .gitignore, .editorconfig, pre-commit, and Makefiles.
+description: Repo hygiene snippets: .gitignore, .editorconfig, pre-commit, and Makefiles.
 status: stub
 tags:
   - hygiene

docs/hygiene/makefile.md

@@ -1,6 +1,6 @@
 ---
 title: Makefile patterns
-description: Makefile patterns — self-documenting help target, .PHONY hygiene, and uv integration.
+description: Makefile patterns: self-documenting help target, .PHONY hygiene, and uv integration.
 status: stub
 tags:
   - hygiene

docs/hygiene/pre-commit.md

@@ -172,7 +172,7 @@ For project-specific checks that don't warrant their own repo:
 ```
 
 !!! warning "`language: system` requires the binary on PATH"
-    `system` hooks won't be installed for you — make sure `uv`, `lychee`, etc.
+    `system` hooks won't be installed for you: make sure `uv`, `lychee`, etc.
     are available in CI and locally, or use `language: python` /
     `language: docker` / `language: golang` to let pre-commit manage them.
 

docs/index.md

@@ -12,9 +12,9 @@ hide:
 This site collects small, opinionated, well-validated snippets you can drop
 straight into a project. Everything here is designed to be:
 
-- **Self-contained** — copy a single block and it works.
-- **Validated** — variables come with `validation` blocks, types, and sane defaults.
-- **Cited** — links back to the upstream docs so you can verify behavior.
+- **Self-contained**: copy a single block and it works.
+- **Validated**: variables come with `validation` blocks, types, and sane defaults.
+- **Cited**: links back to the upstream docs so you can verify behavior.
 
 ---
 

docs/kubernetes/deployment-baseline.md

@@ -1,6 +1,6 @@
 ---
 title: Deployment + Service + Ingress baseline
-description: Production-ready Deployment baseline — resources, probes, security context, and topology.
+description: Production-ready Deployment baseline: resources, probes, security context, and topology.
 status: stub
 tags:
   - kubernetes

docs/kubernetes/probes.md

@@ -1,6 +1,6 @@
 ---
 title: Probes done right
-description: Liveness, readiness, and startup probes done right — common mistakes and fixes.
+description: Liveness, readiness, and startup probes done right: common mistakes and fixes.
 status: stub
 tags:
   - kubernetes

docs/kubernetes/scaling.md

@@ -14,5 +14,5 @@ tags:
 ## Planned content
 
 - HPA on CPU + custom metrics
-- PodDisruptionBudget — minAvailable vs maxUnavailable
+- PodDisruptionBudget: minAvailable vs maxUnavailable
 - Default-deny NetworkPolicy + targeted allow rules

docs/observability/index.md

@@ -9,7 +9,7 @@ tags:
 # Observability
 
 !!! note "Stub page"
-    Logging, tracing, and metrics — same patterns across stacks.
+    Logging, tracing, and metrics: same patterns across stacks.
 
 ## Planned content
 

docs/observability/prometheus.md

@@ -14,7 +14,7 @@ tags:
 
 ## Planned content
 
-- Naming: `http_requests_total`, `_seconds`, `_bytes` — units in the name
+- Naming: `http_requests_total`, `_seconds`, `_bytes`: units in the name
 - RED method (Rate, Errors, Duration) for request-driven services
 - USE method (Utilization, Saturation, Errors) for resources
 - Histogram bucket selection

docs/terraform/aws/backends.md

@@ -141,7 +141,7 @@ resource "aws_kms_alias" "tfstate" {
 resource "aws_s3_bucket" "tfstate" {
   bucket = var.bucket_name
 
-  # Belt and braces — never let someone delete this by accident.
+  # Belt and braces: never let someone delete this by accident.
   lifecycle {
     prevent_destroy = true
   }
@@ -242,7 +242,7 @@ resource "aws_dynamodb_table" "tflocks" {
 ## References
 
 - [Terraform: S3 backend](https://developer.hashicorp.com/terraform/language/backend/s3)
-- [Terraform 1.10 release notes — S3 native locking](https://github.com/hashicorp/terraform/releases/tag/v1.10.0)
+- [Terraform 1.10 release notes: S3 native locking](https://github.com/hashicorp/terraform/releases/tag/v1.10.0)
 - [OpenTofu: S3 backend](https://opentofu.org/docs/language/settings/backends/s3/)
 - [AWS: Protecting data with server-side encryption (SSE-KMS)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html)
 - [AWS: Using versioning in S3 buckets](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html)