init-textbook

What this skill does

# init-textbook

## Purpose

This skill drops a complete, sensible default scaffold into an empty (or
nearly empty) project directory so the user can run `mkdocs serve` and see a
working intelligent textbook within minutes. The scaffold matches the
consensus pattern across our recent textbooks (cybersecurity, networking,
information-systems, ancient-history, statistics-course, token-efficiency,
quantum-computing, world-history, intelligent-textbooks, book-mascots) so the
project starts from the same baseline as everything else in the workspace.

The scaffold is intentionally **minimal-but-complete**: it ships only the
features that every recent textbook ends up using anyway (search, code copy,
admonitions, math via arithmatex, side navigation, CC BY-NC-SA license, the
intelligent-textbook URI scheme, **a `cover.png` plus the social-override
hook that swaps in that cover for the home page**). Everything else — mascots, slide viewer, learning
graph viewer, custom 404, Cairo-based per-page social cards, glightbox image
zoom, Google Analytics, comments, kanban, etc. — is left commented out or
absent so the user can layer it on incrementally via the **book-installer**
skill once they actually need it.

This separation of concerns matters: `init-textbook` is run **once** at
project birth; `book-installer` is run **many times** thereafter to add
features. Trying to ship every feature in the initial scaffold turned out to
make new books slow to start and littered with config the user didn't
understand. The 38-feature list under book-installer is the menu, not the
default order.

## When to Use

Trigger this skill when the user says any of:

- "init textbook" / "initialize textbook" / "init-textbook"
- "create a new textbook"
- "scaffold a new book"
- "start a new intelligent textbook"
- "set up a new mkdocs textbook project"
- "I'm in an empty directory and want to start a book about X"

Do **not** trigger when:

- The directory already has a `mkdocs.yml` and `docs/` — that's a job for
  `book-installer` (to add features) or for individual generator skills.
- The user is asking how to *use* an existing textbook — that's a docs
  question, not a scaffolding job.

## What This Skill Creates

Relative to the project root the user is in:

```
<project-root>/
├── .gitignore                     # Python, MkDocs, OS, and editor ignores
├── {{REPO_NAME}}.code-workspace   # VS Code workspace file
├── mkdocs.yml                     # rendered from assets/templates/mkdocs.yml
├── .gitignore                     # Python / MkDocs / OS / editor ignore patterns
├── plugins/
│   └── social_override.py         # MkDocs hook: per-page og:image / twitter:image override
└── docs/
    ├── index.md                   # home page
    ├── about.md                   # audience + how to read
    ├── course-description.md      # seed for learning-graph-generator
    ├── contact.md                 # LinkedIn contact info
    ├── license.md                 # CC BY-NC-SA 4.0 deed
    ├── chapters/
    │   └── index.md               # "list of chapters" landing page
    ├── learning-graph/
    │   └── index.md               # learning-graph section landing page
    ├── sims/
    │   └── index.md               # MicroSim catalog landing page
    ├── css/
    │   └── extra.css              # cover-image + iframe styles
    ├── js/                        # empty — populated by book-installer features
    └── img/
        ├── cover.png              # generic 1731×909 cover (replace with book-specific art)
        └── license.png            # CC BY-NC-SA 4.0 badge image
```

All template files use `{{PLACEHOLDER}}` markers that the skill substitutes
with values gathered from the user.

## Inputs the Skill Must Gather

Before writing any files, ask the user for the following. Provide sensible
defaults where possible and let the user accept them with a single yes.

| Variable | Default | Notes |
|----------|---------|-------|
| `SITE_NAME` | (none — must ask) | The book's title in title case (e.g. "Quantum Computing") |
| `SITE_DESCRIPTION` | (none — must ask) | One-sentence description for SEO + social sharing |
| `SITE_AUTHOR` | "Dan McCreary" | Inferred from the `git config user.name` if available |
| `GITHUB_USERNAME` | "dmccreary" | Inferred from `git remote get-url origin` if available |
| `REPO_NAME` | basename of current directory | Inferred from `pwd` |
| `LINKEDIN_URL` | "https://www.linkedin.com/in/danmccreary/" | Author's LinkedIn — optional override |
| `PRIMARY_COLOR` | "indigo" | Material palette primary — common picks: indigo, blue, green, brown, deep orange |
| `ACCENT_COLOR` | "orange" | Material palette accent |
| `YEAR` | current year (2026) | For the copyright line |

If the user is in a hurry and says "use defaults", accept the inferred values
and proceed. Always confirm the substituted values back to the user in a
single block before writing files, so they can spot a wrong repo name or a
typo'd title.

## Workflow

### Step 1 — Verify the directory is fit for scaffolding

Run `ls -la` in the project root. The skill should refuse to overwrite when
any of these already exist:

- `mkdocs.yml`
- `docs/index.md`
- `docs/license.md`

If any are present, stop and tell the user — they likely want
`book-installer` instead. Do not silently merge or overwrite; the user's
existing content is the authoritative source.

### Step 2 — Gather inputs

Infer what you can:

```bash
git config user.name                 # → SITE_AUTHOR fallback
git remote get-url origin 2>/dev/null # → parse for GITHUB_USERNAME and REPO_NAME
basename "$(pwd)"                    # → REPO_NAME fallback
date +%Y                             # → YEAR
```

Then ask the user once, in a single grouped prompt, for the remaining values
(`SITE_NAME`, `SITE_DESCRIPTION`, palette preferences) and to confirm the
inferred values. Do not pepper them with one-question-at-a-time prompts.

### Step 3 — Confirm the substitution table

Before writing anything, echo the resolved values back so the user can
correct them in one shot. Example:

```
About to scaffold:
  SITE_NAME         = Quantum Computing for Skeptics
  SITE_DESCRIPTION  = An interactive intelligent textbook examining...
  SITE_AUTHOR       = Dan McCreary
  GITHUB_USERNAME   = dmccreary
  REPO_NAME         = quantum-computing
  PRIMARY_COLOR     = indigo
  ACCENT_COLOR      = orange
  YEAR              = 2026

Site URL will be: https://dmccreary.github.io/quantum-computing/
Proceed? (yes/no)
```

### Step 4 — Create directories and copy templates

Create the directory tree shown above with `mkdir -p`. Then copy each file
from `assets/templates/` into the project, performing placeholder
substitution on the text files.

For text files, do a simple in-place substitution of every `{{VAR}}` token
(e.g. `{{SITE_NAME}}`, `{{SITE_DESCRIPTION}}`, etc.) with the value gathered
in Step 2. Use a small inline `sed` or Python step — do not require any
external dependencies.

For `docs/img/license.png`, copy the binary as-is (no substitution).

### Step 5 — Verify the result builds

After scaffolding, suggest the user run:

```bash
pip install mkdocs mkdocs-material
mkdocs build --strict
```

`--strict` will catch broken nav links right away. The scaffold is designed
to pass `--strict` with no chapter content yet, because every nav entry that
points at a not-yet-generated file is left commented out.

Confirm the social-override hook is wired correctly by checking that the
built home page's `og:image` and `twitter:image` point at the declared
cover (not whatever Material's defaults emit):

```bash
grep -E '(og|twitter):image' site/index.html
# expect: both URLs are absolute and end with /img/cover.png
```

If the URLs don't point at `cover.png`, the hook didn't load — re-check
that `hooks:` is a top-level `mkdocs.yml` key (not nested under
`plugins:`) and that `plugins/social_override.py` is at the project root,
not under `docs/`. (The hook only acts on pages that declare `image:`