Auto-Generating Chapters for Massive Markdown Files on macOS

The Scrolling Problem in Large Markdown Documents

Well-structured Markdown documents use headings to organize content into logical sections. For short notes this is cosmetic. For large technical documents, those headings are essential navigation landmarks. A 12,000-word architecture proposal may have thirty or forty headings spread across six or seven top-level sections. Locating a specific sub-section by scrolling through all that content is slow and disorienting.

Most macOS Markdown viewers offer no structural navigation at all. They treat the document as a flat scroll of content. Telescopo is different: it reads your heading structure and gives it to you as a navigable outline.

Dynamic Chapter Navigation

When you open a Markdown file in Telescopo, the Dynamic Chapter Navigation panel automatically populates with every heading in the document, organized in a hierarchical outline that mirrors the H1, H2, and H3 structure of your file. The panel appears in the sidebar and updates instantly as you navigate the document.

Clicking any chapter entry in the panel scrolls the main view to that heading with a smooth, Metal-accelerated animation. There is no delay, no reflow, and no loss of scroll position context. You can click through ten sections in ten seconds to orient yourself in an unfamiliar document.

Why Metal Acceleration Matters for Large Files

A 15,000-word Markdown file that contains multiple Mermaid diagrams, numerous code blocks, and dozens of headings represents a significant rendering workload. Viewers built on web technology (Electron, WebView) can struggle with this: slow initial render, janky scrolling, and delayed chapter index population are common complaints.

Telescopo's Metal pipeline renders the document on the GPU. Chapter index generation happens on a background thread and does not block the visible content from appearing. The result is that even the largest Markdown files open without any perceptible delay, and the chapter outline is ready by the time you have read the first paragraph.

Use Cases for Large Markdown Navigation

Heading Hierarchy: H1, H2, and H3

The Dynamic Chapter Navigation panel represents the complete heading hierarchy of your document. Top-level H1 headings appear as primary chapters. H2 headings appear as sub-sections indented beneath their parent H1. H3 headings appear as tertiary entries beneath their parent H2.

This three-level hierarchy covers the depth of the vast majority of real-world technical documents. The outline gives you an immediate sense of the document's scope and structure before you read a single line of prose.

The Same Feature Works in ePub Files

Telescopo's chapter navigation extends to ePub files as well. Long ebooks and technical reference manuals in ePub format expose their table of contents through the same sidebar panel, giving you consistent navigation across both Markdown and ePub documents.

Best-Effort Automatic Chapters for Code Files

Telescopo now also supports best-effort automatic chapter generation for coding files. The system is adaptive and works on a per-file basis — it analyzes the structure of your source code (functions, classes, sections, imports) and generates navigable chapter markers that make it easier to jump between logical blocks in large files.

This is not a rigid parser tied to a single language. Instead, Telescopo uses heuristics that adapt to the file's contents, providing useful navigation landmarks even in unfamiliar codebases. Whether you're reading a 2,000-line Swift file or a dense Python module, the chapter panel gives you an at-a-glance outline of the file's structure.

Frequently Asked Questions