Span Elements

We’ve already seen many examples of span elements, especially in the resources section showing resources inserted as spans. These are the rest of them…

Markua’s hyperlink support is a subset of that of Markdown. The inline link syntax is supported, as is the automatic link shortcut.

The normal way to create a link is as follows:

[link text](absolute_url)

Example:

Markua was developed at [Leanpub](http://leanpub.com).

To create a link where the text displayed for the link text is the URL itself, the automatic link syntax can be used. In this syntax, an absolute URL is enclosed in angle brackets.

Some text <absolute_url> some text.

Example:

Markua was developed at <http://leanpub.com>.

Explicitly Creating Spans with […]

Surrounding text in square brackets can be useful not just for giving it a URL to link to. If you wish to add attributes to an arbitrary span of text, you can create an arbitrary span of text using square brackets and then add an attribute list immediately afterward:

Some text [then a span]{and: an, attribute: list} attached to the span.

You can use any attribute list on this span, and you can also just use the id syntactic sugar {#theid} on this span. The most common uses of this are to add ids or index entries, which are discussed later.

Note, however, that you cannot start a normal span with a caret (^): this creates a [^footnote] instead. (Footnotes are discussed below.)

Sometimes a Square Bracket is Just a Square Bracket

If there are no round brackets or curly braces immediately after some text in square brackets, the text in square brackets is just that: text in square brackets. In this case, the square brackets are output as normal text.

This is useful when you want to [sic.] something, etc.

Footnotes and Endnotes

Footnotes

Books often have footnotes.

To add a footnote, you insert a footnote tag using square brackets, a caret and the tag, like this:

This has a footnote[^thenote].

Then, you define the footnote later in the document, using the same square brackets, caret and tag, followed by a colon, a space and the footnote definition:

[^thenote]: This is the footnote content.

If you wish to write multiple paragraphs in the footnote, you must indent the subsequent paragraphs by four spaces or one tab:

This has a footnote[^thenote].

Here is some unrelated text.

[^thenote]: This is the first paragraph of footnote content.

    This is the second paragraph of footnote content.

Here is some more unrelated text.

Endnotes

Books often have endnotes. Sometimes these are instead of footnotes, but other times, these are in addition to footnotes. So, it makes sense for Markua to define separate syntaxes for both, rather than just defining one “footnote or endnote” syntax and letting the author pick whether the notes are footnotes or endnotes via a global setting.

To add an endnote, you insert an endnote tag using square brackets, two carets and the tag, like this:

This has an endnote[^^thenote].

Endnotes are like footnotes, but happier (^^).

Then, you define the endnote later in the document, using the same square brackets, two carets and tag, followed by a colon, a space and the endnote definition:

[^^thenote]: This is the endnote content.

Just as with footnotes, if you wish to write multiple paragraphs in an endnote, you must indent the subsequent paragraphs by four spaces or one tab.

Single Reference to Footnotes and Endnotes

You can only refer to a footnote or endnote once. You can’t define a footnote or endnote in one place and refer to it multiple times in the same Markua manuscript. If you wish to refer to a parenthetical piece of text from multiple places in a Markua manuscript, the best approach is to put it in a section (or sub-section, sub-sub-section, etc.) or aside and refer to it from multiple places using a crosslink.

Footnotes and Endnotes Support Required for Paragraphs Only

Leanpub only supports footnote and endnote references inserted in normal paragraph content.

(Sometimes authors want to get creative with their footnotes and endnotes. Sometimes they want to add them in headings, or in footnotes or endnotes themselves. This latter style has been used on rare occasions, most notably by David Foster Wallace. However, that’s difficult to implement, and is optional in Markua, so Leanpub has not done so.)

There are two parts to making a crosslink.

  1. Define an id.
  2. Reference that id with a crosslink.

Defining an id

There are two ways to define an id:

  1. Using an id attribute {id: some-id}
  2. Using a shorter “syntactic sugar” approach: {#some-id}

The shorter “syntactic sugar” approach is usually preferred. However, it can look a bit odd in an attribute list with other attributes in it. So, in that case, the {id: some-id} syntax is preferred.

In terms of the value of an id, it has some special restrictions:

  1. The first character in the id has to be a lowercase or uppercase letter, i.e. [a-zA-Z] if you think in regular expressions.
  2. The remaining characters in the id have to be a lowercase or uppercase letter or a digit or a hyphen (-) or an underscore (_).
  3. You can only define an id value once in an entire Markua document, even one that is split over multiple files.

These restrictions ensure that your ids can then be linked to by a crosslink from anywhere in the Markua document.

The id needs to be defined on either a block or span element.

Defining an id on a Block Element

To define an id on a block element like a paragraph, figure, heading or even a definition list item, you simply stick the id definition on a line above the start of the block element. Note that exactly one newline must separate the attribute list from the block element–if two newlines are used, the attribute list will be interpreted as a directive, and the id won’t be correctly applied.

Here’s how to use the attribute list syntax to define an id attribute:

{id: some-id}
This is a paragraph with the id of `some-id`.

Here’s how to use the shorter “syntactic sugar” approach to define an id attribute:

{#some-id}
This is a paragraph with the id of `some-id`.

Defining an id on a Span Element

To define an id on a span element you simply add the id definition immediately after the span element.

Here’s how to use the attribute list syntax to define an id attribute on a span element:

The word Markua{id: markua} has an id.

Leanpub is based in **Victoria, BC, Canada**{id: victoria}.

Here’s how to use the shorter “syntactic sugar” approach to define an id attribute:

The word Markua{#markua} has an id.

Leanpub is based in **Victoria, BC, Canada**{#victoria}.

Here’s how to define an id on a custom span:

The [quick sly fox]{#quick_sly} jumped over the lazy dogs.

If you want to define an id on a span while also defining other attributes like index entries, the id: syntax must be used in a full attribute list:

The [quick sly fox]{id: quick_sly, i: "Fox, Sly and Quick"} jumped over the lazy dogs.

Regardless of how you defined the id, you then link to it to create a crosslink. To do this, you use the # character and the id in a link:

[link text](#some-id)

This syntax is intended to be reminiscent of HTML anchor tags, not of h1 titles in Markua.

Note that order of definition and use does not matter: crosslinks will work regardless of whether the id is defined before or after the use of it.

  • If a Markua document contains duplicate id attribute values, the first one is used and the subsequent ones are ignored. Leanpub should output a warning about duplicate ids.
  • Crosslinks that reference an unused id may either be created as a (broken, non-functional) link or be created as normal text (not a link) by Leanpub. The Leanpub may also output a warning about this somewhere, but not in the actual document text itself.

Character Substitution (X-- for X—, X -- for X –, ... for …)

All Markua documents are written in UTF-8, so to produce any Unicode character, it possible to just use the proper Unicode characters. However, in certain cases, it’s desirable for Markua to specify automatic replacement of certain combinations of characters with a Unicode replacement. If Leanpub encounters one of these combinations of characters outside of a code block, Leanpub must replace the combination of characters with the appropriate Unicode character in the output.

--
To produce an em dash (—), what is thought of by non-typography people as a “dash” or a “long dash”, you can just type two hyphens (--) directly after a non-space character. You can also use the proper Unicode character, U+2014, of course. The following all produce em dashes: foo--bar, foo-- bar, foo--.
--
To produce a space followed by an en dash (–), or the kind of dash that’s wider than a hyphen but narrower than an em dash, you can just type a space, followed by two hyphens ( --). You can also use the proper Unicode character, U+2013, of course. The following both produce en dashes preceded by spaces: foo -- bar, foo --. (With foo -- bar, there’s a space before and after the en dash; with foo --, there’s no space after it (e.g. at the end of a paragraph).
...
To produce a horizontal ellipsis (…), you can just type .... You can also use the proper Unicode character, U+2026, of course.

Optional Automatic Curly Quotes Outside of Code Blocks and Spans

Leanpub may replace the " character with the appropriate “curly quote” at its discretion. This lets "typography" become “typography”, and it's become it’s as appropriate.

Note that this is an optional behaviour: Leanpub may support this fully, only in some output formats, or not at all.

Also, note that it is NEVER acceptable for Leanpub to do this, or any character substitution, to text inside a code block or code span. In almost all instances this would completely break the code. (If you wonder how I got curly quotes into the code spans for “typography” and it’s above, it’s because I pasted them into the manuscript that way. Just as Leanpub doesn’t make straight quotes curly in a code span, it doesn’t make curly quotes straight in a code span either.)

Escaping Special Characters with Backslash (\)

Curly braces and backticks are special in Markua.

At the beginning of a line, an opening curly brace ({) starts an attribute list, and two opening curly braces ({{) start a placeholder. In the middle of a block element, an opening curly brace starts an index entry. And, at the top of a manuscript.txt file (if the single file approach is used), an opening curly brace starts a settings block.

So, to use a curly brace as an actual curly brace character, you need to backslash-escape it like this: \{. (Note that this does not apply inside code or other resources: Markua does not process anything inside them.)

Similarly, a backtick is special. In text content (such as this paragraph), a backtick starts an inline span resource such as a code resource. And three backticks on a line by themselves start a code block.

Code Spans and Backticks (`)

You can create a code span by using pairs of 1, 2 or 3 backticks to surround a span of text within a paragraph, like this:

This paragraph has a Ruby `puts "hello"` code span inside it.

You cannot show a literal backtick in a normal code span, however, since you cannot backslash escape anything inside it. Inside a code span, a backslash is just a backslash.

This paragraph has a Ruby `puts "hello\tworld"` code span inside it.

So, if you want to output a backtick in a code span, you need to delimit the code span using two backticks:

This paragraph has a code span with literal backticks `` `say hello` `` in it.

Up next

Metadata