AutoLink Extension

The AutoLink extension provide cross page automatic linking for markdown (*.md) files. This allows pages, such as those on this site, to link to each other by partial name. In the case of shortcut style linkes (see Shortcut links) heading content will also be include automatically.

The following table lists the available configuration options for the AutoLink extension.

Table 1: Configuration options for the AutoLink extension.

KeyDefaultDescription
activeTrueToggle for disabling the extension. This only changes the initial active state, use setActive to control at runtime.

The link within traditional markdown links (e.g., [text](link)) may include a markdown filename. The name must be unique, but may be incomplete. The entire page hieerachy is searched and filenames are compared using the python "endswith" method. Thus, the supplied name is considered unique if only one path from all possible paths ends with the supplied text, see Example 1.

Example 1: Example automatic link to another markdown page.

[Core](core.md)

The markdown filename link also supports html bookmark style links, as shown in Example 2.

Example 2: Example of automatic link to another markdown page that includes an html bookmark.

[Core](core.md#shortcut-link)

Optional key-value pairs used to define the settings for automatic links can be specified like [text](link key=value). A complete list of the available settings is given in Table 2.

Table 2: Available settings for automatic links. Note that the language setting has no effect unless the link is a source file.

KeyDefaultDescription
styleNoneThe style settings that are passed to rendered HTML tag.
classNoneThe class settings to be passed to rendered HTML tag.
idNoneThe class settings to be passed to the rendered tag.
optionalFalseToggle the link as optional when file doesn't exist.
exactFalseEnable/disable exact match for markdown file.
languageNoneThe language used for source file syntax highlighting.

Markdown syntax includes syntax for creating shortcuts (see Shortcut links), within MooseDocs these are deemed "shortcut links." The AutoLink extension allows for markdown filenames to be used within a shortcut link. In this case the text from the first heading is used as the link text, as in Example 3.

Example 3: Example of a shortcut link that contains a markdown filename.

It is also possible to include html style bookmarks with the filename, depending on the configuration (see Table 1) the link text will include the name of the text within the bookmark and optionally the page heading, see Example 4.

Example 4: Example of a shortcut link that contains a markdown file including an html style bookmark.

[core.md#shortcut-link]

A complete list of the available settings for automatic link shortcuts is given in Table 3.

Table 3: Available settings for automatic link shortcuts. Note that the language setting has no effect unless the link is a source file.

KeyDefaultDescription
styleNoneThe style settings that are passed to rendered HTML tag.
classNoneThe class settings to be passed to rendered HTML tag.
idNoneThe class settings to be passed to the rendered tag.
optionalFalseToggle the link as optional when file doesn't exist.
exactFalseEnable/disable exact match for markdown file.
languageNoneThe language used for source file syntax highlighting.

Automatic Source Content

If a filename is used within a link or shortcut link and the file is contained in the git repository a bottom extending modal window will be created that displays the complete text, as shown in Example 5.

Example 5: Example showing source code links to modal windows with complete source code.

[/Diffusion.C]

[Diffusion Kernel](/Diffusion.C)

Similar to the Listing Extension, the optional language setting can be used to specify the coding language to use for syntax highlighting as demonstrated in Example 6.

Example 6: Example showing source code link that sets the language to use for syntax highlighting.

[/test/run_tests language=python]