Lectern
A calm, beautiful reading view for Markdown in VS Code.
Open any note, doc or README as a page you actually want to read.
Getting started ·
Features ·
Settings ·
Changelog ·
Releases
VS Code's built-in preview is made for checking Markdown while you write it. Lectern is
made for reading it. Your file opens in the same tab as a clean, comfortable page with
good typography, a warm palette if you want one, and nothing else on screen. Ticking a task
or following a link works right there, and the source is one keystroke away.
Getting started
- Install Lectern from the Extensions view (search for "Lectern").
- Open any
.md, .markdown or .mdx file.
- Press
Ctrl+Alt+R (Cmd+Alt+R on macOS). Press it again to go back to the source.
Lectern needs VS Code 1.82 or newer. It also works in editors built on VS Code, such as
Cursor, Windsurf, Antigravity and VSCodium; it's on Open VSX
for the ones that install from there.
You can also click the book icon in the editor title bar, right-click a file in the
Explorer and choose Open in Reading View, or run Lectern: Open in Reading View from
the Command Palette.
Tip: want Markdown to always open in Lectern? Right-click a Markdown tab, choose
Reopen Editor With… → Configure default editor for '*.md'… → Reading View - Lectern: Markdown Reader.
Or add this to your settings.json:
"workbench.editorAssociations": { "*.md": "lectern.reader" }
Features
See what changed
Read your changes the way they'll look, not as lines of Markdown. In a diff of a
Markdown file (for example after clicking a changed file in Source Control), press
Ctrl+Alt+R or click the book icon. Lectern shows the old and new versions side
by side:
- Added blocks are green and removed blocks are red, with a dashed line on the
other side where they were.
- Changed blocks are light red on the left (the old text) and light green on the
right (the new text). The words that changed are highlighted more strongly.
- A task box that was ticked or unticked has a ring around it. Done tasks are not
struck through in a diff, so a line through text always means it was removed.
- Both sides scroll together. The bar at the top counts the changes, jumps to the
previous or next one (
Alt+↑ / Alt+↓), and Text diff goes back to the
normal diff. Ctrl+Alt+R does that too.
To open every Markdown diff this way, run Lectern: Toggle Opening Markdown Changes in
Reading View from the Command Palette. Run it again to go back to text diffs.
A palette for every light
Read in Light, Sepia, Dark or Black, or let Editor follow your VS Code
theme. High Contrast themes are supported too.
Always know where you are
A slide-out outline tracks the section you're reading and jumps anywhere in one click.
A thin progress bar and a word count with reading time sit quietly at the edges.
Pin the outline (the pin button at its top) to keep it open beside the text while you
read. It stays pinned for every note until you unpin it. In a narrow window it slides
over the text instead.
See the whole note as a mind map
The mind map button at the top of the outline (or Lectern: Show Mind Map) draws
the note's headings as a tree that grows out from the title, one colour per section.
Click a heading to jump to it. Click the small circle at the end of a branch to fold it
or open it again. Zoom and move around as in the diagram viewer, and press Esc to
close. With the keyboard: Tab moves between headings, Enter jumps, ← / → fold
and unfold.
Callouts, tasks and wiki links
- Callouts in Obsidian style (
> [!note], > [!warning], …), including foldable
ones ([!faq]-), plus GitHub alerts (> [!IMPORTANT]).
- Task lists you can tick. Clicking a checkbox updates
[ ] / [x] in the file itself.
- Wiki links:
[[Note]], [[Note#Heading]], [[Note|label]] and embeds such as
![[diagram.png|300]] or videos, resolved across your workspace. Missing notes get a
dashed underline.
- Links stay in the reader. A link to
other.md#setup opens that file in Lectern at
that heading; web links open in your browser.
Math
Write formulas the way GitHub and Obsidian do: $…$ inline, $$…$$ on their own lines,
or a ```math block. They're typeset by KaTeX, right in the flow of your text.
Prices like "$5 and $10" stay plain text, and \$ is always a literal dollar.
Diagrams
Mermaid flowcharts, sequence, class, state, ER, Gantt, pie, mind map, timeline and git
diagrams draw straight from a ```mermaid block, in the colours of your reading
palette.
Switch palettes and every diagram is redrawn to match:
Click any diagram to open it full screen. Zoom with the mouse wheel, the toolbar or
+ / -, drag to move around, press 0 to fit it to the window and Esc to close. Big
flowcharts become easy to follow.
Mermaid only loads when a note contains a diagram, so everything else stays fast, and a
typo shows Mermaid's error next to your source instead of a blank box. The
math and diagrams guide has the full syntax, the dollar-sign
rules and examples.
Code that's easy to read
Syntax highlighting for 35+ common languages, with a language label and a
one-click copy button on each block.
Make it yours
The panel in the bottom-right corner sets the palette, font (sans, serif or mono),
text size, line width and line spacing. Changes apply instantly and carry over
to every file.
And the little things
- Emoji shortcodes like
:rocket: 🚀, :tada: 🎉 and :white_check_mark: ✅ work as
on GitHub, using GitHub's own list.
- Front matter is shown as a tidy list of properties, with tags as chips.
- Click any image to view it full window.
Ctrl+F / Cmd+F searches inside the reading view.
- Live updates: edit the source in a split editor and the page follows as you type.
- Keyboard and screen-reader friendly: visible focus, labelled controls,
Escape
closes panels, and motion is reduced when your OS asks for it.
- Safe by design: scripts in your Markdown never run, links can't trigger VS Code
commands, and diagrams and formulas can't add links or scripts either.
Settings
Everything is adjustable from the in-view panel. The same values are regular VS Code
settings, so you can also set them per workspace:
| Setting |
Default |
Description |
lectern.backgroundMode |
editor |
editor, light, sepia, dark or black. |
lectern.fontFamily |
"" |
Any CSS font stack. Empty uses the default sans-serif stack. |
lectern.fontSize |
18 |
Text size in px (12–28). |
lectern.readingWidth |
760 |
Maximum width of the text column in px (480–1600). |
lectern.lineHeight |
1.7 |
Line spacing (1.2–2.4). |
lectern.outlinePinned |
false |
Keep the outline open beside the text. |
Commands
| Command |
Shortcut |
| Lectern: Open in Reading View |
Ctrl+Alt+R / Cmd+Alt+R in a Markdown editor or diff |
| Lectern: Open Markdown Source |
Ctrl+Alt+R / Cmd+Alt+R in the reading view (in a diff: back to the text diff) |
| Lectern: Toggle Opening Markdown Changes in Reading View |
— |
| Lectern: Show Mind Map |
— |
| Lectern: Open Settings |
— |
Contributing
Bug reports, ideas and pull requests are all welcome. CONTRIBUTING.md
explains how to build, test and run Lectern locally; npm run screenshots regenerates
every image on this page.
License
MIT © Omar Elmasry. Lectern bundles open-source libraries such as marked,
highlight.js, KaTeX and Mermaid; their licenses are in
THIRD_PARTY_NOTICES.md.