### Build and Install Debug QuickLook

Source: https://github.com/xykong/flux-markdown/blob/master/docs/debug/DEBUG_QUICKLOOK_WINDOW_SHRINK.md

Builds and installs a debug version of QuickLook with logging enabled. Ensure you are in the correct project directory.

```bash
# 1. Build and install Debug version
cd /Users/happyelements/Documents/git/markdown-quicklook
./scripts/install.sh Debug true
```

--------------------------------

### Install Dependencies for Web Renderer

Source: https://github.com/xykong/flux-markdown/blob/master/docs/dev/DEVELOPMENT.md

Navigate to the web-renderer directory and install its npm dependencies.

```bash
cd web-renderer
npm install
```

--------------------------------

### Start Log Collection with Custom Output

Source: https://github.com/xykong/flux-markdown/blob/master/docs/debug/DEBUG_QUICKLOOK_WINDOW_SHRINK.md

Starts collecting QuickLook window logs and allows specifying a custom output directory for the log files. Use the --output flag followed by the desired path.

```bash
# Or specify custom output directory
./scripts/collect-quicklook-window-logs.sh --output ./logs
```

--------------------------------

### Build FluxMarkdown from Source

Source: https://github.com/xykong/flux-markdown/blob/master/README.md

Clone the repository, navigate to the directory, and run the installation command.

```bash
git clone https://github.com/xykong/flux-markdown.git
cd flux-markdown
make install
```

--------------------------------

### Install FluxMarkdown with Homebrew

Source: https://github.com/xykong/flux-markdown/blob/master/README.md

Use this command to install FluxMarkdown via Homebrew, the recommended installation method.

```bash
brew install --cask xykong/tap/flux-markdown
```

--------------------------------

### Install tex2typst Dependency

Source: https://github.com/xykong/flux-markdown/blob/master/docs/superpowers/plans/2026-05-12-typst-math-rendering.md

Installs the tex2typst library, used for transpiling Typst to LaTeX in the QuickLook environment. This is a prerequisite for the lightweight rendering path.

```bash
cd web-renderer && npm install tex2typst
```

--------------------------------

### Shell Command for Installation and Cache Refresh

Source: https://github.com/xykong/flux-markdown/blob/master/docs/assets/demo.md

Provides the Homebrew command to install FluxMarkdown and the command to refresh the QuickLook cache.

```bash
brew install --cask xykong/tap/flux-markdown

# Refresh QuickLook cache
qlmanage -r
```

--------------------------------

### Flowchart Example

Source: https://github.com/xykong/flux-markdown/blob/master/benchmark/fixtures/05-mermaid.md

Demonstrates a basic flowchart with decision points and branching logic.

```mermaid
flowchart TD
    A([Start]) --> B{User authenticated?}
    B -->|No| C[Redirect to login]
    C --> D[Show login form]
    D --> E{Valid credentials?}
    E -->|No| F[Show error]
    F --> D
    E -->|Yes| G[Generate JWT]
    G --> H[Set cookie]
    B -->|Yes| I{Token expired?}
    I -->|Yes| J[Refresh token]
    J --> K{Refresh valid?}
    K -->|No| C
    K -->|Yes| L[Issue new token]
    L --> M[Continue request]
    I -->|No| M
    H --> M
    M --> N([End])
```

--------------------------------

### Example Log Output

Source: https://github.com/xykong/flux-markdown/blob/master/docs/user/TROUBLESHOOTING.md

Expected log messages indicating that the custom preview extension is active and processing files.

```text
MarkdownPreview: viewDidLoad called
MarkdownPreview: preparePreviewOfFile called for: /path/to/file.md
```

--------------------------------

### Install XcodeGen for Swift Extension

Source: https://github.com/xykong/flux-markdown/blob/master/docs/dev/DEVELOPMENT.md

Install the XcodeGen tool using Homebrew, a prerequisite for generating the Swift project.

```bash
brew install xcodegen
```

--------------------------------

### Singleton Pattern Example

Source: https://github.com/xykong/flux-markdown/blob/master/benchmark/fixtures/07-mixed.md

Illustrates the Singleton design pattern in a table format, showing a code snippet for its implementation and a common use case.

```text
| Pattern | Code |
|---------|------|
| Singleton | `instance = new Cls()` | Shared state |
```

--------------------------------

### KaTeX Block Equation Example

Source: https://github.com/xykong/flux-markdown/blob/master/docs/user/HELP.md

An example of a block-level KaTeX equation for rendering mathematical formulas in Markdown.

```tex
\int_a^b f(x)\,dx
```

--------------------------------

### Verify Extension Installation

Source: https://github.com/xykong/flux-markdown/blob/master/docs/testing/TESTING.md

Checks if the Markdown Quick Look extension is registered with the system. This helps troubleshoot loading issues.

```bash
qlmanage -m | grep -i markdown
```

--------------------------------

### Run Layer 1 Benchmark

Source: https://github.com/xykong/flux-markdown/blob/master/openspec/changes/archive/2026-02-21-perf-hljs-tree-shaking/tasks.md

Execute the JavaScript benchmark to compare cold start duration against a baseline.

```bash
cd benchmark/js-bench && node bench.mjs
```

--------------------------------

### Install typst.ts Ecosystem Dependencies

Source: https://github.com/xykong/flux-markdown/blob/master/docs/superpowers/plans/2026-05-12-typst-math-rendering.md

Installs the necessary packages from the typst.ts ecosystem, including the core library, web compiler, and renderer. These are required for the full WASM-based rendering in the Host App.

```bash
cd web-renderer && npm install @myriaddreamin/typst.ts @myriaddreamin/typst-ts-web-compiler @myriaddreamin/typst-ts-renderer
```

--------------------------------

### State Diagram Example

Source: https://github.com/xykong/flux-markdown/blob/master/benchmark/fixtures/05-mermaid.md

Visualizes the different states an object or system can be in and the transitions between them.

```mermaid
stateDiagram-v2
    [*] --> Draft

    Draft --> InReview : submit()
    Draft --> Archived : archive()

    InReview --> Draft : requestChanges()
    InReview --> Approved : approve()
    InReview --> Rejected : reject()

    Approved --> Published : publish()
    Approved --> Draft : reopen()

    Published --> Archived : archive()
    Published --> Draft : unpublish()

    Rejected --> Draft : reopen()
    Rejected --> Archived : archive()

    Archived --> [*]

    state InReview {
        [*] --> PendingReview
        PendingReview --> UnderReview : assignReviewer()
        UnderReview --> PendingReview : unassign()
    }
```

--------------------------------

### Start QuickLook Log Collection

Source: https://github.com/xykong/flux-markdown/blob/master/docs/debug/DEBUG_QUICKLOOK_WINDOW_SHRINK.md

Initiates log collection for QuickLook window events. This script captures detailed debugging information. Logs are saved to a timestamped file.

```bash
# 3. Start log collection
./scripts/collect-quicklook-window-logs.sh
```

--------------------------------

### Factory Pattern Example

Source: https://github.com/xykong/flux-markdown/blob/master/benchmark/fixtures/07-mixed.md

Demonstrates the Factory design pattern within a table, providing a code snippet and its typical use case for object creation.

```text
| Pattern | Code |
|---------|------|
| Factory | `createObj(type)` | Polymorphism |
```

--------------------------------

### Uninstall Official and Install Tap Version

Source: https://github.com/xykong/flux-markdown/blob/master/docs/release/HOMEBREW_SUBMISSION.md

This command sequence is used to switch from the official Homebrew cask version to the tap version. It first uninstalls the official version and then installs the complete version from the tap.

```bash
brew uninstall --cask flux-markdown
brew install --cask xykong/tap/flux-markdown
```

--------------------------------

### Observer Pattern Example

Source: https://github.com/xykong/flux-markdown/blob/master/benchmark/fixtures/07-mixed.md

Shows the Observer design pattern in a table, including a code snippet for event handling and its application.

```text
| Pattern | Code |
|---------|------|
| Observer | `emitter.on('evt', fn)` | Events |
```

--------------------------------

### Elixir Hello Function

Source: https://github.com/xykong/flux-markdown/blob/master/Tests/fixtures/feature-validation.md

An Elixir module with a greet function and an example of its usage.

```elixir
defmodule Hello do
  def greet(name), do: "Hello, #{name}!"
end
IO.puts Hello.greet("Elixir")
```

--------------------------------

### Gantt Chart Example

Source: https://github.com/xykong/flux-markdown/blob/master/benchmark/fixtures/05-mermaid.md

Represents a project schedule, showing tasks, their durations, dependencies, and milestones over time.

```mermaid
gantt
    title FluxMarkdown Development Timeline
    dateFormat  YYYY-MM-DD
    section Architecture
    Design spec           :done, arch1, 2024-01-01, 2024-01-07
    Review & approval     :done, arch2, after arch1, 5d
    section Core Renderer
    markdown-it setup     :done, core1, 2024-01-08, 5d
    Syntax highlighting   :done, core2, after core1, 7d
    KaTeX integration     :done, core3, after core2, 5d
    Mermaid integration   :done, core4, after core3, 7d
    section Swift Bridge
    WKWebView setup       :done, swift1, 2024-01-15, 5d
    JS bridge protocol    :done, swift2, after swift1, 5d
    File monitoring       :done, swift3, after swift2, 3d
    section Features
    TOC panel             :done, feat1, 2024-02-01, 7d
    Search functionality  :done, feat2, after feat1, 7d
    Zoom & scroll memory  :done, feat3, after feat2, 5d
    section Performance
    Baseline measurement  :active, perf1, 2025-02-01, 7d
    JS layer optimization :perf2, after perf1, 14d
    Swift layer opt       :perf3, after perf2, 7d
    section Release
    Beta testing          :2025-03-01, 14d
    v2.0 release          :milestone, 2025-03-15, 0d
```

--------------------------------

### Definition List Example

Source: https://github.com/xykong/flux-markdown/blob/master/docs/dev/renderer/RENDERER_MARKDOWN_IT_PLUGIN_ROADMAP.md

Demonstrates the common input format for definition lists, which are often used for parameter explanations or glossaries in external documents. This syntax is supported by the `markdown-it-deflist` plugin.

```markdown
Term
: Definition

Parameter A
: Explains A
```

--------------------------------

### Find All Resize Events in Logs

Source: https://github.com/xykong/flux-markdown/blob/master/docs/debug/DEBUG_QUICKLOOK_WINDOW_SHRINK.md

Filters the QuickLook log file to show all events related to window resizing. This includes both the start and end of live resize operations, as well as the saving of the new size.

```bash
# Find all resize events
grep "windowDidEndLiveResize\|windowWillStartLiveResize" /tmp/quicklook-logs-*.log
```

--------------------------------

### Swift Code Example

Source: https://github.com/xykong/flux-markdown/blob/master/docs/assets/demo.md

A simple Swift struct demonstrating the basic structure and features of FluxMarkdown.

```swift
import Foundation

struct FluxMarkdown {
  let name = "FluxMarkdown"
  let features = ["GFM", "Mermaid", "KaTeX", "TOC", "Zoom"]
}

print("\(FluxMarkdown().name) - Ready in Finder")
```

--------------------------------

### GitHub Style Callouts/Alerts Example

Source: https://github.com/xykong/flux-markdown/blob/master/docs/dev/renderer/RENDERER_MARKDOWN_IT_PLUGIN_ROADMAP.md

Shows the common syntax for GitHub-style alerts or callouts, used to highlight notes, warnings, or tips. These can be rendered into structured elements for better readability.

```markdown
> [!NOTE]
> This is a note.

> [!WARNING]
> Danger ahead.
```

--------------------------------

### Test Markdown with Typst Math Examples

Source: https://github.com/xykong/flux-markdown/blob/master/docs/superpowers/plans/2026-05-12-typst-math-rendering.md

A sample Markdown file containing various Typst math expressions for manual verification of rendering.

```markdown
# Typst Math Test

## Basic fraction (transpiled via KaTeX)

```typst
a/b + c/d
```

## Sum notation

```typst
sum_(i=1)^n i = (n(n+1))/2
```

## Matrix

```typst
mat(1, 2; 3, 4)
```

## Integral

```typst
integral_0^1 x^2 dif x
```

## Mixed with LaTeX

Regular LaTeX still works: $E = mc^2$

$$\int_0^1 x^2 dx = \frac{1}{3}$$
```

--------------------------------

### Example of RENAMED Requirement

Source: https://github.com/xykong/flux-markdown/blob/master/openspec/AGENTS.md

Demonstrates the format for renaming a requirement, specifying the 'FROM' and 'TO' states.

```markdown
## RENAMED Requirements
- FROM: `### Requirement: Login`
- TO: `### Requirement: User Authentication`
```

--------------------------------

### JavaScript Code Block Example

Source: https://github.com/xykong/flux-markdown/blob/master/Tests/fixtures/test.markdown

Demonstrates a simple JavaScript function to greet a name and log the output. This is a standard code block.

```javascript
const greet = (name) => `Hello, ${name}!`;
console.log(greet("World"));
```

--------------------------------

### JSON Configuration Example

Source: https://github.com/xykong/flux-markdown/blob/master/docs/assets/demo.md

A JSON object representing the configuration for the FluxMarkdown application, detailing its platform and features.

```json
{
  "app": "FluxMarkdown",
  "platform": "macOS",
  "entry": "QuickLook",
  "features": ["gfm", "mermaid", "katex", "toc", "zoom", "scroll-memory"]
}
```

--------------------------------

### Image Size Syntax Example

Source: https://github.com/xykong/flux-markdown/blob/master/docs/dev/renderer/RENDERER_MARKDOWN_IT_PLUGIN_ROADMAP.md

Illustrates non-standard but popular syntax for specifying image dimensions directly within Markdown. This is useful for controlling layout and preventing oversized images in rendered documents.

```markdown
![](img.png =200x)
![](img.png =200x100)
```

--------------------------------

### Verify tex2typst Installation

Source: https://github.com/xykong/flux-markdown/blob/master/docs/superpowers/plans/2026-05-12-typst-math-rendering.md

Verifies that the tex2typst package has been installed correctly by attempting to require it in a Node.js environment. This confirms the installation was successful and the package is accessible.

```bash
cd web-renderer && node -e "require('tex2typst'); console.log('tex2typst OK')"
```

--------------------------------

### Run the Host App

Source: https://github.com/xykong/flux-markdown/blob/master/docs/testing/TESTING.md

Opens the built application. Ensure this app remains running during testing to register the Quick Look extension.

```bash
open ~/Library/Developer/Xcode/DerivedData/FluxMarkdown-*/Build/Products/Debug/FluxMarkdown.app
```

--------------------------------

### Mermaid Flowchart Example

Source: https://github.com/xykong/flux-markdown/blob/master/docs/user/HELP.md

An example of a Mermaid flowchart that can be rendered within Markdown files.

```mermaid
flowchart TD
  A["Start"] --> B["Write Markdown"] --> C["Press Space"]
```

--------------------------------

### Run Host App via Xcode

Source: https://github.com/xykong/flux-markdown/blob/master/docs/user/TROUBLESHOOTING.md

Recommended method to run the Quick Look extension. This involves generating the project, opening it in Xcode, and running the Markdown scheme.

```bash
# 1. 生成工程
make generate

# 2. 在 Xcode 中打开
open FluxMarkdown.xcodeproj

# 3. 在 Xcode 中:
#    - 选择 Markdown scheme
#    - 按 Cmd+R 运行
#    - 保持 App 运行状态

# 4. 在新终端窗口:
qlmanage -r
qlmanage -r cache
killall Finder

# 5. 测试
#    在 Finder 中选中 Tests/fixtures/feature-validation.md，按空格
```

--------------------------------

### Initialize OpenSpec Project

Source: https://github.com/xykong/flux-markdown/blob/master/openspec/AGENTS.md

Use `openspec init [path]` to initialize a new OpenSpec project in the specified directory. This sets up the necessary configuration and directory structure.

```bash
openspec init [path]           # Initialize OpenSpec
```

--------------------------------

### Markdown Link Examples

Source: https://github.com/xykong/flux-markdown/blob/master/docs/debug/DEBUG_PERCENT_ENCODED_LINK_NAVIGATION.md

These markdown examples demonstrate links with spaces, both encoded and unencoded, which are intended to link to files.

```markdown
[Open notes](my%20notes.md)
[Open notes](my notes.md)
```

--------------------------------

### Recommended Image Practices

Source: https://github.com/xykong/flux-markdown/blob/master/docs/history/images/IMAGE_DISPLAY_BEHAVIOR.md

Demonstrates recommended ways to include images using relative paths, subdirectories, HTTPS for network images, and Base64 encoding for small icons.

```markdown
<!-- 相对路径：最可靠 -->
![Logo](./images/logo.png)

<!-- 子目录相对路径 -->
![Screenshot](./screenshots/app.png)

<!-- 网络图片：使用 HTTPS -->
![GitHub](https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png)

<!-- Base64 内嵌：适合小图标 -->
![Icon](data:image/png;base64,iVBORw0KG...)
```

--------------------------------

### Open QuickLook Preview

Source: https://github.com/xykong/flux-markdown/blob/master/Tests/TEST_LINK_ALERT.md

Use this command to open a Markdown file in QuickLook preview mode for testing link behavior.

```bash
qlmanage -p Tests/test-link-navigation.md
```

--------------------------------

### Build Web Renderer

Source: https://github.com/xykong/flux-markdown/blob/master/docs/dev/DEVELOPMENT.md

Navigate to the web-renderer directory and build the project. This generates an 'dist/index.html' file with inlined assets.

```bash
cd web-renderer
npm run build
```

--------------------------------

### Project Structure Overview

Source: https://github.com/xykong/flux-markdown/blob/master/AGENTS.md

Provides a high-level view of the project's directory structure, including the Makefile, XcodeGen config, Swift sources, and the web-renderer.

```bash
.
├── Makefile            # Main build orchestrator (npm + xcodegen + xcodebuild)
├── project.yml         # XcodeGen config (Generates .xcodeproj - DO NOT EDIT PROJECT DIRECTLY)
├── Sources/
│   ├── Markdown/       # Host App (SwiftUI) - Container for extension
│   └── MarkdownPreview/# Extension (AppKit) - WKWebView, QLPreviewingController
├── web-renderer/       # Rendering Engine (TypeScript/Vite) -> See web-renderer/AGENTS.md
└── scripts/            # Versioning and packaging scripts
```

--------------------------------

### Markdown Base64 Image Examples

Source: https://github.com/xykong/flux-markdown/blob/master/docs/history/images/BASE64_FIX_SUMMARY.md

Demonstrates how to embed PNG and SVG images using Base64 encoding directly within Markdown syntax. Also shows an example of an HTML img tag with a Base64 source.

```markdown
# Base64 图片示例

## PNG 图片
![Red Pixel](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAIAAAACUFjqAAAAEklEQVR4nGP4z8CAB+GTG8HSALfKY52fTcuYAAAAAElFTkSuQmCC)

## SVG 图片  
![Red Square](data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTAwIiBoZWlnaHQ9IjEwMCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KICA8cmVjdCB3aWR0aD0iMTAwIiBoZWlnaHQ9IjEwMCIgZmlsbD0icmVkIi8+Cjwvc3ZnPg==)

## HTML 语法
<img src="data:image/png;base64,..." width="100" height="100">
```

--------------------------------

### Run Tests for Web Renderer

Source: https://github.com/xykong/flux-markdown/blob/master/docs/dev/DEVELOPMENT.md

Navigate to the web-renderer directory and execute the test suite using npm.

```bash
cd web-renderer
npm test
```

--------------------------------

### Syntax Highlighting: Full Import vs. Optimized

Source: https://github.com/xykong/flux-markdown/blob/master/benchmark/fixtures/07-mixed.md

Compares the bundle size and initialization time for a full highlight.js import versus an optimized approach using core and selective language registration.

```typescript
// Current: full hljs import (~400KB)
import hljs from 'highlight.js';

// Optimized: core + selective language registration
import hljs from 'highlight.js/lib/core';
import javascript from 'highlight.js/lib/languages/javascript';
hljs.registerLanguage('javascript', javascript);
```

--------------------------------

### Example of ADDED Requirement in auth/spec.md

Source: https://github.com/xykong/flux-markdown/blob/master/openspec/AGENTS.md

Illustrates adding a new requirement for Two-Factor Authentication.

```markdown
## ADDED Requirements
### Requirement: Two-Factor Authentication
...
```

--------------------------------

### Example of ADDED Requirement in notifications/spec.md

Source: https://github.com/xykong/flux-markdown/blob/master/openspec/AGENTS.md

Illustrates adding a new requirement for OTP email notification.

```markdown
## ADDED Requirements
### Requirement: OTP Email Notification
...
```

--------------------------------

### Find All Persistence Writes in Logs

Source: https://github.com/xykong/flux-markdown/blob/master/docs/debug/DEBUG_QUICKLOOK_WINDOW_SHRINK.md

Searches the QuickLook log file for entries related to saving window sizes. This helps determine when and why window dimensions are being persisted to storage.

```bash
# Find all persistence writes
grep "Saving size\|Saving final size" /tmp/quicklook-logs-*.log
```

--------------------------------

### Project Directory Structure

Source: https://github.com/xykong/flux-markdown/blob/master/docs/history/reorg/REORGANIZATION_SUMMARY.md

Illustrates the reorganized directory structure of the project, showing the placement of documentation, tests, scripts, sources, and the web renderer.

```bash
.
├── docs/
│   ├── features/
│   │   └── ZOOM.md
│   ├── testing/
│   │   └── TESTING.md
│   ├── ARCHITECTURE.md
│   ├── DEBUG_*.md
│   ├── DESIGN_*.md
│   ├── DEVELOPMENT.md
│   ├── OPTIMIZATION_ROADMAP.md
│   ├── RELEASE_PROCESS.md
│   ├── RENDERER_MARKDOWN_IT_PLUGIN_ROADMAP.md
│   ├── THIRD_PARTY_LICENSES.md
│   └── TROUBLESHOOTING.md
├── Tests/
│   ├── fixtures/
│   │   ├── feature-validation.md
│   │   ├── images-test.md
│   │   └── zoom-test.md
│   ├── MarkdownTests/
│   │   ├── ResourceLoadingTests.swift
│   │   └── WindowSizePersistenceTests.swift
│   └── scripts/
│       └── watch-link-clicks.sh
├── scripts/
│   ├── analyze-pr.sh
│   ├── create_dmg.sh
│   ├── delete_release.sh
│   ├── generate_large_md.sh
│   ├── install.sh
│   ├── release.sh
│   ├── update-homebrew-cask.sh
│   └── verify_truncation.sh
├── Sources/
├── web-renderer/
├── README.md
├── README_ZH.md
├── CHANGELOG.md
├── LICENSE
├── AGENTS.md
├── Makefile
└── project.yml

```

--------------------------------

### Class Diagram Example

Source: https://github.com/xykong/flux-markdown/blob/master/benchmark/fixtures/05-mermaid.md

Defines a set of classes with their attributes, methods, and relationships, including inheritance and associations.

```mermaid
classDiagram
    class Entity {
        +UUID id
        +DateTime createdAt
        +DateTime updatedAt
        +validate() bool
        +toJSON() string
    }

    class User {
        +string email
        +string passwordHash
        +string displayName
        +UserRole role
        +bool isActive
        +updatePassword(newHash: string)
        +deactivate()
    }

    class Organization {
        +string name
        +string slug
        +Plan plan
        +int memberCount
        +addMember(user: User)
        +removeMember(userId: UUID)
        +upgradePlan(plan: Plan)
    }

    class Membership {
        +UUID userId
        +UUID organizationId
        +MemberRole role
        +DateTime joinedAt
        +changeRole(role: MemberRole)
    }

    class Document {
        +string title
        +string content
        +string contentType
        +UUID authorId
        +UUID organizationId
        +bool isPublic
        +publish()
        +archive()
        +fork() Document
    }

    class Comment {
        +string body
        +UUID authorId
        +UUID documentId
        +UUID parentId
        +edit(body: string)
        +delete()
    }

    Entity <|-- User
    Entity <|-- Organization
    Entity <|-- Document
    Entity <|-- Comment
    Entity <|-- Membership

    User "1" --> "many" Membership
    Organization "1" --> "many" Membership
    User "1" --> "many" Document : authors
    Organization "1" --> "many" Document : owns
    Document "1" --> "many" Comment
    Comment "0..1" --> "many" Comment : replies
```

--------------------------------

### Sequence Diagram Example

Source: https://github.com/xykong/flux-markdown/blob/master/benchmark/fixtures/05-mermaid.md

Illustrates a sequence of interactions between different participants in a system, including conditional logic.

```mermaid
sequenceDiagram
    participant U as User
    participant F as Frontend
    participant A as API Gateway
    participant S as Auth Service
    participant D as Database
    participant C as Cache

    U->>F: Click "Login"
    F->>A: POST /auth/login {credentials}
    A->>S: Validate credentials
    S->>C: GET user:{email}
    alt Cache hit
        C-->>S: Return cached user
    else Cache miss
        S->>D: SELECT * FROM users WHERE email=?
        D-->>S: User record
        S->>C: SET user:{email} TTL=300
    end
    S->>S: Verify password hash
    S->>S: Generate JWT (15min) + Refresh (7d)
    S-->>A: {accessToken, refreshToken}
    A-->>F: 200 OK {tokens}
    F->>F: Store tokens securely
    F-->>U: Redirect to dashboard
```

--------------------------------

### Generate Swift Project

Source: https://github.com/xykong/flux-markdown/blob/master/docs/dev/DEVELOPMENT.md

Run the make generate command to build the web renderer and generate the FluxMarkdown.xcodeproj from project.yml.

```bash
make generate
```

--------------------------------

### Build Swift App

Source: https://github.com/xykong/flux-markdown/blob/master/docs/dev/DEVELOPMENT.md

Run the make app command to build the Swift application. Alternatively, open the generated FluxMarkdown.xcodeproj in Xcode.

```bash
make app
```

--------------------------------

### Decorator Pattern Example

Source: https://github.com/xykong/flux-markdown/blob/master/benchmark/fixtures/07-mixed.md

Presents the Decorator design pattern in a table, with a code snippet and its use case in Aspect-Oriented Programming (AOP).

```text
| Pattern | Code |
|---------|------|
| Decorator | `@memoize fn()` | AOP |
```

--------------------------------

### Troubleshoot Cached Versions

Source: https://github.com/xykong/flux-markdown/blob/master/docs/testing/TESTING.md

Commands to kill the Finder process and reset the Quick Look cache. Use this when encountering issues with old versions being displayed.

```bash
killall Finder
qlmanage -r
qlmanage -r cache
```

--------------------------------

### List Specifications with OpenSpec

Source: https://github.com/xykong/flux-markdown/blob/master/openspec/AGENTS.md

Use `openspec list --specs` to enumerate all specifications within the project. This is useful for understanding existing capabilities and identifying potential duplicates.

```bash
openspec list --specs          # List specifications
```

--------------------------------

### Markdown Fixture Example

Source: https://github.com/xykong/flux-markdown/blob/master/docs/testing/TESTING.md

A sample Markdown file used for testing various features including front matter, callouts, code highlighting, and diagrams.

```markdown
# Markdown Quick Look Test

## Basic Markdown
**Bold**, *Italic*, ~~Strikethrough~~

## Code Block
```javascript
const hello = () => {
  console.log("Hello, World!");
};
```

## Math (KaTeX)
Inline: $E=mc^2$

Block:
$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

## Mermaid Diagram
```mermaid
graph TD;
    A[Start] --> B{Is it working?};
    B -->|Yes| C[Great!];
    B -->|No| D[Debug];
```

## Task List
- [x] Build project
- [x] Run tests
- [ ] Deploy
```

--------------------------------

### Build from Tag

Source: https://github.com/xykong/flux-markdown/blob/master/docs/release/RELEASE_WORKFLOW_DESIGN.md

Checks out the specific Git tag to ensure the build process uses the exact code snapshot intended for the release. Remember to return to the master branch afterwards.

```bash
# Build should checkout the tag
git checkout "v$FULL_VERSION"
make dmg
git checkout master  # return to master
```

--------------------------------

### Build Project

Source: https://github.com/xykong/flux-markdown/blob/master/openspec/changes/archive/2026-02-21-perf-hljs-tree-shaking/tasks.md

Run the build command to ensure successful compilation and check for TypeScript errors.

```bash
npm run build
```

--------------------------------

### Incorrect Scenario Formatting in Specs

Source: https://github.com/xykong/flux-markdown/blob/master/openspec/AGENTS.md

Highlights incorrect markdown formatting for scenarios in spec files, showing examples to avoid, such as using bullets or incorrect header levels.

```markdown
- **Scenario: User login**  ❌
**Scenario**: User login     ❌
### Scenario: User login      ❌
```

--------------------------------

### Test Extension with qlmanage

Source: https://github.com/xykong/flux-markdown/blob/master/docs/user/TROUBLESHOOTING.md

Command to directly invoke the Quick Look extension for a specific file using qlmanage. This bypasses the standard registration mechanism for testing purposes.

```bash
qlmanage -p Tests/fixtures/feature-validation.md
```

--------------------------------

### Typst Fence Detection Test

Source: https://github.com/xykong/flux-markdown/blob/master/docs/superpowers/plans/2026-05-12-typst-math-rendering.md

Tests if Typst code blocks are correctly identified and transformed into placeholder divs by the markdown-it highlighter. This setup is used for integration testing.

```typescript
import MarkdownIt from 'markdown-it';

describe('Typst fence detection in markdown-it', () => {
    test('typst code block produces placeholder div', () => {
        // Simulate the highlight function behavior
        const md = new MarkdownIt({
            highlight: function (str: string, lang: string): string {
                if (lang === 'typst' || lang === 'typst-math') {
                    return '<div class="typst-placeholder" data-typst-source="' +
                        str.replace(/"/g, '&quot;').replace(/\n/g, '&#10;') + 
                        '"><div class="typst-loading">Rendering Typst…</div></div>';
                }
                return '';
            }
        });

        const input = '```typst\nsum_(i=1)^n i = (n(n+1))/2\n```';
        const html = md.render(input);
        expect(html).toContain('typst-placeholder');
        expect(html).toContain('data-typst-source');
        expect(html).toContain('sum_(i=1)^n');
    });

    test('typst-math alias also works', () => {
        const md = new MarkdownIt({
            highlight: function (str: string, lang: string): string {
                if (lang === 'typst' || lang === 'typst-math') {
                    return '<div class="typst-placeholder" data-typst-source="' +
                        str.replace(/"/g, '&quot;').replace(/\n/g, '&#10;') + 
                        '"></div>';
                }
                return '';
            }
        });

        const input = '```typst-math\nalpha + beta\n```';
        const html = md.render(input);
        expect(html).toContain('typst-placeholder');
    });

    test('regular code blocks are not affected', () => {
        const md = new MarkdownIt({
            highlight: function (str: string, lang: string): string {
                if (lang === 'typst' || lang === 'typst-math') {
                    return '<div class="typst-placeholder"></div>';
                }
                return '';
            }
        });

        const input = '```javascript\nconsole.log("hello")\n```';
        const html = md.render(input);
        expect(html).not.toContain('typst-placeholder');
    });
});

```

--------------------------------

### Find All Screen Change Events in Logs

Source: https://github.com/xykong/flux-markdown/blob/master/docs/debug/DEBUG_QUICKLOOK_WINDOW_SHRINK.md

Searches the QuickLook log file for all occurrences of screen environment change events. This command helps identify when display configurations or window screen assignments were altered.

```bash
# Find all screen change events
grep "didChangeScreen\|applicationDidChangeScreenParameters" /tmp/quicklook-logs-*.log
```

--------------------------------

### QuickLook Zoom Test Command

Source: https://github.com/xykong/flux-markdown/blob/master/docs/features/ZOOM.md

This bash command opens a specific Markdown file in Finder and instructs the user to press Space to initiate a QuickLook preview for testing zoom functionality.

```bash
open -a Finder Tests/fixtures/zoom-test.md
# Select file and press Space
# Try: Hold CMD + Scroll, Pinch, or CMD + '+'
```