How SyMark works

SyMark is simply complexly fascinating software. It runs as a single main.rs file with very few dependencies and is designed to be straightforward and customizable.

Flow of Execution

1. The program starts by finding all .sy files (SiYuan's JSON note format) in a specified input directory using find_sy_files

2. For each note file:

   • Parse the note structure into the Note data structure

   • Extract headings to build a table of contents using extract_toc_items

   • Generate HTML representation of the note content via generate_html_for_note

     1. Block Type Identification: The render_blocks function processes each block based on its Type field:

        • Paragraphs

        • Headings (with levels 1-6)

        • Lists (ordered, unordered, and task lists)

        • Code blocks (with syntax highlighting support)

        • Tables

        • Blockquotes

        • HTML blocks

        • And more specialized types

     2. Text Formatting: Within text blocks, render_text_mark handles:

        • Basic formatting (bold, italic, underline, strikethrough)

        • Links (external URLs and internal references)

        • Code spans

        • Superscript and subscript

        • Highlighting

        • Block references (linking to other blocks by ID)

        • Inline memos

     3. Cross-References: The system supports references between notes:

        • find_block_by_id locates blocks by their unique identifiers

        • find_content_by_id extracts content from referenced blocks

        • NodeBlockQueryEmbed handles transclusions within other notes

        • This enables a wiki-like navigation experience between notes

     4. HTML Safety and SiYuan Compatibility: Several safeguards ensure the generated HTML is safe and valid:

        • escape_html prevents HTML injection in user content

        • remove_zero_width_spaces cleans up text to improve rendering (SiYuan uses zero-width spaces in certain contexts)

        • get_style_class translates SiYuan's custom styling variables into appropriate HTML/CSS classes

        • Careful handling of nested structures (lists within lists, etc.)

     5. Navigation Generation: For each note, the system:

        • Extracts headings to build a table of contents via extract_toc_items

        • Generates a hierarchical TOC via generate_toc_html

        • Adds a back navigation link (defined in BACK_NAVIGATION_HTML)

        • Creates links to related notes based on tags

   • Create navigation elements (table of contents, links to related notes)

   • Apply styling and formatting based on note properties

3. Generate index pages:

   • Main index page via generate_index_page

   • Custom index pages via generate_custom_index_page

   • Tag-based index pages via generate_tag_page

   • Complete note listing via generate_all_notes_page

4. Copy any associated assets (images, CSS, etc.) using find_and_copy_assets and copy_directory

5. Copy everything into the specified output directory and log all events in the terminal output