AutoLink Extension
The AutoLink extension provides 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 links (see Shortcut links), heading content may also be included automatically. Table 1 lists the available configuration options for the AutoLink extension.
Table 1: Configuration options for the AutoLink extension.
| Key | Default | Description |
|---|---|---|
| active | True | Toggle for disabling the extension. This only changes the initial active state, use setActive to control at runtime. |
Automatic Links
In MooseDown, the link within traditional markdown link syntax (e.g., [text](link)) may be a markdown filename. The name must be unique, but may be incomplete. The entire page hierarchy is searched and filenames are compared using the python str.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.
The syntax also supports HTML bookmark style links, as demonstrated in Example 2.
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. The alternative setting is particularly powerful and serves as a substitute for the originally linked file should it fail to be found. The input for this setting may be an HTML bookmark, a URL, or a markdown file plus bookmark combination (or just a file) as demonstrated in Example 3.
Example 3: Example uses of the alternative setting for automatic links when the original markdown file is not found in the available content.
[Bookmark](not_a_real_directory/not_a_real_file_name.md alternative=#source) [URL](not_a_real_file_name.md alternative=https://www.google.com/) [File and bookmark](not_a_real_file_name.md#not-a-real-bookmark alternative=core.md#shortcut-link)
The optional and exact settings are similarly applied when handling alternative links to markdown files.
Table 2: Available settings for automatic links. Note that the language setting has no effect unless the link is a source file.
| Key | Default | Description |
|---|---|---|
| style | None | The style settings that are passed to rendered HTML tag. |
| class | None | The class settings to be passed to rendered HTML tag. |
| id | None | The class settings to be passed to the rendered tag. |
| alternative | None | An alternative link to use when the file doesn't exist. |
| optional | False | Toggle the link as optional when the file doesn't exist. |
| exact | False | Enable/disable exact match for the markdown file. |
| language | None | The language used for source file syntax highlighting. |
The alternative setting should not be used as a means to circumvent potentially broken content configurations, but rather consciously under special circumstances. For example, its main purpose is to provide a fallback when developing sites designed with multiple configurations and cross-links between them, but expeditiously building only one of those configurations such that certain content is only conditionally unavailable.
Automatic Link Shortcuts
Markdown includes syntax for creating shortcuts (see Shortcut links). In MooseDown, 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 4.
Example 4: 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 5.
Example 5: Example of a shortcut link that contains a markdown file including an HTML style bookmark.
A complete list of the available settings for automatic link shortcuts is given in Table 3. Notice that the alternative setting is available and its use is demonstrated in Example 6.
Example 6: Example uses of the alternative setting for automatic shortcut links when the original markdown file is not found in the available content.
[not_a_real_file_name.md alternative=#autolinks] [not_a_real_file_name.md alternative=core.md]
Note that explicit URLs like https://www.google.com/ are not supported for automatic shortcut link alternatives, and MooseDocs will log an error if such an attempt is made.
Table 3: Available settings for automatic link shortcuts. Note that the language setting has no effect unless the link is a source file.
| Key | Default | Description |
|---|---|---|
| style | None | The style settings that are passed to rendered HTML tag. |
| class | None | The class settings to be passed to rendered HTML tag. |
| id | None | The class settings to be passed to the rendered tag. |
| alternative | None | An alternative link to use when the file doesn't exist. |
| optional | False | Toggle the link as optional when the file doesn't exist. |
| exact | False | Enable/disable exact match for the markdown file. |
| language | None | The language used for source file syntax highlighting. |
The alternative, optional, and exact settings given in both Table 2 and Table 3 have no effect when the link is a local bookmark, e.g., [#bookmark], nor when it is a source link. Furthermore, the language setting is only applicable to source links.
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 7.
Example 7: 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 8.