SyMark processes .sy files from SiYuan notebooks and generates a static website with HTML pages for each note, tag collections, and index pages. It preserves the structure and formatting of your notes while creating a clean, responsive web interface.
- Converts SiYuan notes to responsive HTML webpages
- Maintains bidirectional links and transclusions between notes
- Supports tags with dedicated tag pages
- Automatically generates table of contents
- Renders markdown formatting, code blocks, and other SiYuan features
- Image caption support using figure/figcaption elements
- Custom index page support
- Zero-width whitespace character removal for clean HTML output
- Lightning-fast generation even for large notebooks (1,000,000+ notes)
- Privacy-focused with no trackers or telemetry
- Rust (latest stable version)
- SiYuan notebook with exported
.syfiles
-
Extract the archive
NotebookName.sy.zipinto theinputdirectory in SyMark -
Run SyMark with an optional theme name:
# Use default theme cargo run # Use a specific theme cargo run my-theme
The first parameter is the theme name to use. If not specified, the "default" theme will be used.
-
The generated website will be in the
output/directory -
Open
output/index.htmlin your browser to view your website
The program will display information about the generation process, including:
- Number of notes processed
- Tags found
- Generated HTML files
- Build time statistics
SyMark now supports multiple themes, which can be selected at generation time.
SyMark expects the following directory structure:
symark/
├── input/ # Directory containing SiYuan notebook data
│ ├── assets/ # Assets from SiYuan (images, etc.)
│ ├── [note-id]/ # SiYuan note directories
│ └── [note-id].sy # SiYuan note files (JSON format)
├── themes/ # Directory containing themes
│ ├── default/ # Default theme (used as fallback)
│ │ ├── page.html # HTML template for generated pages
│ │ ├── styles.css # CSS styles for the website
│ │ └── graph.html # Graph visualization template
│ └── [theme-name]/ # Additional themes
└── output/ # Generated website (created by SyMark)
SyMark uses HTML and CSS templates from the themes/[theme-name]/ directory:
page.html: The base HTML template for all generated pagesstyles.css: The CSS styles for the websitegraph.html: The template for the graph visualization page
If these files don't exist for the selected theme, SyMark will attempt to copy them from the default theme. If the default theme doesn't exist, empty templates will be created.
To create a custom index page, add the tag index to any note in SiYuan. SyMark will use that note as the content for the main index.html page.
For example, the note "20250506164324-csw026m.sy" in the sample data has the tag "index" and will be used as the landing page. The system will also generate an "all.html" page that contains links to all notes.
Customize the appearance by editing the CSS file in your theme directory: themes/[theme-name]/styles.css.
Tags in your SiYuan notes become browsable collections in the generated website. For each unique tag, SyMark creates a dedicated page listing all notes with that tag.
The generated website includes:
index.html: Main entry point (custom or default listing)all.html: Complete list of all notestag_[tagname].html: Pages for each tag collection (e.g.,tag_Features.html)[note-id].html: Individual note pages (e.g.,20250506164324-csw026m.html)graph.html: Interactive visualization of note connections
Each page includes navigation links to easily browse between notes, tags, and the index page.
If you encounter issues:
- Ensure your
.syfiles are valid JSON - Check that all referenced assets exist in the
input/assets/directory - Verify you have read/write permissions for the
output/directory - Make sure your note IDs follow the SiYuan format (YYYYMMDDhhmmss-xxxxx)
- For missing assets, check the console output for warnings
- Missing images: Ensure image assets are in the
input/assets/directory - Broken links: Check that referenced note IDs exist in your input directory
- Formatting issues: Verify your SiYuan notes use supported formatting features
- Image captions: Add captions to images by using the title attribute in SiYuan's image dialog
SyMark is optimized for speed and can process large notebooks efficiently:
- Processes hundreds of notes in milliseconds
- Automatically removes zero-width whitespace characters for clean HTML
- Minimal memory footprint suitable for low-end hardware
- Theme-based templates for easy customization
This is free and unencumbered software released into the public domain.
Anyone is free to copy, modify, publish, use, compile, sell, or
distribute this software, either in source code form or as a compiled
binary, for any purpose, commercial or non-commercial, and by any
means.
In jurisdictions that recognize copyright laws, the author or authors
of this software dedicate any and all copyright interest in the
software to the public domain. We make this dedication for the benefit
of the public at large and to the detriment of our heirs and
successors. We intend this dedication to be an overt act of
relinquishment in perpetuity of all present and future rights to this
software under copyright law.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.
For more information, please refer to https://unlicense.org/
SyMark is designed to work with SiYuan, an excellent open-source personal knowledge management system.