to-markdown

Files (4)

• SKILL.md
• cropping.md · references/
• review-dimensions.md · references/
• step-6-test-record.md · references/

SKILL.md (first lines)

# Faithful Document → Markdown

## Overview

A conversion is a **transcription**, not a summary and not a rewrite. The output stands in for the
source: someone will cite it, grep it, and trust its numbers without reopening the original.

**Core principle: machine text extraction sets the quality ceiling.** `pdftotext` and friends
destroy exactly what makes a technical document worth converting — fractions collapse to
`1 X x¯k`, table rules vanish, captions merge into body prose, and upright-vs-italic distinctions
disappear. No cleanup pass recovers information that extraction already threw away.

So: **read the rendered page.** Use extraction only as a cheap index (where things are), never as
the source of truth for what things say.

## When to Use

- Source has equations, tables, multi-panel figures, or numbered cross-references.
- Output must be greppable, diffable, or citable — going into a repo, a knowledge base, a wiki.
- Someone will rely on a number in the output without checking the source.
- Reviewing or repairing an existing conversion.

**When NOT to use:**
- You need the *gist* → just read the PDF and answer. Don't convert.
- Plain prose with no structure, and nobody will cite it → `pdftotext -layout` is fine.
- The source is already Markdown, HTML, or LaTeX → convert the markup directly.

## The Output Contract

Every conversion produces these parts. Not guidelines — the shape of the deliverable.

| Part | Content |
|---|---|
| **Body files** | Source prose **verbatim**. Reflowed line breaks; headers and page numbers removed. |
| **Real assets** | Every figure as an actual image file, cropped from the rendered page. |
| **Structured data** | Every table as **Markdown rows**. Never an image. |
| **Math** | Every equation as LaTeX, carrying the source's own equation number. |
| **Provenance** | Per file: source path + page range. Globally: the page-offset rule. |
| **Index** | Nav, plus a figure/table inventory with source pages. |

### Verbatim means verbatim

Preserve the author's errors. Typical examples: *"the results shows"*,
*"this approachs are sensitive"*, *"implementation the module"*, *"seperate layers"*.

Silently fixing these corrupts the reference — a later reader quoting your version misquotes the
author. If a typo genuinely blocks comprehension, keep it and add `[sic]`.

**House style does not apply to quoted material.** If your project mandates a writing style
(terse, plain-language, a controlled-language standard), it governs text *you* author — the index, provenance, reference
cards. The transcribed source keeps its own voice. Rewriting someone's thesis into your house
style produces a paraphrase, not a reference.

### Never fabricate an asset

If the source has a screenshot, extract the screenshot. Hand-typing ASCII or emoji art to imitate
it presents invented content as source content — the single worst outcome here, because it looks
fine and is unfalsifiable without the original. Same for redrawing a diagram from memory or
describing a photo in prose where the figure belongs.

Can't crop it? Say so in the output. An honest gap beats a convincing fake.

## Process

```dot
digraph convert {
    rankdir=TB;
    "Index the source" [shape=box];
    "Read pages as images" [shape=box];
    "Value in typography?" [shape=diamond];
    "Transcribe by eye" [shape=box];
    "Crop assets" [shape=box];
    "Verify to falsify" [shape=box];
    "Review: one agent per lens" [shape=box];

    "Index the source" -> "Value in typography?";
    "Value in typography?" -> "Read pages as images" [label="yes: math,\ntables, figures"];
    "Value in typography?" -> "Transcribe by eye" [label="no: plain prose,\nextraction OK as base"];
    "Read pages as images" -> "Transcribe by eye";
    "Transcribe by eye" -> "Crop assets";
    "Crop assets" -> "Verify to falsify";
    "Verify to falsify" -> "Review: one agent per lens";
    "Review: one agent per lens" -> "Read pages as images" [label="defect found"];
}
```

**1. Index the source.** Page count, page size, producer, text-layer presence, per-page image
counts, caption positions. This is what extraction is *for*. Establish the page-offset rule early
(`PDF page = printed page + N`) — front matter almost always makes these differ.

**2. Read pages as images.** `Read` with `pages` (20 max per call). Batch by chapter, not by
arbitrary page count — batching across a chapter boundary is how page attributions get mixed up.

**3. Transcribe by eye.** Per chapter. Keep the source's own section numbering. Reflow LaTeX line
wraps into whole paragraphs. Drop running headers and page numbers.

**4. Crop assets.** Derive the box from caption position + text-block layout, render at 200 dpi.
The crop's bottom edge goes **above** the caption — the caption belongs in the Markdown as text,
not baked into pixels where it cannot be searched or corrected. Assert it (`y1 = caption.y0 - 2`)
rather than eyeballing it; a caption inside the frame still looks right.
See [references/cropping.md](references/cropping.md) for the PyMuPDF recipe, including two figures
sharing one page.

**5. Verify so that failure is possible.** See below.

**6. Review along independent dimensions.** One subagent per lens, all dispatched in one
message. This step is separate from step 5 and is not satisfied by it: step 5 checks what your
own checks can represent, step 6 covers what they are structurally blind to.

A review is these four parts, in this order:

1. **Write the coverage table before you dispatch anything.** One row per output file you
   produced, with the lens that will cover it. Every row gets a lens name.

   | output file | lens |
   |---|---|
   | 01-introduction.md | prose + tables |
   | 03-methods.md | prose + math |
   | table-3.md | tables |

From bmad-labs/skills, MIT.

More from bmad-labs/skills