Markdown Comments: Syntax & Private Notes Guide

%%This is a private inline comment%%

%%
Multi-line private drafting comment
%%

When drafting technical specifications, synthesizing interviews, writing essays, or organizing meeting agendas, authors frequently need to leave private notes to themselves.

You might want to record unresolved questions, draft alternate phrasing, keep raw interview timestamps, or store reminder checklists that should never appear in published documentation or shared client exports.

Markdown provides two distinct methods for embedding private commentary: Obsidian double-percent comments (%%) and standard HTML comment tags (<!-- -->).

Obsidian comment syntax: %%comment%%

In Obsidian and Oyma, comments are created by wrapping text in double percent symbols (%%):

Inline comments

The local speech pipeline processes audio at 16kHz %%Verify sample rate with Alex%% on Apple Silicon.

In the rendered preview and exported documents, the text between %% is completely hidden, displaying: The local speech pipeline processes audio at 16kHz on Apple Silicon.

Multi-line comment blocks

For extensive author notes, alternate drafts, or internal checklists, use a multi-line comment block:

# Q4 Strategy Execution Plan

We are expanding local on-device capabilities throughout Q4.

%%
Action items before publishing:
1. Re-verify competitor pricing in src/data/competitors/.
2. Check Gate 13 uniqueness across new guides.
3. Confirm audio buffer allocation with engineering lead.
%%

The following deliverables are scheduled for immediate release.

Everything between the opening %% and closing %% is hidden from the rendered document.

Standard HTML comment syntax: <!-- comment -->

In standard CommonMark and GitHub Flavored Markdown (GFM), HTML comments are the universal method for hiding text:

<!-- This is an HTML comment that works across all Markdown engines -->
The meeting began promptly at 10:00 AM.
<!-- Need to follow up with Jordan regarding budget numbers -->

Because CommonMark parsers ignore standard HTML comment blocks, this text is stripped from the rendered output in all tools.

Comparing Obsidian comments vs HTML comments

Security notice: If you export a document to public HTML using standard tools, HTML comments (<!-- -->) remain in the page source and can be viewed via browser developer tools. In contrast, Obsidian comments (%%) are completely omitted from the HTML output, ensuring confidential notes remain strictly private.

Working with comments in Oyma

In Oyma on macOS:

• In the live-preview editor, comments are styled with dimmed, distinct syntax highlighting when editing.
• When you switch to Reading Mode or export to PDF, Word, or HTML, all comments are excluded automatically.
• All comments reside directly in your local .md files on disk, ensuring zero data loss and total file transparency.

Frequently asked questions

What is the syntax for comments in Obsidian and Oyma?

Enclose the comment text within double percent signs (`%%comment%%`). Comments can be inline within a paragraph or span multiple lines. They are completely hidden in reading mode and stripped during PDF and HTML export.

What is the standard CommonMark method for adding comments?

Standard CommonMark uses HTML comment tags: ``. HTML comments are supported universally by all Markdown parsers and are not displayed in rendered HTML.

Are comments indexed by full-text search in Oyma?

Yes. Because comments remain plain text on disk, SQLite full-text search indexes comment text, allowing you to find private annotations and research reminders instantly.

Can comments contain other Markdown formatting?

Yes. Inside a comment block, you can write any text, links, or syntax without affecting the rendered document. The entire comment block is hidden from the rendered view.