Markdown Syntax

Markdown is supported, though not every Markdown feature is included. This page explains the available options and common patterns that are not supported.

When something is marked as "not supported", you can contribute code through a pull request.

Basic formatting

Use italics, bold, and both. This works evenwithinwords. Strikethrough and underline are also supported. You can even combine these styles.

*italics*, **bold**, and ***both***.
~~strikethrough~~, ~underline~, and ~*combined*~.

Paragraphs are one long line. Each block of text becomes a single paragraph. Do not use newlines inside a paragraph unless you want line breaks, like the following message:

When you use newlines
Then a break will be added
Make your own haiku

Avoid

Using _underscores_ for emphasis (bold, italics, both) will not work.

Headings

Headings 1 through 6 are supported. Put the corresponding number of # symbols at the beginning of a line.

## Headings

Avoid

The alternate method of using a line of ------ or ====== underneath the heading is not supported.

Lists

1. Ordered lists are supported.
2. Just prefix each list item with a number and a period.

1. First Item
2. Second Item

• Unordered lists are also supported.
• Use a hyphen for each item.

- First Item
- Second Item

You can also use nested lists.

• Naughty list
1. Tyler
2. Brian
• Nice list
• Basically everyone else

- Naughty List
  1. Tyler
  2. Brian
- Nice list
  - Basically everyone else

Task lists are supported and can be nested. When you click a task to mark it complete or incomplete, the wiki is updated. If autosave is enabled, the updated wiki is also saved.

• Not done
• Done
1. Done child

- [ ] Not done
- [x] Done

Avoid

Starting the numbering of a list with any number other than 1 is not supported.

Using + or * for list items works, but they are converted to - the next time you edit the list.

Images and Links

URLs and email addresses are converted automatically: https://fidian.github.io/omniflux fidian@rumkin.com

Link to an external page: OmniFlux

[Link Text](https://example.com/)

Link to internal pages with double brackets. When the link text should be converted into the page ID, use [[Page Name]], like Changelog and Fair Comparison. When you want custom link text, put the page ID before the pipe and the label after it, like Main Page (which has no ID) and Markdown Info (page ID is markdown-syntax).

[[Changelog]] and [[Fair Comparison]]
[[|Main Page]] and [[markdown-syntax|Markdown Info]]

External image: (the "alt text" is also converted to a title)

![Octocat](https://fidian.github.io/omniflux/octocat.svg)

Linking around an external image:

[![Octocat](https://fidian.github.io/omniflux/octocat.svg)](https://fidian.github.io/omniflux/octocat.svg)

Images uploaded to the wiki can be referenced and used on any page, like this solar flare:

![Solar Flare](#solar-flare.jpg)

Avoid

Links can have titles by adding a description after the URL, but that's unsupported.

Do not use angle brackets (< and >) around a URL to turn it into a link. Similarly, URLs without http:// or https:// in front are not linked.

Reference-style links are not supported, which is where a link is used in one or more spots, but the URL is maintained elsewhere.

Uploading images into the wiki can significantly increase its size.

Code

Short passages of code can stand out by using a single backtick at the start and end of the inline passage: like this.

You can enter a block of code by having a line of three backticks in a row to start the section and another three backticks in a row to end the section. Edit this page to see many examples of embedded code blocks.

Code fences are supported and language information is preserved.

While code fences support language information, no highlighting happens by default because OmniFlux keeps the core wiki small. If you want highlighting, check out Code Highlighting for instructions.

Avoid

Code fences can specify a language, but no special highlighting happens by default.

Indenting a block of code with 4 spaces will not turn it into a code block.

Backticks within a code block are not supported.

Blockquotes

Start each line with > to have a blockquote.

This is an example.
Markdown inside is supported.

Nested blockquotes work.
Use > > (or more) at the beginning of the line.

> This is an example
>
> > Nested blockquotes work.

Avoid

Use exactly one space after each >. This parser will not convert lines with zero spaces into blockquotes. Lines with more than one space keep the extra spaces as Markdown content, which can have unintended consequences.

Tables

Standard Markdown works for tables, plus alignment is supported. Headings are required.

Tables are automatically formatted in the Markdown to align on columns for easier editing. This happens every time, so don't worry about extra whitespace or formatting while editing. OmniFlux will clean it up for you!

Markdown formatting within cells is allowed.

| Left | Center | Right |
| ---- | :----: | ----: |
| 1    |   1    |     1 |
| 10   |   10   |    10 |
| 100  |  100   |   100 |

Avoid

Nested pipe characters within a table are not supported, not even within backticks for code.

Horizontal Rules

Three or more dashes in a row on a line by itself produces this line.

---

Avoid

Avoid overusing these. Headings are usually a better way to separate content.

Custom Elements

You can add a custom element by simply including the JavaScript and HTML. See Custom Elements to learn more.

<custom-element>Hello!</custom-element>

Completely Unsupported

Embedding HTML within Markdown is not supported, except for custom elements. This is tricky because conversion needs to be accurately bidirectional. However, you can accomplish nearly the same thing using the raw-html Custom Element example.

The <del> tag isn't created when using ~~~text~~~.

Anchors, like #[jump-here], are unsupported because the wiki uses CSS-based navigation that relies on the location hash. User-generated anchors could conflict with page IDs.

Footnotes.

Rule Processing

When converting Markdown to HTML, there are a bunch of rules that need to get applied in a particular order. Also, sometimes rules need to build on themselves, such as when an image is linked. The rule processing engine is a generic way to process a string through a set of rules and have handlers decide how each interaction unfolds.

The Markdown parser first looks for block-level markup. Each time a chunk is found, that chunk is processed fully. This means the Markdown is converted to DOM elements for that block-level element and any inline elements within the block.

Inline elements are trickier because some need recursion and some must prevent it. For instance, backticks for code mean anything within them must be excluded from further processing, but a link can contain bold text.

Rule Definitions

Each rule is governed by a pattern and a handler. When the pattern matches text, the match result is passed in as arguments to the handler. This supports groups. Take, for example, this rule for strikeout text, or the second rule for erasing newlines.

[/~~(.+?)~~/, (entireMatch, txt) => dom('s', txt)

[/\n+/, () => []]

If the first pattern was matched against the string "one ~~two~~ three", then the handler's entireMatch variable will be "~~two~~" and the txt variable will be "two".

Each handler needs to return completely processed HTML as an array of DOM elements or strings that will be escaped. HTML strings are not allowed to be returned.

Markdown Processing Quick Overview

First, block handlers look for block-level elements. When a match is found, it must handle the block and all of the inlines within. Typically a block handler matches the beginning and end of a section of a document and then passes chunks of text to an inline processing function. Content that a block-level handler does not match is discarded.

The rule processor tries to find the rule that matches earliest. If multiple rules match at the same position, the first rule in the rule set is used. Block-level processing is less sensitive to this, but inline markup depends on it. Take, for instance, a linked image in Markdown: [![ALT](image-url)](link-url). The pattern for the link needs to match the entire link, including the image portion, and then its handler calls a function to parse ![ALT](image-url) into HTML.

Changelog
Code Highlighting
Content Transclusion
Custom Elements
Fair Comparison
Keybindings
Markdown Syntax
Rule Processing
Saving with WebDAV
Upgrading

Changelog

Is your version a little stale or missing some features? Learn how to upgrade!

• 2027-08-03 - Updated search to provide feedback for too many and zero results.
• 2027-07-27 - Added more metadata. Hide delete button for index page.
• 2027-07-23 - Added metadata for the application name and version. Fixed edit page's wrapping of the page ID to now use ellipsis.
• 2026-07-22 - Documentation update. Code and CSS cleanup. Added document title to top toolbar.
• 2026-07-21 - Added Control/Command-S behavior to save the wiki, along with additional keybindings. Added Escape shortcuts for canceling an edit and toggling the sidebar. Changed the edit confirmation button to say "Apply" to differentiate it from "Save".
• 2026-07-20 - Standardized class names, attributes, and more to use hyphens. Documented transclusion and removed transcluded content when editing.
• 2026-07-12 - Added support for [[Page Title]] for faster linking to internal pages. Changed best practices to embed custom elements in articles, which simplifies the experience.
• 2026-07-10 - Fixing sidebar icon display on Android.
• 2026-07-08 - Included TypeScript annotations into the JavaScript to allow intelligent editors the ability to have more context. This is preserved in the non-minified build.
• 2026-06-29 - Debounced search and required at least 3 characters. Added detection of broken internal links. Fixed minor issues with CSS, especially around mobile devices. Placed the cursor near the content being viewed when editing a page.
• 2026-06-25 - Added search, backlinks, dark mode, task lists.
• 2026-06-24 - Added WebDAV support for saving and automatic saving. Added custom element support.
• 2026-06-23 - Added icons to summary bars to help distinguish them faster. Added Fair Comparison of wiki alternatives. Added horizontal rules.
• 2026-06-22 - Enabled uploading of files and images into the wiki. Images are stored once and can be referenced by multiple pages.
• 2026-06-19 - Tables are now supported, along with alignment of table columns. Expanded section for how to include code highlighting with Prism.js.
• 2026-06-18 - Added autosave, a delete button, renaming the wiki, changing page IDs, and importing pages from another wiki file. Updated the Markdown processor to simplify the handlers and recurse only where needed.
• 2026-06-17 - Added a sidebar, transclusions, control/command + enter keybinding, automatic index list generation.
• 2026-06-15 - Improved the build system and added Markdown conversion tests.
• 2026-06-10 - Initial release.

Upgrading OmniFlux

You can copy all of your pages to a new copy of OmniFlux to upgrade to the latest version. The upgrade process also copies any extra <script> and <style> elements that were added. These are placed just after the core script and styles that make the wiki function.

The process is painless.

1. Save a copy of your existing wiki to your local drive.
2. Open a new version of OmniFlux from the documentation site.
3. Open the sidebar and go to "Actions".
4. (Optional) Erase all pages by clicking "Remove All Pages".
5. Import your old content by clicking "Import Pages" and selecting the saved wiki from step 1.
6. Save the upgraded wiki.

What gets copied?

• All pages. If you imported into a wiki that is not empty, then any pages with matching IDs are overwritten with the imported content.
• Any additional style and script tags that are outside of the articles.
• Style tags are put into the document header.
• Script tags are put at the end of the body.
• The document title.

In addition, the sidebar is updated after the import to reflect the new state of the wiki.

Are there any concerns?

When there are specific issues with versions that are released, the date of the new version will be listed along with upgrade instructions.

• 2026-07-20 - Class names changed.
• Before upgrading, modify your wiki and replace "of_core" with "of-core". <style class="of_core"> should become <style class="of-core">, and the same change should apply to the <script> tag.

Code Highlighting

You can include Prism or another library within the wiki to highlight code blocks. Code fences in Markdown automatically add class="language-xxxx" to the <code> element, allowing tools like Prism to work.

1. Go to the download page for Prism.
2. Select the desired theme.
3. Select additional highlighting languages you want.
4. While keeping that browser tab open, open a new tab that has the saved copy of this wiki.
5. Create a new page in the wiki and edit it. Add a <raw-html> element. When creating the <script> and <style> elements later, they must go into the <raw-html> code.
6. Go to the Prism tab and copy the extra JavaScript needed for Prism.
7. Go to the wiki tab and create a new <script> element and paste in the Prism code.
8. Go to the Prism tab and copy the extra CSS needed.
9. Go back to the wiki tab and create a new <style> element with the necessary Prism stylesheets.
10. Save the wiki HTML and verify that code fences are highlighted by reloading the wiki in your browser.

The normal process for upgrading will copy all articles, which includes this Prism code.

Problems

Prism does not highlight newly added <code> elements automatically. See issue #1115 for others wanting this same feature. You can handle this by adding another <script> element. Like before, put this one into the page.

<script>
MutationObserver(mutations => {
  for (const mutation of mutations) {
    if (mutation.type === 'childList' &&
        mutation.target.nodeName === 'ARTICLE' &&
        mutation.addedNodes.length > 0) {
      Prism.highlightAllUnder(mutation.target);
    }
  }
}).observe(document.body, { childList: true, subtree: true });
</script>

Another issue is that some Prism plugins, like toolbar plugins, will add extra elements to the HTML. This makes the HTML to Markdown conversion think that there is extra text. For instance, the "Copy to Clipboard Button" does this, which adds a "Copy" paragraph in the Markdown. Be careful when adding plugins and ensure they don't modify the DOM dramatically.

🖫 list-of-names.csv

This is a short CSV file listing names and whether they have been naughty or nice.

list-of-names.csv

🖼 solar-flare.jpg

This is a small image embedded in the wiki. When you use it elsewhere, the image data is referenced from this page. The image behaves like a normal image, but its data is never repeated.

You can use it like this: ![Solar Flare](#solar-flare.jpg)

Fair Comparison

All of the wikis compared here work with no installation, no server-side software, and nothing more than a web browser. Read my reviews, read reviews by others, and try out the systems that you think would work best for your purposes.

If you know of other self-contained wikis in this same vein, please let me know by opening an issue.

The table above and each section below provide statistics and notes to make projects easier to compare.

• Status: How long has the project been around? Have the bugs been worked out? (POC = proof of concept)
• Active: Is the project under active development?
• Editing: How are pages edited? WYSIWYG means "what you see is what you get"; MD means Markdown in a textarea.
• Size: The size of the stock, empty file on disk, not gzipped. If minification is available, the minified version is listed.
• Extensible: Is the codebase meant to be expanded with plugins or extensions? Is there a documented API?
• Storage: How is the content stored in the file?
• One File: Is the wiki predominantly saved as a single file by default? Plugins and extensions may change this behavior.
• Embed Files: Are users allowed to embed images? Can any file be added to the wiki?
• Local Saving: How does saving work when not using a server.
• Server-Side Saving: Is this software able to push files to a server somehow?
• Searching: Does the wiki provide built-in or extensibility to allow searching?

1.5KB Single-File Wiki

Goal: How small can a fully editable wiki possibly be?

Pros

Lightweight, CSS-based wiki that only needs JavaScript for editing. This is what inspired OmniFlux.

Viewable without JavaScript. Relies on CSS for navigation.

Cons

Content is stored twice, once as rendered HTML and once as a template that contains the raw Markdown.

Markdown conversion is somewhat buggy at times for specific examples.

Feather Wiki

Goal: A practical, extensible personal wiki that lives in a single file.

Pros

A more traditional, page-based navigation style than TiddlyWiki. Lots of community support for various customizations.

Much, much lighter than TiddlyWiki.

Cons

There are quirks on screens with different sizes, such as buttons being off screen when saving edits, though additional CSS could clear most of these up.

Unfriendly to source code management tools, such as git, because of the extremely long lines.

OmniFlux

Goal: A modern knowledge base packed into a tiny standalone HTML file.

Pros

You're looking at an OmniFlux wiki right now!

Viewable without JavaScript because it relies on CSS for navigation.

Cons

It's not designed to be extensible through plugins or additional code, but any script and style elements you add will be preserved during upgrades. Because there's no API to tie into, this is not listed as being "extensible."

With the goal of bidirectional conversion between HTML and Markdown, embedding arbitrary HTML within Markdown is not supported (custom elements are allowed).

siteleteer

Goal: Simple multi-page website in a single HTML, using Markdown for editing.

Pros

Very small, even though the JavaScript is not minified and includes comments. It is distributed this way to help developers change the wiki to do what they want.

Automatic navigation menu, with support for changing the order of items that are displayed.

Same author as FeatherWiki.

Cons

Stores content twice, once as rendered HTML and once as Markdown embedded in a pre tag.

Upgrades are more difficult than with most other solutions.

TiddlyWiki

Goal: The everything-in-one-file platform for notes, wikis, and personal knowledge management.

Pros

The leader of the pack. One of the earliest (if not the first) single-page wikis.

Strongly encourages plugins to handle all sorts of things. Extremely flexible and configurable. Works with a variety of server-side software to support saving remotely.

Cons

With ultimate configurability comes the largest size.

Navigation is unlike typical websites. Each "page" opens above the current content, so small pages are encouraged.

WOAS

Goal: Carry an entire wiki on a USB drive and edit it anywhere.

Pros

Worked well when it came out. Supported a style of markup like Wikipedia.

Supports AES encryption for pages.

Cons

Outdated and no longer loads because browsers don't allow loading Java applets any longer. Because there's an immediate check to see if file saving works, the entire wiki is not viewable.

WOAS Fork

Goal: Preserve and modernize the classic portable wiki experience.

Pros

Updated version of WOAS that supports saving in newer browsers. Supports a style of markup like Wikipedia.

Supported AES encryption for pages.

Cons

Fairly large for what you get, though space is cheap.

Xie

Goal: Generate self-contained wiki documents from Markdown with almost no overhead.

Pros

This shows promise because it is extremely lightweight.

Cons

Unfortunately, while editing pages and trying to add content, it appears to get confused on which page is being edited. Also, multiple copies of the same page get added to the DOM. However, these bugs aren't devastatingly bad and could be fixed with a little more time invested.

Saving with WebDAV

WebDAV (Web-based Distributed Authoring and Versioning) is a set of extensions to the standard HTTP protocol. While basic HTTP is generally read-only for viewing web pages, WebDAV allows users to edit, manage, and move files on a remote web server over the internet.

OmniFlux can use a WebDAV server, or a lightweight endpoint that supports HTTP PUT, to upload a copy of itself back to the server. The Upload button saves immediately, and Auto Upload saves after each content change while enabled. Here is a small list of supported software:

• All of the "nests" from Feather Wiki, which come in different versions.
• awesome-webdav has a list of servers that support WebDAV.
• Cloud providers (e.g. Nextcloud and ownCloud) and NAS devices (Synology, QNAP, TrueNAS) support it.
• Apache has mod_dav to enable support.

Custom Elements

A custom element extends the HTML standard with user-provided JavaScript. This can be for appearance only, or it can add functionality. Check out MDN's Using custom elements for further information.

OmniFlux allows embedding of custom elements as block-level Markdown. They are not allowed as inline elements.

<custom-element attr="value" more="ok">
This content is sent to the custom element.
</custom-element>

When converted to HTML, the custom element tag and all of its contents are copied exactly as they appeared in the Markdown.

When upgrading, any custom <style> and <script> tags are preserved, so your custom elements will continue to work.

Embedding arbitrary HTML as Markdown is not supported by OmniFlux's parser, but you can accomplish nearly the same thing using a custom element.

raw-html Example

In this scenario, the raw-html custom element is not defined and still works. That's because any custom element wrapping Markdown is preserved exactly as-is.

Here is an example of wrapping content with raw-html tags.

<raw-html><p style="font-size:3em">BIG!</p></raw-html>

And it looks like this:

But why does this work?

1. OmniFlux detects that there is a custom element, <raw-html>...</raw-html>.
2. OmniFlux doesn't know what custom elements are defined.
3. The safest path here is to copy the HTML from the Markdown to the resulting document.
4. The browser sees the custom element and it's not defined, so <raw-html> and its matching close tag are ignored, but the contents are preserved.

This allows HTML embedding without editing the OmniFlux code. The main risk is defining that custom element later, which could change or break pages that use it.

Tilt Example

This is an example of creating a custom element, embedding it into the wiki, and then using that same custom element to show something fancy. This is what the Markdown looks like to embed a custom element.

<tilt-container>OmniFlux</tilt-container>

It will render like this.

To include the tilt container custom element, add JavaScript to OmniFlux by creating a page that embeds the code for the custom element. Take a look at Tilt Custom Element and edit the page. Upgrading copies over custom elements, so these additions can move to newer OmniFlux versions.

Tilt Custom Element

This page defines the <tilt-container> custom element. Edit the page to see how it's done!

Read more about <raw-html>, embedding, and using Custom Elements.

If you make changes to this custom element, you will need to save and reload the wiki to have the element refreshed.

Content Transclusion

OmniFlux allows you to copy content from other elements. For instance, below is the title of the wiki, which comes from the document's title. Whenever a change is made to any page, all transclusions are updated.

This is achieved by using embedded HTML (see Custom Elements) and the data-of-transclude attribute.

<raw-html data-of-transclude="title"></raw-html>

The transclusion value, title, is used as a query selector in the document and the target element's content is copied. This is useful for standard disclaimers, safety warnings, or common steps that you want on several pages without maintaining those copies separately. Below is the License Information page repeated three times. When the license information page changes, all of these copies update automatically.

The three lines above are wrapped in a table, and the embedded Markdown looks like this before content is inserted.

<raw-html>
<table>
<tbody><tr><td data-of-transclude="#license-information"></td></tr>
<tr><td data-of-transclude="#license-information"></td></tr>
<tr><td data-of-transclude="#license-information"></td></tr>
</tbody></table>
</raw-html>

OmniFlux is licensed under the MIT License.

Keybindings

OmniFlux includes keybindings to speed up editing and reduce the effort required to add content. Keybindings change based on whether you are viewing or editing.

For Macs: All Ctrl shortcuts can be used with ⌘ Cmd instead.