Notesaw Preview
Notesaw is an extention of Markdown that is primitively designed for note-taking and documentation, by adding additional features including programming-like block syntax.
Notesaw Preview is a VS Code extension that provides a live preview of Notesaw documents, similar to VS Code's native Markdown preview, but better, faster, and more powerful. The feature set includes stable and precise scroll synchronization, seemingless delay brought by partial rendering, and more.
Notesaw is downward compatible with Markdown, so you may also use it as a drop-in replacement for Markdown preview.
The block style is inspired by Github Alert's design.
Table of Contents
Features
Notesaw Syntax
- 🗂️ Hierarchical block syntax for flexible document organization
- ✏️ Minimalistic syntax design, easy to learn and use, simple but powerful
- 🧘 Minimalistic style design for distraction-free writing and reading, compatible with native GFM styling
- 🎨 Icons and auto-generated label colors for enhanced visual differentiation
- 👍 Integrated support for GFM and KaTeX
- ✈️ Linear-time complexity for extended syntax processing, as efficient as Markdown
Notesaw Preview
- ⚡ Stable and fast for large documents
- 🧠 Intelligent and precise scroll synchronization
- ⏳ Seamless delay brought by partial rendering for improved performance
- 🚀 Instant feedback with no debounce
Get Started
- Install the extension from the Marketplace.
- Open a Markdown document or create a new one.
- Click the preview button in the top-right corner of the editor, or use the command palette (
Ctrl+Shift+P or Cmd+Shift+P) and search for "Notesaw: Show Preview". The button should be next to the native Markdown Preview button.
- Start writing and enjoy the live preview!
Exporting
You can export your Notesaw document to HTML or PDF format. To do this, open the command palette (Ctrl+Shift+P or Cmd+Shift+P) and search for "Notesaw: Export to HTML" or "Notesaw: Export to PDF". The exported file will be saved in the same directory as your Notesaw document.
Notesaw Preview uses Puppeteer to generate PDF files, which requires a working installation of Chrome for Testing.
If you haven't downloaded one, we recommend manually downloading and installing chrome from Official Releases. Find chrome binary that matches your operating system and architecture, download from the corresponding URL, and extract it to a desired location. You should be able to find the chrome binary in the extracted folder, and fill its absolute path to the Puppeteer Path setting in the extension settings.
You can also get Chrome for Testing via npm. For more details, please refer to Chrome for Testing and Puppeteer Documentation.
Extension Settings
You can customize the behavior of Notesaw Preview through the VSCode settings. Press Ctrl + , (or Cmd + , on macOS) to open the settings, and search for "Notesaw" to find the available options.
Notesaw Syntax
Please refer to SYNTAX.md for the complete syntax specification of Notesaw.
It is recommended to read the syntax specification before using Notesaw, as it will help you understand the design philosophy and how to write and structure your notes effectively.
A note on GFM footnotes. A footnote reference (text[^1]) and its definition ([^1]: …) are resolved together across the whole document by Markdown. Because Notesaw previews edit incrementally — only re-rendering the changed range instead of the whole note — a reference and its definition are only kept reliably linked when they fall within the same re-rendered region. Keep them close together (or in adjacent content) for now; distant footnotes may drop their link when edited in a different region. Full footnote tracking across ranges is planned for a future rewrite.
How does it work?
Notesaw is built on top of the unified framework/ecosystem, which provides a powerful and flexible way to process and transform Markdown content.
Parsing. The Notesaw parser (src/parser.ts) linearly sweeps through the document, recognizing and processing extended syntax elements (block, inline block, box) as it goes, which makes it super efficient. The rest of the document is partitioned into pieces, and each piece is processed by remark to obtain an MDAST fragment. Notesaw then merges all the fragments into the final MDAST, which is processed into HAST and finally HTML by rehype. Indentation (4 spaces or a tab) is what determines the hierarchy, so extended syntax is only recognized at the correct indentation level.
Location tracking. During the transformation stage (src/transformer.ts), every rendered element is assigned a stable id, and Notesaw maintains a set of line-to-block maps (map, mapStartLine, mapEndLine, mapDepth, mapFather) that record which block each editor line belongs to. Combined with the position information provided by remark, these maps are crucial for scroll synchronization between the editor and the preview, as well as partial rendering.
Rendering. The generated HTML fragment is delivered to the webview (assets/script/webview-script.js), which either performs a full diff update via morphdom, or — for a text edit — re-processes only the minimal affected range and patches the corresponding DOM subtree in place. HTML/PDF export reuses the same core pipeline (src/note-convert.ts), with PDF generation handled by Puppeteer.
For more details, see architecture.md.
Change Log
For full change log, see CHANGELOG.md.
Progress
Notesaw Renderer
- [x] Add support for basic Markdown syntax
- [x] Add support for KaTeX math syntax
- [x] Add support for code blocks highlighting
- [x] Add support for code blocks with line numbers
- [x] Basic block syntax support
- [ ] Block link support
- [x] Inline Block Syntax
- [x] Error handling
- [ ] Custom indentation length
- [ ] Custom block label
- [x] Export to PDF
Notesaw Editor
- [x] VScode extension framework
- [x] Preview button to the editor
- [x] Real-time rendering
- [x] Intelligent DOM tree replacement
- [x] Partial rendering to improve performance
- [x] Scroll Synchronization
- [x] Editor to preview
- [ ] Preview to editor
- [x] Theme support
Future Plans
- [ ] Wiki links support
- [ ] Support keypoint summary
- [ ] Syntax highlighting
- [ ] Editor formatting
Milestones
- [2025-02] Gain inspiration and start project planning.
- [2025-03] Confirm development path: build on top of unified framework.
- [2025-03] Start developing core features.
- [2025-04-18] Complete the first version of the core features.
- [2025-05-03] Complete main features of Notesaw VS Code preview extension.
- [2025-08-27] Redesign the style and simplify the syntax.
- [2025-09-01] Complete Notesaw preview v0.1.0 and release it on the VS Code Marketplace.
- [2025-10-26] Release v0.2.0.
- [2026-02-17] Release v0.2.2.
References
License
This project is licensed under the MIT License - see the LICENSE file for details.
