Formatting

Layout and wrapping

Width, margins, headings, tables, block spacing and document line numbers.

Width and margins

An explicit --cols sets the total terminal width.

  • Without it, mdv uses a detected terminal width of at least 20 columns, otherwise configured cols, otherwise 80 columns.
  • Document margins and line-number gutters reduce the space available to content.
  • Their reserved width must be smaller than the total.

Output width

mdv --no-config --theme catppuccin --cols 40 --wrap word example.md
mdv outputVersion 6.1.1
A Markdown viewer keeps a long paragraph
readable while you change the terminal 
width. Each option controls how these 
words are arranged without changing the 
document.
Markdown source
A Markdown viewer keeps a long paragraph readable while you change the terminal width. Each option controls how these words are arranged without changing the document.

Horizontal margins

mdv --no-config --theme catppuccin --cols 64 example.md
mdv outputVersion 6.1.1
A Markdown viewer keeps a long paragraph readable while you chan
ge the terminal width. Each option controls how these words are 
arranged without changing the document.
Markdown source
A Markdown viewer keeps a long paragraph readable while you change the terminal width. Each option controls how these words are arranged without changing the document.

Tab expansion

mdv --no-config --theme catppuccin --cols 64 --tab-length 2 example.md
mdv outputVersion 6.1.1
  name  status
  mdv  ready
Markdown source
```text
name	status
mdv	ready
```

--margin accepts either side or both; an omitted side is zero. --tab-length controls tab expansion, with a default of four spaces. Terminal margins do not apply to HTML export.

Wrapping and paragraph reflow

Value of --wrap Behavior
char Wrap at Unicode grapheme boundaries; the default.
word Prefer word boundaries; break oversized words at grapheme boundaries.
none Avoid soft line wrapping. Constrained table cells may still need to break.

--reflow joins soft source line breaks inside paragraphs before wrapping to the current width. Hard Markdown breaks remain. Reflow requires wrapping to be enabled.

Line wrapping

mdv --no-config --theme catppuccin --cols 40 --wrap char example.md
mdv outputVersion 6.1.1
A Markdown viewer keeps a long paragraph
readable while you change the terminal w
idth. Each option controls how these wor
ds are arranged without changing the doc
ument.
Markdown source
A Markdown viewer keeps a long paragraph readable while you change the terminal width. Each option controls how these words are arranged without changing the document.

Paragraph reflow

mdv --no-config --theme catppuccin --cols 64 --wrap word example.md
mdv outputVersion 6.1.1
This paragraph was wrapped
in the source file.
The reader can join its
soft line breaks together.
Markdown source
This paragraph was wrapped
in the source file.
The reader can join its
soft line breaks together.

Headings

Value of --heading-layout Behavior
level Indent headings by their level and their content one column further; the default.
center Center headings without indenting their content.
flat Left-align headings and indent their content by one column.
none Left-align headings and content.

--show-heading-markers adds # markers matching the heading level. With level, --smart-indent smooths jumps such as H1 followed directly by H4.

Heading layout

mdv --no-config --theme catppuccin --cols 64 --heading-layout level example.md
mdv outputVersion 6.1.1
Guide
 
 An introduction.

 Installation
  
  Install the program.

  Usage
   
   Open a document.
Markdown source
# Guide

An introduction.

## Installation

Install the program.

### Usage

Open a document.

Heading markers

mdv --no-config --theme catppuccin --cols 64 example.md
mdv outputVersion 6.1.1
Guide
 
 An introduction.

 Installation
  
  Install the program.

  Usage
   
   Open a document.
Markdown source
# Guide

An introduction.

## Installation

Install the program.

### Usage

Open a document.

Heading level jumps

mdv --no-config --theme catppuccin --cols 64 example.md
mdv outputVersion 6.1.1
Guide
 
 Introduction.

   Details
    
    A level was skipped.
Markdown source
# Guide

Introduction.

#### Details

A level was skipped.

Tables

Value of --table-wrap Behavior
fit Fit cells to the available width; the default.
wrap Split a wide table into successive blocks of columns.
none Allow horizontal overflow without imposing cell widths.

Table geometry is independent of --wrap, which chooses cell breakpoints.

  • With constrained fit or wrap, a cell can still break at grapheme boundaries when necessary, even with text wrapping disabled.
  • --table-borders enables the full rounded grid.
  • --table-smart-indent reduces indentation when width is tight.

Wide tables

mdv --no-config --theme catppuccin --cols 40 --table-wrap fit example.md
mdv outputVersion 6.1.1
 Name    │ Description         │ Status 
─────────┼─────────────────────┼────────
 reader  │ Comfortable long-fo │ ready  
         │ rm reading with wor │        
         │ d wrapping          │        
 compact │ Dense output for a  │ ready  
         │ narrow terminal wor │        
         │ kspace              │
Markdown source
| Name | Description | Status |
| --- | --- | --- |
| reader | Comfortable long-form reading with word wrapping | ready |
| compact | Dense output for a narrow terminal workspace | ready |

Table borders

mdv --no-config --theme catppuccin --cols 64 example.md
mdv outputVersion 6.1.1
 Name    │ Wrap 
─────────┼──────
 reader  │ word 
 compact │ char
Markdown source
| Name | Wrap |
| --- | --- |
| reader | word |
| compact | char |

Table indentation

mdv --no-config --theme catppuccin --cols 40 example.md
mdv outputVersion 6.1.1
     Settings
      
 Name    │ Description         │ Status 
─────────┼─────────────────────┼────────
 reader  │ Comfortable long-fo │ ready  
         │ rm reading with wor │        
         │ d wrapping          │        
 compact │ Dense output for a  │ ready  
         │ narrow terminal wor │        
         │ kspace              │
Markdown source
###### Settings

| Name | Description | Status |
| --- | --- | --- |
| reader | Comfortable long-form reading with word wrapping | ready |
| compact | Dense output for a narrow terminal workspace | ready |

Blank lines between blocks

--block-spacing accepts element:top=N,bottom=N entries separated by ;. Omitted sides keep their current values. Adjacent gaps collapse to the larger value rather than adding together.

Supported elements: paragraph, h1 through h6, code-block, display-math, table, horizontal-rule, unordered-list, ordered-list, task-list, blockquote, callout, definition-list, inline-references, end-references, attached-footnotes, and endnotes.

Block spacing

mdv --no-config --theme catppuccin --cols 64 example.md
mdv outputVersion 6.1.1
 First section
  
  First paragraph.
  
  Second paragraph.

 Next section
  
  Keep reading.
Markdown source
## First section

First paragraph.

Second paragraph.

## Next section

Keep reading.

YAML uses a mapping, for example paragraph: {top: 0, bottom: 1} inside block_spacing.

Rules and hidden content

--horizontal-rule-style pretty adds decorative endpoints; simple draws a continuous line. It also controls HTML <hr> with embedded-HTML rendering enabled.

--hide-comments suppresses Markdown comments. --show-empty-elements preserves normally hidden empty headings, lists, quotes, code blocks and tables. Front matter has its own display mode.

Horizontal rules

mdv --no-config --theme catppuccin --cols 64 --horizontal-rule-style pretty example.md
mdv outputVersion 6.1.1
Before the rule.

◈──────────────────────────────────────────────────────────────◈

After the rule.
Markdown source
Before the rule.

---

After the rule.

Comment visibility

mdv --no-config --theme catppuccin --cols 64 example.md
mdv outputVersion 6.1.1
Visible text.

<!-- An internal comment. -->
More text.
Markdown source
Visible text.

<!-- An internal comment. -->

More text.

Empty blocks

mdv --no-config --theme catppuccin --cols 64 --code-block-style 'pretty:show-name' example.md
mdv outputVersion 6.1.1
Before an empty code block.

After the block.
Markdown source
Before an empty code block.

```rust
```

After the block.

Document line numbers

--line-numbers alone numbers rendered rows. source numbers physical Markdown source lines; separator adds a separator; source;separator combines both. Put compound values in quotes. A following filename remains positional when the flag has no explicit mode.

Document line numbers

mdv --no-config --theme catppuccin --cols 64 example.md
mdv outputVersion 6.1.1
 Example
  
  A paragraph long enough to wrap into multiple rendered rows at
  the selected terminal width.
  
  Last paragraph.
Markdown source
## Example

A paragraph long enough to wrap into multiple rendered rows at the selected terminal width.

Last paragraph.

Numbering inside code blocks is configured independently.