Embedded References

#Embedded references are a shorthand method for embedding media images, embedding page metadata and inserting page links into pages. Since internal links are determined at build time, they will always be valid (no more broken links).

Link Referernce Syntax:

{ref: id [#item] [@description]}. In all cases, the "id" refers to the page or media id.

Pages:

When referencing another page, that page's title will be displayed by default. The "description" can be used to provide alternate link text, and the "item" can be used to provide a link to a named anchor in the page's content. For instance, {ref:pageid#footnotes@"Footnotes"} can be used to provide a link to the footnotes section at the bottom of a page. When providing a reference to another page, a link to that page will be added to the other page's Related Pages section at the bottom of the page.

Examples:

This ( {ref:html} ) is a link to the page HTML Extensions.

This ( {ref:references#related@Related Pages} ) is a link to the Related Pages at the bottom of this page.

Media Images:

For embedding media images, the image is shown using a preconfigured HTML structure. If you would like to use your own display structures, see the next section on getting reference metadata to obtain the page's media URLs. The "item" can be used to alter the default behavior, and may contain multiple parameters. When no items are provided, the image shown by default using the largest avaiable image, hyperlinked and without a caption. The item can be set to title, caption, credit or date to use any of those fields as defined by the <Media> options. You can also use the item field to specify an alternate image using large, medium, small or thumb. You can also use the item field to specify an alternate width for the media image using wNNN. Also by default, the image is left-aligned. You can use the item field to specify an alternate alignment using center, floatleft or floatright. Lastly, by default, the image is hyperlinked to the largest media size defined. You can use the nolink option to prevent this behavior. Since multiple item fields will often be necessary, the items should be delimited by periods as shown in the example below.

Example:

The image below was embedded using ( {ref:M2#large.w400.center.title.credit} ). Click on the image to enlarge.

Text Footnotes:

You can also add text footnotes by leaving off the "id" and providing a "description" only in the form of {ref:@description}}. The footnote will be added to the footnotes section at the bottom of the page. The footnote will be bi-directionally linked.

Example:

In this example, "footnote" is followed by ( {ref:@This is a text footnote} ), This is a footnote [ 1 ].

Help:

An additional feature is to use embedded references to provide help text in the form of {ref:?description}. In this case the "description" is the help text. A footnote will not be created, and the footnote link will display a question mark.

Example:

In this example, "text" is followed by ( {ref:?Consider yourself helped.} ), This is help text [ ? ].