--- name: tomdale-inside-mac title: inside mac kind: skill-folder description: 2 skills kept together in one folder, by tomdale. skills: 2 updated: 2026-09-29 authored_by: tomdale source_url: https://github.com/tomdale/inside-mac page: https://innernet.live/community/skills/tomdale/inside-mac --- # inside mac a folder of 2 skills by tomdale, kept on innernet at https://innernet.live/community/skills/tomdale/inside-mac (source: https://github.com/tomdale/inside-mac). every skill in it is below, whole. each one starts with its own manifest: what it does, when to load it, whose it is. you do not need all of them at once. read the index, then use the skill that fits the task in front of you. each skill also has its own link, if only one is wanted. ## the skills 1. **imac doc architecture**: Designs or restructures documentation sets, books, guides, chapters, and subsystem pages in the Inside Macintosh style. Use when planning information architecture, separating concepts/tasks/reference, creating reader roadmaps, defining chapter templates, or repairing navigation and cross-references. https://innernet.live/skills/tomdale-imac-doc-architecture 2. **imac pdf book**: Renders a Markdown documentation set into a print-quality PDF book in the Inside Macintosh visual style, with a cover, a table of contents with page numbers, chapter openers, running heads, labeled callouts, Mermaid figures, and appendixes. Use when asked to produce a PDF guide, manual, or book from Markdown, or to package documentation written with the imac-* skills as a printable deliverable. https://innernet.live/skills/tomdale-imac-pdf-book --- --- name: tomdale-imac-doc-architecture title: imac doc architecture kind: skill description: > Designs or restructures documentation sets, books, guides, chapters, and subsystem pages in the Inside Macintosh style. Use when planning information architecture, separating concepts/tasks/reference, creating reader roadmaps, defining chapter templates, or repairing navigation and cross-references. updated: 2026-09-29 authored_by: tomdale author_url: https://github.com/tomdale source_url: https://github.com/tomdale/inside-mac/tree/main/skills/imac-doc-architecture brought_by: SD license: MIT --- # Architect the documentation Make the material usable in two modes: sequential learning and direct lookup. Organize around reader intent, not the source tree. ## Establish the documentation contract Before drafting, record: - **Audience:** roles and assumed competence. - **Scope:** what this document covers and deliberately omits. - **Prerequisites:** concepts, tools, permissions, and prior pages. - **Environment:** package/API version, runtime, platform, and support status. - **Outcomes:** tasks readers will be able to complete. - **Next paths:** where each reader type should go afterward. Do not begin with installation details or an API inventory before explaining what the system is for. ## Use four layers Apply this default progression to each feature area: 1. **About X** — purpose, mental model, vocabulary, boundaries, and invariants. 2. **Using X** — ordinary workflows, minimum useful API, tested examples, and recovery. 3. **X Reference** — authoritative contracts for every public surface. 4. **Summary of X** — compact inventory and links, preferably generated. Add an implementation or advanced layer between Using and Reference only when readers build adapters, plugins, providers, or internals. Label it by audience. Keep layers distinct: - About explains *what and why*, not every option. - Using teaches *how to accomplish a goal*, not every symbol. - Reference states *the complete contract*, not a tutorial narrative. - Summary supports scanning; it must not duplicate hand-maintained truth. ## Build a book or documentation set ```markdown # ## Start here - Who this is for - What it enables - Supported versions and environments - Prerequisites ## What to read | If you want to… | Read… | You can skip… | |---|---|---| | Understand the model | About | Advanced internals | | Complete the common path | Using | Full reference | | Integrate deeply | Extension guide | Beginner walkthrough | | Look up a symbol | API Reference | Narrative sections | ## System overview - Architecture diagram - Components and boundaries - One minimal end-to-end example ## Feature areas - About - Using - Reference - Summary of ## Shared lookup - Compatibility and deprecations - Error and recovery index - Glossary - API index ``` Order feature areas by dependency or user workflow. Start high-level and descend only as needed. If chapters are independent, say so; if one is foundational, say “Read this first” and explain why. ## Open every chapter with a roadmap ```markdown # ## Read this chapter if - … ## Before you begin - Knowledge: … - Setup: … - Versions: … ## In this chapter You will: - understand … - implement … - diagnose … ## You can skip - Skip
unless … ## Related paths - For …, see [] because … ``` Route by jobs, not only by product taxonomy. State why a cross-reference matters. ## Design navigation for the web - Use stable descriptive anchors, searchable headings, breadcrumbs, and “On this page.” - Link concepts to their first definition, tasks to exact reference entries, and reference entries back to working examples. - Add **See also** links for prerequisites, alternatives, lifecycle neighbors, and recovery—not generic “related content.” - Use a glossary for controlled vocabulary. Add “See,” “See also,” and “Compare” links; distinguish overloaded senses. - Give figures, tables, and examples descriptive captions that state the lesson. - Keep version and platform metadata structured and centralized, then surface local badges where behavior differs. - Generate API inventories from canonical declarations where possible. Do not reproduce page numbers, print indexes, duplicated language summaries, or cross-book scavenger hunts. ## End with an operational summary ```markdown ## Summary ### Mental model - … ### Common path 1. … 2. … 3. … ### Public surface - [Types](…) - [Functions](…) - [Events/hooks](…) - [Errors](…) ### Invariants - Must: … - Never: … ### Continue - If …, read … ``` Prefer a generated symbol list over copied declarations. Summarize decisions and invariants, not the preceding prose. ## Check the architecture Confirm that: - a newcomer can find a viable start; - an experienced reader can jump directly to a contract; - the common path appears before advanced variants; - every layer has one job; - no essential context is exiled to another document; - cross-links form concept → task → reference → recovery loops; - compatibility and support status are visible before implementation begins. --- --- name: tomdale-imac-pdf-book title: imac pdf book kind: skill description: > Renders a Markdown documentation set into a print-quality PDF book in the Inside Macintosh visual style, with a cover, a table of contents with page numbers, chapter openers, running heads, labeled callouts, Mermaid figures, and appendixes. Use when asked to produce a PDF guide, manual, or book from Markdown, or to package documentation written with the imac-* skills as a printable deliverable. updated: 2026-09-29 authored_by: tomdale author_url: https://github.com/tomdale source_url: https://github.com/tomdale/inside-mac/tree/main/skills/imac-pdf-book brought_by: SD license: MIT --- # Render the guide as a book Write the content with the other `imac-*` skills first. This skill only turns finished Markdown into a paginated PDF. ## Set up a book directory Copy `assets/` from this skill into a new directory, for example `my-guide/`: ``` my-guide/ book.json { "title": "Inside Acme: Widgets" } package.json marked, mermaid, pagedjs, puppeteer-core build.mjs Markdown → HTML → Paged.js → PDF style.css page geometry and typography src/ one Markdown file per chapter, built in filename order ``` Then install the dependencies and build: ```sh npm install npm run build # writes ".pdf" and build/book.html ``` The build drives a locally installed Google Chrome with `puppeteer-core`. Set `CHROME_PATH` if Chrome is somewhere other than `/Applications/Google Chrome.app`. Mermaid and Paged.js load from `node_modules`, so no network access is needed after install. Add `node_modules/` and `build/` to `.gitignore`. ## Source conventions | Construct | Write | Result | |---|---|---| | Cover | `<div class="cover">` containing `cover-kicker`, `cover-title`, `cover-sub`, and `cover-meta` divs | Full-bleed dark cover page | | Table of contents | `<div class="toc-page">`, `## Contents`, and `<nav id="toc"></nav>` | Generated from H1 and H2 headings, with page numbers | | Chapter | `# Title` | New page, "Chapter N" label, rule, running head | | Unnumbered front matter | `# Preface {.unnumbered}` | Chapter opener without a number | | Appendix | `# Glossary {.appendix}` | "Appendix A", "Appendix B", and so on | | Section | `## Heading`, `### Heading` | Ruled sans-serif section heads | | Callout | `> [!NOTE]`, `> [!IMPORTANT]`, `> [!WARNING]`, followed by `>` lines | Labeled, left-ruled box | | Figure | A paragraph starting `**Figure N-M: Caption.**` directly followed by a ` ```mermaid ` block | Captioned figure that is kept on one page | | Code | Fenced code block with a language | Monospaced block with a left rule | | Tables | GFM tables | Ruled tables. Rows are not split across pages. | Number figures by chapter (`Figure 3-2`) in the text itself. Write captions that state the lesson, not just the topic. ## Layout decisions - The trim size is 7.5 × 9.25 in, with mirrored margins and a wider inside margin, as in the 1990s series. - Body text is Palatino. Headings, tables, and running heads are Helvetica Neue. Code is Menlo. - Page numbers are on the outside edge. The running head shows the chapter label on the left and the chapter title on the right, and is hidden on chapter-opening pages. - A chapter starts on a new page, not always a right-hand one, so the book has fewer blank pages. Adjust `style.css` rather than `build.mjs` for visual changes. Change `@page size` and the margins together. ## Verify the output 1. Check the page count that the build prints. 2. Rasterize a few pages (`pdftoppm -r 60 -png book.pdf pages/p`) and inspect the cover, the table of contents, one chapter opener, one figure, and one page with a wide table. 3. Confirm that no figure is separated from its caption, that the table of contents shows page numbers, and that no Mermaid block rendered as raw text. Raw text means a syntax error: check the build output for `pageerror`. ## Troubleshooting | Symptom | Cause | Fix | |---|---|---| | Build hangs, then times out | A Mermaid syntax error stopped rendering | Fix the diagram. Quote labels that contain `()` or `:`. | | A chapter title sits alone on a page | A CSS `page:` property on the chapter opener forces a break | Do not assign named pages to openers | | Figure too small | A wide left-to-right layout was scaled down to the page width | Use `flowchart TB`, or split the diagram | | Table of contents missing page numbers | Headings lack IDs, or the TOC markup changed | Keep the `<nav id="toc"></nav>` placeholder |