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.

Example 1: Example automatic link to another markdown page.

Markdown
HTML

[Core](core.md)

Core

The syntax also supports HTML bookmark style links, as demonstrated in Example 2.

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

Markdown
HTML

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

Core

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.

Markdown
HTML

[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)

Bookmark

URL

File and bookmark

The optional and exact settings are similarly applied when handling alternative links to markdown files.

Table 2: Available settings for automatic links.

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	Identifier to link against this object.
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.

warning:Try not to abuse alternative links.

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.

Markdown
HTML

[core.md]

Core Extension

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.

Markdown
HTML

[core.md#shortcut-link]

Shortcut links

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.

Markdown
HTML

[not_a_real_file_name.md alternative=#autolinks]

[not_a_real_file_name.md alternative=core.md]

Automatic Links

Core Extension

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.

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	Identifier to link against this object.
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.

note:Applicable settings

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].

Source File Links

The !file command creates a link to a bottom extending modal window that displays complete source file text, as shown in Example 7. Optional settings may be used to specify the source language, link text, and modal title.

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

Markdown
HTML

[!file](framework/src/kernels/Diffusion.C)

[!file text=Diffusion Kernel title=Diffusion.C](framework/src/kernels/Diffusion.C)

(contrib/moose/framework/src/kernels/Diffusion.C)

Diffusion Kernel

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.

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

Markdown
HTML

[!file language=python title=run_tests](test/run_tests)

(contrib/moose/test/run_tests)

(contrib/moose/framework/src/kernels/Diffusion.C)

// This file is part of the MOOSE framework
// https://mooseframework.inl.gov
//
// All rights reserved, see COPYRIGHT for full restrictions
// https://github.com/idaholab/moose/blob/master/COPYRIGHT
//
// Licensed under LGPL 2.1, please see LICENSE for details
// https://www.gnu.org/licenses/lgpl-2.1.html

#include "Diffusion.h"

registerMooseObject("MooseApp", Diffusion);

InputParameters
Diffusion::validParams()
{
  InputParameters params = Kernel::validParams();
  params.addClassDescription("The Laplacian operator ($-\\nabla \\cdot \\nabla u$), with the weak "
                             "form of $(\\nabla \\phi_i, \\nabla u_h)$.");
  return params;
}

Diffusion::Diffusion(const InputParameters & parameters) : Kernel(parameters) {}

Real
Diffusion::computeQpResidual()
{
  return _grad_u[_qp] * _grad_test[_i][_qp];
}

Real
Diffusion::computeQpJacobian()
{
  return _grad_phi[_j][_qp] * _grad_test[_i][_qp];
}

Diffusion.C

// This file is part of the MOOSE framework
// https://mooseframework.inl.gov
//
// All rights reserved, see COPYRIGHT for full restrictions
// https://github.com/idaholab/moose/blob/master/COPYRIGHT
//
// Licensed under LGPL 2.1, please see LICENSE for details
// https://www.gnu.org/licenses/lgpl-2.1.html

#include "Diffusion.h"

registerMooseObject("MooseApp", Diffusion);

InputParameters
Diffusion::validParams()
{
  InputParameters params = Kernel::validParams();
  params.addClassDescription("The Laplacian operator ($-\\nabla \\cdot \\nabla u$), with the weak "
                             "form of $(\\nabla \\phi_i, \\nabla u_h)$.");
  return params;
}

Diffusion::Diffusion(const InputParameters & parameters) : Kernel(parameters) {}

Real
Diffusion::computeQpResidual()
{
  return _grad_u[_qp] * _grad_test[_i][_qp];
}

Real
Diffusion::computeQpJacobian()
{
  return _grad_phi[_j][_qp] * _grad_test[_i][_qp];
}

run_tests

#!/usr/bin/env python3
import sys, os

MOOSE_DIR = os.environ.get('MOOSE_DIR', os.path.abspath(os.path.join(os.path.dirname(os.path.realpath(__file__)), '..')))
sys.path.append(os.path.join(MOOSE_DIR, 'python'))
from TestHarness import TestHarness

TestHarness.buildAndRun(sys.argv, None, MOOSE_DIR)

Automatic Links
Automatic Link Shortcuts
Source File Links