Long-Form Writing in Markdown: Books, Newsletters and Shareable Notes

Long documents break the assumptions short ones let you ignore. A 5,000-word report fits in one file and one mental model. A 90,000-word book does not: you need a file structure, a build step, consistent chapter layout, and a way to find the paragraph you half-remember writing four months ago.

This guide covers three kinds of long-form work — books, newsletters, and notes intended for other people — and the point at which Markdown stops being the right container.

Structuring a book

One file per chapter is the convention, and it is correct for a simple reason: it keeps diffs meaningful. A single 90,000-word file produces changesets you cannot review and merge conflicts you cannot resolve.

my-book/
├── build.sh
├── metadata.yaml
├── styles/
│   └── print.css
├── front/
│   ├── 00-half-title.md
│   ├── 01-title.md
│   ├── 02-copyright.md
│   └── 03-preface.md
├── chapters/
│   ├── 01-the-problem.md
│   ├── 02-first-principles.md
│   ├── 03-a-worked-example.md
│   └── ...
├── back/
│   ├── 90-appendix-a.md
│   ├── 91-glossary.md
│   └── 92-further-reading.md
└── build/
    └── my-book.pdf

Numeric prefixes give you ordering that survives shell globbing, which is what makes the build script a one-liner. Zero-pad them — 01, not 1 — or chapter 10 sorts before chapter 2. Leaving gaps in the back-matter numbering (90, 91) means you can insert a chapter without renaming everything.

A minimal build:

#!/usr/bin/env bash
set -euo pipefail

OUT="build/my-book.pdf"
mkdir -p build

pandoc \
  metadata.yaml \
  front/*.md \
  chapters/*.md \
  back/*.md \
  --toc \
  --toc-depth=2 \
  --top-level-division=chapter \
  --pdf-engine=xelatex \
  --css=styles/print.css \
  -o "$OUT"

echo "Built $OUT ($(du -h "$OUT" | cut -f1))"

--top-level-division=chapter makes # headings into real chapters rather than sections, which is what drives chapter numbering and page breaks in the LaTeX document class.

Writing habits that scale

One sentence per line. Unconventional and genuinely transformative for long-form work:

The argument depends on a distinction that is easy to miss.
A system can be reliable without being predictable.
Reliability is about outcomes; predictability is about process.

Rendered output is identical — Markdown collapses single newlines into spaces. But diffs become sentence-level rather than paragraph-level, so git diff shows exactly which sentence you rewrote instead of reflowing an entire block. For a manuscript you will revise a dozen times, this is the single highest-value habit available.

Keep a notes.md per chapter. Research, quotes to verify, things to check. It does not go in the build.

Mark unfinished work with a searchable token:

Revenue grew by TKTK percent over the period.

<!-- TODO: verify the 2024 figure against the annual report -->

TKTK is the journalism convention for “to come” — it appears in no English word, so rg TKTK finds every gap. HTML comments never render, so drafts stay clean.

Track your word count over time rather than agonising over it daily:

#!/usr/bin/env bash
# wordcount.sh — append today's total to a log
TOTAL=$(cat chapters/*.md | wc -w | tr -d ' ')
echo "$(date +%Y-%m-%d),$TOTAL" >> build/wordcount.csv
tail -5 build/wordcount.csv

Front matter and back matter

Books have conventional apparatus. Getting it roughly right signals competence; getting it wrong is distracting.

The conventional order:

Section	Content	Numbering
Half title	Title only	Unnumbered
Title page	Title, subtitle, author, publisher	Unnumbered
Copyright	Copyright notice, ISBN, edition	Unnumbered
Dedication	Optional, short	Unnumbered
Contents	Generated	Roman
Preface / Foreword	Author’s or another’s introduction	Roman
Body	Chapters	Arabic, restarting at 1
Appendices	Supporting material	Arabic, continuing
Glossary	Terms	Arabic, continuing
Notes / Bibliography	References	Arabic, continuing
Index	Generated	Arabic, continuing

The numbering convention — roman for front matter, arabic restarting at the first chapter — is why front matter needs its own page configuration:

@page frontmatter {
  @bottom-center {
    content: counter(page, lower-roman);
    font-size: 9pt;
    color: #666;
  }
}

.front-matter { page: frontmatter; }

/* Arabic numbering restarts with the body. */
.body-start { counter-reset: page 1; }

A copyright page, for reference:

<div class="copyright">

Copyright © 2026 Jordan Rivera

All rights reserved. No part of this publication may be reproduced,
distributed, or transmitted in any form without the prior written permission
of the publisher, except in the case of brief quotations embodied in critical
reviews and certain other noncommercial uses permitted by copyright law.

First edition, June 2026

ISBN 978-0-000000-00-0

Set in Source Serif 4 and Inter.

</div>

Book interior layout

Book pages differ from report pages in ways that are conventions rather than rules, but they are the conventions readers expect.

@page {
  size: 152mm 229mm;   /* 6" × 9" trade paperback */
  margin: 20mm 18mm 22mm;
}

/* Wider inner margin for the binding gutter. */
@page :left {
  margin-right: 26mm;
  @bottom-left  { content: counter(page); }
  @top-left     { content: string(booktitle); }
}

@page :right {
  margin-left: 26mm;
  @bottom-right { content: counter(page); }
  @top-right    { content: string(chapter, first); }
}

/* Chapter openings: always recto, no running head. */
@page chapter-opening {
  @top-left  { content: none; }
  @top-right { content: none; }
}

@media print {
  body {
    font-family: "Source Serif 4", Georgia, serif;
    font-size: 10.5pt;
    line-height: 1.5;
    text-align: justify;
    hyphens: auto;
  }

  h1 {
    page: chapter-opening;
    break-before: recto;
    page-break-before: right;
    string-set: chapter content();
    font-size: 20pt;
    margin: 50mm 0 18mm;
    text-align: center;
    font-weight: 400;
    letter-spacing: 0.02em;
  }

  /* Indented paragraphs, no vertical space — the book convention. */
  p {
    margin: 0;
    text-indent: 1.4em;
  }

  /* First paragraph of a section is not indented. */
  h1 + p,
  h2 + p,
  hr + p,
  p:first-of-type {
    text-indent: 0;
  }

  /* Generous orphan/widow control — books are judged on this. */
  p {
    orphans: 2;
    widows: 2;
  }

  blockquote {
    margin: 10pt 5mm;
    font-size: 9.8pt;
    font-style: normal;
    line-height: 1.45;
  }
}

Several things there are specific to books:

break-before: recto starts each chapter on a right-hand page, inserting a blank verso where needed. This is standard in printed books and pointless in a screen-read PDF — use break-before: page if the output is digital only.

Justified text with hyphenation. Books are justified; reports usually are not. Justification without hyphenation produces rivers of whitespace, so hyphens: auto is mandatory, and it requires lang="en" on the <html> element or it silently does nothing.

Indented paragraphs with no vertical space. The opposite of web convention. Vertical space between paragraphs is a screen convention that looks wrong in a book. The text-indent: 0 exceptions after headings are what makes it read correctly.

Running heads that differ by side. Book title on the verso, chapter title on the recto. string-set handles the chapter side.

Scene breaks

Within a chapter, a shift in time or perspective is marked by a typographic break rather than a heading. In Markdown that is ---, which becomes <hr>:

hr {
  border: none;
  text-align: center;
  margin: 14pt 0;
}

hr::after {
  content: "* * *";
  letter-spacing: 0.5em;
  color: #666;
  font-size: 10pt;
}

Or use whitespace alone, which is subtler:

hr { border: none; height: 14pt; }

Newsletters

Newsletters have one hard constraint that shapes everything: most are read in an email client, and email clients are not browsers. This has a direct implication for Markdown workflows that is worth stating plainly.

If your newsletter is delivered by email, the PDF path is irrelevant. Email HTML is a different, far more restrictive medium: tables for layout, inline styles only, no @media queries in several clients, no web fonts in Outlook. Markdown converts to email HTML through a dedicated tool (a newsletter platform’s own editor, or something like MJML), not through a print pipeline.

The PDF path makes sense for newsletters in two specific cases:

A print newsletter — a physical bulletin for members, a school or club circular, something posted on a noticeboard. Here PDF is the correct output and print CSS applies directly.

An archive. A newsletter that went out by email, preserved as a PDF for a back-issue archive. Recipients got HTML; the archive gets a paginated document.

For either, a newsletter layout is a two-column print layout with a strong masthead:

@page {
  size: A4;
  margin: 15mm 14mm 18mm;
  @bottom-center {
    content: "Issue 34 · June 2026 · Page " counter(page);
    font-size: 8pt;
    color: #888;
  }
}

@media print {
  body {
    font-family: "Source Sans 3", Helvetica, sans-serif;
    font-size: 9.5pt;
    line-height: 1.45;
  }

  /* Masthead spans the full width. */
  h1 {
    font-size: 30pt;
    font-weight: 800;
    letter-spacing: -0.03em;
    text-transform: uppercase;
    border-bottom: 3pt solid #111;
    padding-bottom: 4pt;
    margin: 0 0 3pt;
    column-span: all;
  }

  .masthead-meta {
    font-size: 8pt;
    text-transform: uppercase;
    letter-spacing: 0.12em;
    color: #666;
    margin-bottom: 12pt;
    column-span: all;
    display: flex;
    justify-content: space-between;
  }

  .newsletter-body {
    column-count: 2;
    column-gap: 8mm;
    column-rule: 0.5pt solid #d4d4d8;
    column-fill: auto;
  }

  .newsletter-body h2 {
    font-size: 13pt;
    line-height: 1.2;
    margin: 12pt 0 3pt;
    break-after: avoid;
  }

  .newsletter-body h2:first-child { margin-top: 0; }

  /* A lead story spanning both columns. */
  .lead { column-span: all; }

  .newsletter-body p { margin: 0 0 6pt; }

  /* Pull quotes as column-width interruptions. */
  .pull-quote {
    font-size: 13pt;
    line-height: 1.3;
    font-weight: 600;
    color: #333;
    border-top: 1.5pt solid #111;
    border-bottom: 1.5pt solid #111;
    padding: 7pt 0;
    margin: 10pt 0;
    break-inside: avoid;
  }
}

column-fill: auto is deliberate: the default balance equalises column heights on the last page, which looks wrong for a newsletter where you want copy flowing naturally down column one before column two.

Keep code out of two-column newsletters. Eighty millimetres is not enough width for a fenced block — see the print CSS guide for the column-span: all escape hatch if you must.

Turning notes into shareable documents

Notes written for yourself and notes written for others are different documents. The gap is usually not length — it is that private notes are full of context only you have.

A realistic checklist before sharing working notes:

Expand your abbreviations. OMS means order management system to you and nothing to the reader. Personal shorthand is the commonest reason shared notes are incomprehensible.

Add the framing you never needed. Why does this document exist? What question was being answered? Two sentences at the top does most of the work.

Cut the dead ends. Notes record thinking, including approaches you abandoned. Unless the abandonment is the point, remove them — they read as recommendations.

Resolve the open questions, or label them. A note that says “check whether this is true” is fine for you and alarming for a reader. Either check it or mark it explicitly as unresolved.

Remove anything private. Notes accumulate offhand assessments of people, half-formed complaints, credentials pasted in for convenience. Read the whole thing before it leaves your machine. This is the failure mode with real consequences.

Add a date and your name. A shared document with no date has no shelf life and no accountability.

Structurally, a short header does most of the work:

# Cache invalidation investigation

**Author:** Jordan Rivera
**Date:** 4 June 2026
**Status:** Findings — no decision made yet
**Audience:** Platform team

## Why this exists

Order totals were occasionally stale after a price change. This note records
what I found and the three options I see. It does not recommend one.

## What I found

...

## Options

...

## What I did not investigate

- Whether the same issue affects the tax calculation path
- Behaviour under concurrent price changes to the same SKU

That last section is the highest-value one in a shared investigation note. Stating the boundary of what you looked at prevents the reader from assuming coverage you did not provide.

Layout for notes

Notes do not need book typography. They need to be legible and clearly dated:

@page {
  size: A4;
  margin: 22mm 20mm;
  @top-right {
    content: "Cache invalidation investigation · 4 June 2026";
    font-size: 8pt;
    color: #999;
  }
  @bottom-right {
    content: counter(page) "/" counter(pages);
    font-size: 8pt;
    color: #999;
  }
}

The date in the running header is the important part: a printed page found on a desk six months later carries its own provenance.

Where Markdown stops being enough

Being honest about the ceiling, because for long-form work you may hit it.

Indexes. A real back-of-book index — terms, subterms, page ranges, cross-references — has no Markdown equivalent. LaTeX has makeindex; InDesign has an index panel. Markdown has nothing, and the target-counter() approach that works for a contents list does not extend to an index.

Cross-references at book scale. “See chapter 7, page 213” needs numbering that survives reordering. pandoc-crossref handles figures and tables well; it is not designed for the density a technical book needs.

Float placement. Figures that should appear “near here, at the top of a page, with text flowing around them” require a float algorithm. LaTeX’s is decades old and very good. CSS paged media floats are among the least reliably implemented parts of the spec.

Fine typographic control. Optical margin alignment, manual kerning of a title, adjusting the tracking of one line to fix a bad break, controlling paragraph rag. These are InDesign operations. Print CSS gives you none of them.

Design-led layout. If the book’s layout is part of its argument — an art book, a heavily illustrated technical manual, anything where the page is composed rather than flowed — use a design tool. Markdown assumes text flows into a container, and fighting that assumption is more work than starting elsewhere.

A pragmatic split many authors use: write in Markdown, typeset elsewhere. The manuscript lives in version control as plain text through every draft. When the text is final, it goes to LaTeX for a technical book or InDesign for a designed one. You get Markdown’s authoring experience for the eighteen months of writing and a real typesetting tool for the two weeks of production.

Try it yourself

For chapter drafts, newsletters, and notes you are about to share, the editor here handles the full document in a paginated preview, so you can see chapter openings, column flow and page counts as you write. Nothing is uploaded, which matters for manuscripts and unpublished work.

For a full book build, Pandoc is the right tool — see the Pandoc comparison for where each approach fits, and the academic writing guide if your long-form work needs citations.