MiaoYan Documentation

Editing Pipeline (Hot Path)

Keystrokes flow through EditTextView (a NSTextView subclass with CustomTextStorage) to NSTextStorage.processEditing. Performance is managed by NotesTextProcessor.checkPerformanceLevel:

• Short text: Full Markdown highlighting via MarkdownRuleHighlighter.
• Long/Large text (> 1 MB total OR > 64 KB per paragraph OR > 5000 lines): Simplified highlighting (skips code block regex).
• Medium text (> 2000 lines): Simplified, but code highlighting remains active.

Preview Pipeline

Content flows from Note.content through swift-cmark-gfm to generate an HTML string. Post-render transforms (like math <br> cleanup and GitHub Alerts rewrites) are applied in renderMarkdownHTML. The MPreviewView (WKWebView) loads Resources/DownView.bundle/index.html. Subsequent edits use incremental DOM mutation rather than full reloads.

Use HTML comments to control the appearance order and visual effects of elements (fragments) during a presentation.

Ordering elements: Use data-fragment-index to specify the sequence in which items appear.

Visual effects: Apply classes to elements to trigger specific animations like fading, highlighting, or scaling.

MiaoYan uses Main.storyboard for its macOS UI. Certain bindings are strictly tied to specific class selectors and identifiers. Moving or renaming these will break the UI at runtime without compile-time errors:

• ViewController.swift: Must remain the viewController scene; all @IBOutlet and @IBAction declarations must reside here.
• SidebarProjectView: Loaded as an outline view subclass; use awakeFromNib for construction, not init.
• NotesTableView: Cell views must use the identifier NSUserInterfaceItemIdentifier("NoteCellView").
• SidebarProjectView cells: Must use the identifier "DataCell".
• Action Chain: @IBAction methods in ViewController+Action.swift must maintain their exact ObjC selectors.

MiaoYan supports both unordered and ordered lists:

• Unordered Lists: Use -, *, or + followed by a space.
• Ordered Lists: Use numbers followed by a period (e.g., 1. ).
• Nested Lists: Indent subsequent lines to create sub-items.

You can teach AI agents how to use MiaoYan's specific syntax, attachments, PPT patterns, and CLI workflows by installing the official skill.

npx skills add tw93/MiaoYan/skills/miaoyan -g

Frontend assets used for WKWebView previews are located in Resources/DownView.bundle/. These are vendored manually rather than through SPM. To update an asset:

1. Replace the existing file in Resources/DownView.bundle/.
2. Regenerate the manifest hash using shasum -a 256 <path_to_file.min.js>.
3. Update the entry in Resources/DownView.bundle/js/vendor/MANIFEST.json with the new version and hash.
4. Commit the changes.

Add interactive elements and media:

• Links: Use [Link Text](URL).
• Internal Links: Reference sections using [Section Name](#anchor-name).
• Images: Use HTML <img> tags for fine-grained control over width and height, or standard Markdown syntax.
• Markdown Images: ![Alt Text](URL).

Reference notes at the end of a document:

1. Define the reference in text using [^1].
2. Define the content at the bottom using [^1]: Footnote text.

To make items appear in a specific sequence (step-by-step), use the .element: directive with class="fragment" and data-fragment-index="n".

Visual Effects for fragments:

• fade-in / fade-out / fade-in-then-out
• highlight-red / highlight-green
• fade-up (slide up while fading in)
• grow / shrink

<!-- .element: class="fragment" data-fragment-index="1" -->

Use the .slide: directive in an HTML comment to apply custom backgrounds to specific slides. You can use colors, gradients, images, or even interactive iframes.

• Color/Hex: <!-- .slide: data-background="#F8CB9E" -->
• Iframe/Website: <!-- .slide: data-background-iframe="https://miaoyan.app/" -->
• Interactive Background: <!-- .slide: data-background-interactive -->

macOS Builds

• App Store: Signed and uploaded by maintainers. Sparkle is excluded via #if !APPSTORE.
• Direct Downloads: Run bash scripts/build.sh to produce a zipped .app.
• Appcast Updates: The Sparkle appcast.xml is updated using scripts/release-ci/update_appcast.sh (requires Sparkle EdDSA private key).

Versioning Requirement

The following three version identifiers must remain aligned, or CI will reject the push:

1. Git tag (e.g., Vx.y.z)
2. MARKETING_VERSION
3. CURRENT_PROJECT_VERSION

MiaoYan supports LaTeX for both block-level and inline mathematical formulas.

$$E = mc^2$$

$\pi \approx 3.14159$

$$\sum_{i=1}^{n} x_i = \frac{n(n+1)}{2}$$