Extensions

Extensions

Auto-code words

This extension is enabled by default. Use the command-line option --no-auto-code to disable it.

An auto-code word is automatically rendered as a code span even if it is not marked with grave accents. The word must be at least 4 bytes long. Inner white space must be escaped with backslash characters. The following word forms are recognized as auto-code words:

(The Markdown source below uses grave accents to simulate the appearance of auto-code words when seen in mdview.)

• absolute path -- any word that starts with a slash (/) and is at least four bytes long. Examples: /123, /naïve, /😃, "/dir/file", '/dir/file', /dir/, "/dir/".

• dot relative path -- any word that starts with ./ or ../ and is at least four bytes long. Examples: ../file, ../../dir/, ./file, ./dir/file, ./.bashrc.

• special file name -- a file name ending with extension ".patch" or ".diff". Examples: file.patch, "f.diff".

• URI -- a web link address. Examples: http://, https://, ftp://, http://www, https://www.example, ftp://www.example.com, "http://example.com", (https://www.example.com), http://a.com/, http://a.com?, http://a.com?v=.

  • Note that a permissive autolink will mask off the auto-code URI.

• e-mail address -- an ASCII word that does not start with @ or dot (.), and includes a @ and at least one dot. Example: [email protected].

  • Note that a permissive autolink will mask off the auto-code e-mail address.

• issue id -- the indentifier for issues or bugs on GitHub and in the BugZilla tracker: a hash sign (#) followed by an ASCII word. Examples: #123, #abc.

  • To disable auto-code for a specific id, add a backslash escape before the hash sign.

• function name -- an ASCII identifier followed by "()". An identifier is an alphanumeric sequence, with underscore also allowed, and with the condition that it can not begin with a numerical digit. Examples: foo(), foo_bar(), f9(), _foo().

• uppercase identifier -- an uppercase ASCII identifier that includes at least one underscore, and may optionally start with a dollar sign ($). Examples: XDG_CONFIG_HOME, _Z_DATA, $XDG_CONFIG_HOME.

Formatting

Exterior formatting for italics, bold, and strikethrough, is applied to the auto-code words. Examples: /italics /bold /strikethrough.

Auto-heading links

This extension is available for the Viewer and for HTML output. It is enabled by default. Use the command-line option --no-heading-link to disable it.

The auto-heading link feature automatically constructs a CommonMark link reference definition for the display text of ATX and SETEXT headings in the document. This allows authors to add a regular link to jump to the heading. The link destination must start with # (same as the in-page links of HTML documents). If the title includes spaces, wrap the destination with a pair of matching angular brackets.

Example of a regular link:

# This heading title
                           ┌── destination ──┐
[Jump to "Heading Title"](<#This heading title>)

In addition to jumping to the heading with a regular link, one can jump with a reference link as seen in the specification. Examples of reference links:

[This heading title]
[Jump to title][This heading title]

The reference link destination must exactly match the heading text, omitting any leading #.

Auto-heading link anchors

Given the heading "The heading", the auto-heading link feature adds the following in-page anchors at the heading's line:

Anchor	Referenced by
#The heading	verbatim heading text
#the_heading	snake-case slug
#the-heading	kebab-case slug

Therefore, within the mdview Viewer, the linked heading can be reached equivalently as follows:

Link	Markdown
[The heading]	[The heading]
[To The heading][The heading]	[To The heading][The heading]
To the_heading	[To the_heading](<#the_heading>)
To the-heading	[To the-heading](<#the-heading>)
To THE-Heading ¹	[To THE-heading](<#THE-heading>)
To the-HEADing ¹	[To the-HEADing](<#the-HeAdinG>)

Notes

1. The anchors in the last two links of the table above can work because mdview converts mixed-case slugs to lowercase internally.
2. Anchors for multiline SETEXT headings do not include hard line breaks.

Slug types

Mdview adds three anchor formats for each heading: snake-case, kebab-case and "natural" (for lack of a better term).

The snake-case anchor is the most common, and it is compatible with GitHub. So if you plan to upload your Markdown documents to GitHub, internal Markdown links should use snake-case slugs. Be aware that mdview's snake-case slugs can turn out to be empty under certain conditions, for instance, when the heading text does not include an ASCII character.

The kebab-case anchor slug is compatible with pandoc. In fact, given some heading text as input, the following command should create the same kebab-case slugs that mdview creates: pandoc -f markdown+auto_identifiers+ascii_identifiers. Mdview implements kebab-case slugs according to pandoc's specification of the auto_identifiers and ascii_identifiers extensions. Kebab-case slugs too can be empty under certain conditions.

"Natural" slugs encode the heading text as displayed by the mdview Viewer, and can accommodate all Unicode scripts. For instance, a heading containing Chinese pictograms of Cyrillic letters can be reached with the "natural" slug. Be aware that this type of slug is not portable outside mdview.

Limitations

Important: Mdview does not manage heading-text collisions. If two headings share the same display text, all reference links to that text will direct to the first matching heading in the document.

To mitigate the effects of issues 276 and 277, anchors are not created for headings containing an odd number of asterisk, underscore, or tilde characters. As a result, these headings cannot be jumped to, and they appear as plain text in the Table of Contents. Anchors are also not created if the heading includes an occurrence of the following characters: [, <, >, ], \ and &.

Auto-language files

This extension is only available in the Viewer. It is disabled by default. Use the command-line option --auto-lang to enable it.

When auto-language files are enabled, mdview tries to load a preferred-language file before finally settling to load the file specified on the command line or by an internal file or image link. If the preferred-language file is found, it is loaded instead of the original file. The preferred language is determined based on the user's locale settings. The original file name is modified inserting values derived from the language locale. For example, if the original file name is extensions.md, and the language locale is "fr_FR", the auto-language file name will be extensions.fr_FR.md.

Mdview attempts to shorten the auto-language file name extracting fragments of the language, and testing if a fragment matches an existing file. For the previous example, fr would be tested before fr_FR. This mechanism allows reusing the same auto-language file for all French national variants.

This feature consults the environment variables LANGUAGE, LC_ALL, LC_MESSAGES and LANG to find the list of locales specified by the user. A discussion of how to configure your language locales, and which cut points are valid is beyond the scope of this document. However, the following examples can help:

• If $LANG is fr_BE, then the fragments are fr_BE, fr.
• If $LANG is en_GB.UTF-8@euro, then the fragments are en_GB.UTF-8@euro, en_GB.UTF-8, en_GB@euro, en_GB, en.UTF-8@euro, en.UTF-8, en@euro, en.
• If $LANGUAGE is de:en_US, then the fragments are de, en_US, en, C.

Permissive autolinks

This extension is enabled by default. Use the command-line option --no-permlink to disable it. Note that permissive URL and E-mail autolinks (see below) take precedence over the auto-code word feature. To allow applying auto-code words to permissive URL and E-mail autolinks, disable the permissive autolinks feature.

While standard autolinks must be enclosed in < and >, e.g., <http://www.example.com>, permissive URL autolinks allow links without enclosing marks but have stricter rules to avoid false positives:

• Must be separated from surrounding text by whitespace or certain punctuation.

• Only specific punctuation is permitted before and after permissive autolinks, such as brackets (, {, or [.

• Must include a valid URL scheme (http://, https://, or ftp://).

  • The host must consist of alphanumeric characters and specific symbols, with at least two components separated by a dot.
  • Optional path components must start with / and follow similar character rules.
  • Queries can include various characters but must be properly formatted.

permissive WWW autolinks are also supported. They begin with www. and follow similar rules as URL autolinks.

permissive E-mail autolinks are also supported: The username can include alphanumeric characters and certain symbols, but these must be surrounded by alphanumeric characters.

Find out more in the Permissive Autolinks specification.

Shebang detection

This feature is enabled by default. Use the command-line option --no-shebang to disable it.

Before opening a document, mdview checks if the file content starts with a recognized prefix; if it does, the entire document is rendered as a code block. The list of recognized prefixes includes:

• [Unix shebang], e.g. #!/bin/sh
• HTML declarations <!DOCTYPE and <html

This capability allows for directly opening most shell scripts and HTML files while preserving their original formatting.

Smart text

This feature is enabled by default. Use the command-line option --no-smart to disable it.

Smart text replacement refers to the automatic conversion of certain characters or sequences of characters into typographically correct symbols. Mdview automatically applies the following replacements on output:

1. Smart quotes -- Single and double straight quotation marks (e.g., ' or ") are replaced with curly quotes (e.g., ‘ ’ for single quotes and “ ” for double quotes).

2. Smart dashes -- A sequence of two hyphens (--) separated from other words , is converted into an em dash (—).

Special links

This feature is always enabled.

Consider the destination of a Markdown link, e.g., "http://www.example.com". If the destination type is supported, the Viewer displays clickable text for the link. What happens when the text is clicked depends on whether the destination is external or internal. The Viewer passes external link destinations starting with "http://" and "https://" to the browser, and "ftp://" destinations to an FTP application, if configured.

Internal link destinations are most often written as local file pathnames, e.g. "first-chapter.md". The Viewer opens such links directly. Three other types of clickable internal link destinations are supported: "file://", "resource://" and "search://".

file:// link

This link type represents a local file. So the following Markdown links are equivalent:

[my file](/tmp/my-file.md)
[my file](file:///tmp/my-file.md)

Above, notice that a third slash character follows "file://" because "file://" only works with absolute paths. Thus, a bare pathname link is more flexible than a "file://" link because the pathname can also be relative. However, "file://" becomes useful when Markdown is converted to HTML. Browsers cannot open a bare pathname, but they can open a "file://" destination.

resource:// link

This link type represents and embedded resource, a binary blob stored inside the mdview binary file. In this respect, a "resource://" URI is useless, unless one knows which resources the binary file embeds -- very few, indeed. For example, the welcome page is embedded and can be linked with

[Welcome](resource:///welcome.md)

Interestingly, a "resource://" is looked up first as a local disk file, then as an embedded blob. The search proceeds through the directories listed in the environment variables XDG_DATA_HOME and XDG_DATA_DIRS. When searched as disk files, resources are also optionally looked up as auto-language files.

search:// link

This link type initiates a search in the home page directory, as if the user had typed the search terms in the Search input entry.

[Search now](search://my search terms)

Strike-through text

This feature is enabled by default. Use the command-line option --no-strikethrough to disable it.

Strike-through text is any text wrapped in one or two tildes (~). The opening and closing wrappers must have equal lengths.

Find out more in the Strike-through Text specification.

Tables

This feature is enabled by default. Use the command-line option --no-table to disable it.

Mdview can convert and render GFM Markdown tables.

A Markdown "simple table" is a basic format for creating tables using Markdown syntax, characterized by its straightforward structure. It typically consists of rows and columns separated by pipe characters (|) and uses dashes (-) to delineate the header from the data rows. For example:

| Header 1 | Header 2 |
|----------|----------|
| Row 1    | Data 1   |

A "GitHub Flavored Markdown (GFM)" table extends the basic Markdown table syntax by allowing alignment control within columns using colons (:).

| Left Align | Center Align | Right Align |
|:-----------|:------------:|------------:|
|  Data      | Data         |  Data       |

This renders as:

Left Align	Center Align	Right Align
Data	Data	Data

Merging table cells is not possible with this kind of syntax. Find out more in the Tables specification.

Table rendering limitations

Be aware that the mdview Viewer has limitations compared to a web browser in rendering table layouts. It outputs fixed-width characters for proper column alignment; therefore it automatically uses a monospaced font for tables. Additionally, text within table cells does not wrap; thus, a single cell with long text can make the entire column excessively wide, pushing other columns out of view. While images can be inserted into tables, they cannot be scaled automatically, resulting in oversized images enlarging their respective cells.

See also Limitations: Tables.

Table of Contents

This extension is available for the Viewer and for HTML output. It is disabled by default. Use the command-line option --toc-level=N to enable it. You can also enable the Table of Contents dynamically from the pull-down selector in the Viewer's toolbar.

When auto-heading links are enabled, mdview can generate a Table of Contents (ToC) based on the document's headings. Clicking a ToC entry jumps to the corresponding heading. The ToC body replaces the first occurrence of the string <!-- [toc] --> in the Markdown document. If the string cannot be found, the ToC is placed at the top of the document. The Viewer saves the Markdown text corresponding to the generated ToC to the Backing file.

XML page metadata

Markdown pages can include metadata that influence the operation of the Viewer. Refer to the XML metadata page.