Plain-Text Outline Normalization: The Technical Guide to Durable Hierarchy
1. The Indentation Divergence Problem in Digital Note-Taking
Hierarchical outlines form the foundational backbone of software technical specifications, research synthesis, legal briefs, and meeting agendas. Despite their conceptual simplicity, plain-text outlines suffer from severe interoperability fragility across digital editing environments. A single document opened across Visual Studio Code, Obsidian, Apple Notes, GitHub pull request comments, and terminal editors like Vim will interpret leading whitespace under conflicting rules.
The fundamental root cause is the conflation of literal ASCII space characters (code point U+0020) with horizontal tab characters (code point U+0009). While graphical editors often display a tab character visually as four character widths, terminal configurations or web-based Markdown parsers may render that same tab as two, eight, or even variable widths. When users copy and paste bulleted points across disparate tools, indentation styles mix silently. A sub-point intended to nest two levels deep may accidentally align with its parent, completely inverting the conceptual meaning of your technical architecture.
2. Deterministic Tab Stop Calculation and Space Mapping
To eliminate indentation drift without corrupting authorial intent, this formatter uses a deterministic equivalent space calculation model. Rather than naively counting raw characters, each leading whitespace string is parsed as a virtual cursor advancing across a columnar grid:
- Space Characters: Advance the virtual cursor position by exactly 1 column.
- Tab Characters: Advance the cursor to the next integer multiple of the configured tab stop width:
spaces += tabStopWidth - (spaces % tabStopWidth). - Mixed Whitespace Detection: If both spaces and tabs occur in the leading whitespace prefix of the same line, the engine records an ambiguity warning and normalizes the composite width deterministically.
Once equivalent space widths are calculated across all non-empty lines, the engine analyzes the minimum non-zero indentation step discovered across the document. This auto-discovers whether the source text was authored using 2-space or 4-space conventions, allowing smooth mapping to integer hierarchy levels without requiring tedious manual configuration.
3. Preventing Hierarchy Inversion: Indentation Jump Clamping
In valid document typography, a child node must be subordinate to an immediate parent. In informal note-taking, however, authors frequently jump several indentation levels at once—for example, indenting eight spaces immediately below a root line with zero spaces. When such text is fed into strict CommonMark or GitHub Flavored Markdown compilers, the resulting HTML list elements frequently fail to nest properly, generating orphaned list tags or broken blockquote contexts.
The Plain-Text Outline Formatter actively inspects each line's relative level offset against its preceding item. Whenever a line attempts to jump deeper than previousLevel + 1, the engine logs an indent-jump warning, notifies the user of the skipped hierarchy tier, and clamps the item to exactly one level below its immediate predecessor. This preserves structural validity across all downstream export formats while highlighting potential authoring oversights.
4. Five Target Serialization Paradigms Compared
Different workflows demand different representation formats. Our formatting engine supports five distinct output serializations from a single unified hierarchy graph:
| Output Style | Syntax Example | Primary Use Case | Portability Guarantee |
|---|---|---|---|
| Markdown Bullets | - Item | Durable PKM vaults, Obsidian, documentation sites | 100% CommonMark & GFM compliant |
| Nested Decimal | 1. Item | Legal agreements, ISO technical standards, RFCs | Universal ASCII plaintext readability |
| ATX Headings | # Item | Drafting multi-section longform guides & books | Directly generates page section navigation |
| Task Checklist | - [ ] Item | Sprint tracking, GitHub issues, procedural checklists | Supported in GitHub, GitLab, Obsidian |
| Unicode Box Tree | Item | Terminal READMEs, system directory visualizations | Single-width monospaced terminal fidelity |
5. Bullet and Marker Normalization Mechanics
When amalgamating notes compiled from disparate sources, bullet markers are frequently inconsistent. One section may use asterisks (*), another hyphens (-), another plus symbols (+), and others Unicode typographical bullets (such as •, ◦, or ▪). Furthermore, copy-pasting from numbered lists often leaves hardcoded digits (1., 2.) or parenthesis enumerators (a), (1)) embedded in the text.
When Strip Existing Bullets/Numbers is enabled, the engine applies regular expression strip grammars before re-serializing the outline. This strips antiquated or mismatched bullet symbols while preserving subsequent text verbatim. As a result, you can paste completely haphazard bullet lists and immediately re-serialize them as clean, uniform Markdown or structured legal decimal sections.
6. Local Processing and Spreadsheet Security Guarantees
Enterprise security policies and data governance standards require that sensitive meeting records, architectural diagrams, and proprietary outlines never leave authorized workstation boundaries. This utility executes entirely within your browser's local JavaScript runtime. It opens zero network connections, stores zero cookies, and retains no persistence after the tab is closed.
When exporting your outline hierarchy as a spreadsheet CSV file for project management tracking, the engine implements strict defense against Formula Injection (CSV Injection). If any outline line starts with vulnerable spreadsheet command characters (=, +, -, @, or tab characters), the field is sanitized with a prepended single-quote escape (') and quoted securely. This guarantees that importing your outline into Microsoft Excel or Google Sheets will never trigger unauthorized dynamic formula evaluation.