HydroMark User Manual (English)

Applies to: Version 1.1.x Platform: Windows + Microsoft OneNote 2013 / 2016 / 2019 / 2021 / Microsoft 365 (desktop) Ribbon tab: HydroMark

Table of Contents

1. Introduction
2. System Requirements & Installation
3. Quick Start
4. The Ribbon
5. Rendering & Source Mode
6. Markdown Syntax
7. Code Blocks & Syntax Highlighting
8. Math Formulas
9. Mermaid Diagrams
10. Callouts
11. Tables
12. Slash Command Palette
13. AI Assistant
14. Page Management & TOC
15. Themes & Appearance
16. Import & Export
17. Trial, License & Purchase
18. Customizing Shortcuts
19. Keyboard Shortcuts Reference
20. Languages
21. FAQ & Troubleshooting
22. Appendix: Markdown Cheat Sheet

1. Introduction

HydroMark is a Markdown add-in for Microsoft OneNote. Write Markdown directly in OneNote, press Enter, and it instantly renders into native OneNote content — with syntax-highlighted code, math formulas, Mermaid diagrams, callouts, adjustable table widths, and a built-in AI Assistant that executes add-in actions for you.

Key Features

2. System Requirements & Installation

System Requirements

• Windows 7 or later
• Microsoft OneNote 2013 or later (desktop edition; Mac and mobile versions are not supported)
• .NET Framework 4.8 or later

Installation

1. Download the installer. The installer is an all-in-one, multi-language build that automatically adapts to both 32-bit and 64-bit OneNote — no need to pick an architecture.
2. Run the installer and follow the wizard.
3. Verify: launch OneNote — the HydroMark tab should appear in the ribbon with all Markdown tools.

Uninstall

1. Open Control Panel → Programs and Features
2. Find HydroMark
3. Click Uninstall, then restart OneNote

3. Quick Start

Step 1: Enable auto render

1. Open OneNote and click the HydroMark tab
2. In the Render group, click Auto Render so it shows the ✔ state

Step 2: Write Markdown

Type Markdown directly on the page, for example:

# Heading 1
This is **bold** text, this is *italic* text.

- Item 1
- Item 2

Step 3: Render instantly

Press Enter when a line is finished and it renders immediately. When typing with an IME (Chinese, Japanese, Korean...), the Enter that confirms candidate words does not trigger rendering — type freely.

Step 4: View and edit the source

• Press Ctrl+, to switch the whole page to Markdown source for editing; press again to render back
• Or press Ctrl+Space anytime to render / un-render just the current line

4. The Ribbon

After installation, a HydroMark tab appears in the OneNote ribbon with 9 groups:

4.1 Render

4.2 Import/Export

4.3 Code

4.4 Page

Page width options:

4.5 Table

4.6 Theme

💡 Auto-follow OneNote dark mode: as long as you have never manually picked a Code Theme or Panel Theme, they automatically follow OneNote's dark/light mode in real time (syntax highlight colors included). Once you pick a theme manually, it stays fixed.

4.7 AI

4.8 Settings

4.9 Website / Help / About

5. Rendering & Source Mode

HydroMark provides four rendering paths for different situations:

Key points:

• Ctrl+Space is a line-level bidirectional toggle (Markdown ↔ rendered) — most convenient for editing already-rendered content
• Ctrl+, is page-level source mode — best for bulk edits or pasting Markdown from elsewhere
• To change rendered content: put the cursor back on the line, press Ctrl+Space to un-render, edit, then render again

6. Markdown Syntax

6.1 Headings

Six heading levels via #:

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

6.2 Emphasis

**bold**            → bold
*italic*            → italic
~~strikethrough~~   → strikethrough
==highlighted==     → highlight marker
**_bold italic_**   → bold italic

6.3 Inline code

This is `inline code`

Rendered as monospaced text on a gray background.

6.4 Blockquote

> This is a quote
> spanning multiple lines

6.5 Horizontal rule

All three work:

---
***
___

6.6 Unordered list

- Item A
- Item B

* and + also work as list markers.

6.7 Ordered list

1. First step
2. Second step

6.8 Task lists

Both English and Chinese formats are supported:

- [ ] Unfinished task
- [x] Finished task

- 【】Unfinished task (Chinese style)
- 【√】Finished task

Unfinished tasks render as ☐; finished ones as ☑ with strikethrough and gray text.

6.9 Links

[Display text](https://example.com)

6.10 Images

![Alt text](image path)

Both local paths and web URLs are supported. You can also insert via the slash command and pick a local image file.

6.11 Tables

| Name | Age | City |
| --- | --- | --- |
| Alice | 28 | Beijing |
| Bob | 32 | Shanghai |

Renders as a native OneNote table; use Alt+C / Alt+R to add columns/rows afterwards. The --- separator row is required — it tells HydroMark this is a table.

6.12 Footnotes

This is a footnote reference[^1], and a second one[^note].

[^1]: Content of the first footnote.
[^note]: Footnote IDs can be longer names.

[^id] renders as a superscript number; definition lines render as small-print notes.

7. Code Blocks & Syntax Highlighting

Basic usage

Wrap code in triple backticks with a language tag:

```csharp
public class Hello
{
    public static void Main()
    {
        Console.WriteLine("Hello, World!");
    }
}
```

Supported languages

200+ programming languages, including:

Code block operations

• Copy code: select a code block, click Copy on the ribbon
• Clear code: click Clear
• Switch language: pick from the Code Language dropdown (before or after rendering)

8. Math Formulas (Professional)

LaTeX formulas render natively in OneNote.

Inline formulas

Wrapped in single $:

Einstein's famous equation $E = mc^2$ changed physics.

Block formulas

Wrapped in double $$, centered on their own lines:

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

Examples

⚠️ Note: formula delimiters must be paired ($...$ or $$...$$); unbalanced ones will not render.

9. Mermaid Diagrams (Professional)

26+ Mermaid diagram types are supported. Diagrams render as images embedded in OneNote; press Ctrl+Space to return to source, edit, then render again.

Basic usage

```mermaid
flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Do it]
    B -->|No| D[End]
```

Common diagram types

See the Mermaid official documentation for full syntax.

10. Callouts (Professional)

Four colored callout styles, using @@ markers (marker on its own line, content, then closing @@):

@@INFO
An information callout (blue)
@@

@@WARN
A warning callout (yellow)
@@

@@IMPORTANT
An important callout (orange)
@@

@@ERROR
An error callout (red)
@@

Callouts are a HydroMark-specific extension; standard Markdown does not support them. Exported .md files keep the original markers.

11. Tables

Creating tables

Create tables with Markdown syntax (see 6.11), then press Enter or F5. Tables render full-page width with evenly distributed columns by default — great for wide data tables.

Full-width ↔ content-fitted toggle

Place the cursor inside a table and press Alt+W (or the ribbon Table Width button) to switch both ways:

• Full-page width: table fills the page, columns evenly distributed — best for wide tables
• Content-fitted: table shrinks to its actual content width — best for small 2–3 column tables

The choice is persisted on the page; re-rendering the page will not reset it.

Adding rows and columns

⚠️ Make sure the cursor is inside a rendered table first.

12. Slash Command Palette

Opening

Type / (slash) on the page — the command palette pops up next to the cursor.

How to use

1. Type / to open the palette
2. Keep typing to filter directly (Chinese supports pinyin initial search, e.g. "CT" = bold) — no need to click the search box
3. Choose with arrow keys and press Enter (or click)
4. The template is inserted at the cursor; the cursor lands at the {cursor} marker
5. Press Esc to cancel

Command list

Text formatting: bold, italic, strikethrough, highlight, inline code

Headings: H1 – H6

Blocks: blockquote, code block, horizontal rule

Lists: unordered list, ordered list, task list

Callouts: info (@@INFO), warning (@@WARN), important (@@IMPORTANT), error (@@ERROR)

Formulas: inline $...$, block $$...$$

Links & media: link [](), image ![]()

Tables & diagrams: table (with separator template), Mermaid diagram code block

💡 Headings, quotes, rules, task lists and tables render immediately after insertion.

13. AI Assistant

HydroMark includes an AI sidebar: describe what you need in natural language, and the AI generates content and executes add-in actions directly on the page — it doesn't just chat, it writes into your notes.

Opening

• Click the AI Assistant ribbon button, or press Alt+A
• The sidebar docks to the right side of the OneNote window, following it as it moves or resizes — chat and edit side by side

What it can do

Sending & stopping

• Click Send to submit; click Stop anytime while the AI is answering
• Clear the whole chat history with the trash icon (asks for confirmation)

AI Model Settings

Click AI Model Settings on the ribbon (or the settings button in the sidebar):

1. Pick a provider — 15 built-in presets: OpenAI (ChatGPT), DeepSeek, Kimi (Moonshot), Zhipu GLM, Alibaba Qwen (DashScope), Tencent Hunyuan, Baidu Qianfan, ByteDance Volcano Ark, Claude, Microsoft Azure OpenAI, Grok (xAI), Google Gemini, Xiaomi, OpenRouter, and Custom (any OpenAI-compatible endpoint: proxies, vLLM, Ollama, LM Studio...)
2. Enter base URL and API key — the URL is editable; API keys are encrypted with Windows DPAPI and can only be decrypted on your machine
3. Pick a model — click "Refresh models" to fetch the latest list online, or type one manually; new models from your provider require no add-in update
4. Test connection — verify the configuration before saving
5. Save multiple model profiles and switch between them anytime

⚠️ Multimodal note: if the selected provider/model does not support image input, attached images are ignored with a notice — switch to a vision-capable model.

License requirement

• The AI Assistant requires a valid license: the trial, Basic and Professional editions all include it — activate or purchase first
• Basic can use the AI for all basic actions, but AI requests that would produce Professional-only output (diagrams / formulas / callouts / palette themes) are blocked with an upgrade notice

14. Page Management & TOC

Full-width pages

OneNote's default page width is narrow. HydroMark provides full-width pages:

• New Full Width Page (Ctrl+Shift+N): create a new full-width page in the current section
• Full Width Current Page (Ctrl+Shift+W): expand the current page's content area to full width

Page width

When rendering the whole page, pick a target width from the Page Width menu: A4 (794pt) / Letter (816pt) / A3 (1123pt) / Auto (content based).

Table of contents

HydroMark can generate a TOC from rendered headings (H1-H6):

1. Make sure the page contains rendered Markdown headings
2. Click Show TOC on the ribbon
3. The TOC appears on the page listing every heading level; click Hide TOC to remove it

15. Themes & Appearance

Three independent theme groups, all in the ribbon Theme group:

15.1 Code theme

Code block background and border: Dark / Light / Purple / Blue.

15.2 Highlight theme

Syntax coloring inside code blocks — 100+ presets (vs, github, monokai, dracula, nord, one-dark, solarized...).

15.3 Panel theme

Slash command palette colors: Dark / Light / Purple / Blue.

Auto-follow OneNote dark mode

As long as you have never manually chosen a Code Theme or Panel Theme, the add-in automatically follows OneNote's dark/light mode: when OneNote switches to dark, code blocks, the palette and highlight colors switch to dark schemes too, and back. Once you pick a theme manually, it stays fixed.

16. Import & Export

16.1 Export Markdown (F8)

Press F8 or click Export MD, then choose:

Option 1: Export to clipboard

1. Choose "Export to clipboard"
2. The page's Markdown is copied to the clipboard
3. Images are exported as local files (default: Documents\OneNoteMarkDownAddin\export-images\); a dialog reports the image count and folder

Option 2: Export to folder

1. Choose "Export to folder"
2. Pick a location and file name (defaults to the page title; duplicates get a suffix)
3. The .md file is saved as UTF-8; images go into an *image* subfolder next to the file, referenced with relative paths

💡 Export is available in the trial and in every paid edition.

16.2 Import Markdown (Ctrl+Shift+V)

1. Copy Markdown content to the clipboard (Ctrl+C)
2. Open the target OneNote page and click into the content area
3. Press Ctrl+Shift+V or click Import MD
4. The content is parsed, rendered and inserted at the cursor

⚠️ Click into the page content area (outline) first, or you'll get a "content area not found" notice.

17. Trial, License & Purchase

17.1 Trial

• The 14-day free trial starts on first use; every feature is available (Professional features and the AI Assistant included)
• Reminders pop up when 7, 3 and 1 days remain
• For licensing security the trial requires periodic online verification (at least once every 6 hours); after a long offline period you'll be asked to reconnect — access resumes immediately after
• Rolling back the system clock or deleting local trial data does not extend the trial

17.2 Licenses & editions

After the trial, purchase a license to continue. There are Basic and Professional editions, each in a Personal / Family variant, available as lifetime or annual subscription:

17.3 Activation

1. Open Settings → License on the ribbon
2. Enter the license key and email you received after purchase, click Activate
3. Once activated, the dialog shows the ✅ activated state
4. The number of devices per license is set by the edition; exceeding it shows "This license key has exceeded its activation limit"
5. When changing devices, Deactivate on the old device first, then activate on the new one

17.4 Status & invalidation

• The Settings group caption shows your current plan (Trial / Basic Lifetime / Professional Lifetime / Annual...)
• If verification fails, a dialog explains why (network or license issue) and the add-in retries automatically
• Refunded or administratively disabled licenses are invalidated automatically at the next startup verification

18. Customizing Shortcuts

Every shortcut can be remapped:

1. Open Settings → Keyboard Shortcuts
2. The list shows every shortcut (action / description / current key)
3. Double-click a row to edit, then press the new combination
4. Conflict detection prevents two actions sharing one combination
5. Set an entry to "None" to disable it; restore defaults anytime
6. Changes take effect immediately — no OneNote restart needed

19. Keyboard Shortcuts Reference

💡 All of these can be remapped in Settings → Keyboard Shortcuts.

20. Languages

HydroMark supports 9 UI languages:

The UI language follows the Office display language automatically — no manual switching. The installer is an all-in-one multi-language build; no separate language packs.

21. FAQ & Troubleshooting

Q: The HydroMark tab doesn't appear after installation

1. Restart OneNote
2. Check OneNote → File → Options → Add-ins, and make sure the HydroMark COM add-in is enabled
3. If it still doesn't show, run the installer again to repair

Q: Enter doesn't trigger rendering

1. Make sure Auto Render is enabled (shows ✔)
2. Check the Markdown syntax; paired markers (**, ~~...) must be closed
3. With an IME active, the Enter that confirms candidate words intentionally does not render; press Enter once more after the word is committed

Q: Code blocks have no syntax highlighting

1. Specify a language: ```csharp instead of a bare ```
2. Or pick the language via the ribbon Code Language dropdown

Q: A Mermaid diagram fails to render

1. Check the Mermaid syntax (semicolons, colons); verify against examples on the Mermaid website
2. Some -beta diagram types require newer Mermaid syntax
3. If it keeps failing, restart OneNote

Q: Formulas display incorrectly

1. Make sure $ / $$ pairs are balanced
2. Check the LaTeX syntax

Q: Export fails

1. Click into the page content area before exporting
2. When exporting to a folder, make sure the target path is writable

Q: The AI Assistant won't open

1. The AI Assistant requires a valid license (trial or any paid edition) — activate it under Settings → License first
2. Check the provider and API key in AI Model Settings; use "Test connection" to verify
3. AI request failures are usually an invalid API key, exhausted quota, or network issues; for proxies / self-hosted endpoints double-check the base URL

Q: Pasted images are ignored in the AI sidebar

• The selected provider or model does not support image input; switch to a vision-capable model (e.g. GPT-4o, Gemini, Claude)

Q: How do I uninstall?

1. Control Panel → Programs and Features → HydroMark → Uninstall
2. Restart OneNote afterwards

22. Appendix: Markdown Cheat Sheet

# Heading H1
## Heading H2
### Heading H3

**bold** *italic* ~~strikethrough~~ ==highlight==

`inline code`

> blockquote

- Unordered list
1. Ordered list
- [ ] Task list
- 【】Chinese task list

[Link](URL)
![Image](path)

[^1]: Footnote definition, referenced as [^1] in text

| Header | Header |
| --- | --- |
| Cell | Cell |

```code block```

$inline formula$
$$block formula$$

@@INFO / @@WARN / @@IMPORTANT / @@ERROR (callouts)