Resources

Markua documents are written in plain text, either in one text file or multiple text files. However, modern books sometimes contain more than text. Books may embed many types of resources. Each type of resource has a number of supported formats. Markua’s goal is to make inserting all types of resources simple and consistent, while staying as close to Markdown’s syntax as possible.

Resources vary in four different ways:

Insertion Methods: Span and Figure
Locations: Local, Web and Inline
Types: audio, code, image, math, video
Formats: png, m4a, mp3, ruby, latex, etc.

Before going into more detail, it’s helpful to consider a brief example of Markua text which shows a number of resources being inserted. These resources have different insertion methods (span and figure), different locations (local, web and inline), different types (image, code) and different formats (png, jpg, ruby)–yet the syntax to insert them is compact and consistent:

Inserting an image as a figure is...

![A Piece of Cake](http://markua.com/cake.jpg)

Inline code resources are added as spans like this `hello world` or as figures.

```ruby
puts "hello world"
```

{format: ruby}
![Hello, World](hello.rb)

The last figure in the example above showed an attribute list, which is a list of key-value pairs in curly braces. Any figure can have an attribute list, regardless of resource location, type or format. Attribute lists are explained in depth later.

If you’re familiar with Markdown syntax, you’ll note that the syntax for local and web resources is similar to Markdown’s inline image insertion syntax, and that the syntax for inline resources is similar to the fenced code blocks syntax from popular Markdown extensions including GitHub Flavoured Markdown.

Tables are also resources, and can also be local, web or inline. However, the table syntax is more elaborate than the syntax for the other resource types, so we discuss tables later.

Finally, if any resource is missing during book generation, Leanpub will insert something like the “missing image” often seen on web pages into the book.

Resource Insertion Methods

Resources can be inserted either as figures or as spans.

Figures

All resources can be inserted as figures. Figures are the normal case for how a resource is inserted. In many Markua books and documents, they will make up the bulk or the entirety of the resources.

To insert a resource as a figure, there must be at least one newline before and after it.

The syntax for a local resource or a web resource inserted as a figure is as follows:

{key: value, comma: separated, optional: attribute_list}
![Optional Figure Caption](resource_path_or_url)

The syntax for an inline resource inserted as a figure is as follows:

{key: value, comma: separated, optional: attribute_list}
```optional_format
inline resource content (default format is `guess`)
```

Note that you can also insert an inline resource as a figure using tildes as the delimiter. If the only delimiter was backticks, it would be really difficult to write about Markua in Markua. This syntax is as follows:

{key: value, comma: separated, optional: attribute_list}
~~~optional_format
inline resource content (default format is `text`)
~~~

Note that exactly three backticks or three tildes must be used to insert an inline resource as a figure. If more backticks or tildes are used, these will be interpreted as normal text.

Figure Attributes

A figure can also have attributes. The supported attributes vary based on the type of resource, but all figures support the caption, class, format, title and type attributes. (As such, these five attributes are not shown on the specific resource types below.)

caption: This is text which is shown near the figure, typically above or below it. Note that the figure caption itself may contain the Markua text formatting specified earlier in the Text Formatting chapter. If no caption is provided but a title is provided, then the title should be used as the caption: it does not make sense to refer to a figure with a title, but for the figure itself to have no caption.
format: This is the resource format. Different resource types have different legal values for format.
title: This is text which is displayed for the figure wherever the figure is listed (e.g. List of Illustrations, Table of Tables, etc.). If no title is provided, the caption should be used in those places.
type: This is the resource type. This is usually inferred from the format instead of being specified.

Figures can have alt text and a figure caption. The alt text and figure caption are distinct things. We will discuss the figure caption first and the alt text second.

Figure Captions

A resource which is inserted as a figure can have a figure caption.

This caption shows up in two places in the output:

Near the resource, typically above or below it, per the preference of Leanpub.
Based on the resource type, either in the List of Illustrations, List of Tables or Table of Figures, if they are generated for the book. This text should also be a crosslink to the caption inserted near the figure itself.

The caption for a figure can be provided either in the square brackets in front of a local or web resource or in the attribute list above the resource:

![My Amazing Algorithm](algorithm.rb)

{caption: "My Amazing Algorithm"}
![](algorithm.rb)

The first choice is clearly shorter, as well as more pleasant to write and to read.

Note that inline resources have no square brackets, so any captions must be added in the attribute list:

Here's a paragraph before the figure.

{caption: "My Amazing Algorithm"}
```ruby
puts "hello world"
```

Here's a paragraph after the figure.

Figure Alt Text

A figure can have alt text, as long as the type of resource being inserted supports alt text. The alt text is defined in an attribute list above the figure. Since the alt text is defined in the attribute list, the resource location does not matter: local, web and inline resources all support alt text.

The four types of resource which can have alt text when inserted as a figure are image, video, audio and math. Resources of type code and table do not support alt text, since they themselves are just text. If any alt text is provided for a code or table resource it is ignored.

Alt text is text which is intended to take the place of the resource if the resource itself cannot be seen. In the case of images, the obvious use case is for readers with visual disabilities who are using a screen reader, but it also includes audiobooks and ebook readers which often do not support embedded images, audio and video.

The alt text should not have the same content as the figure caption, if the figure caption is present. (Imagine the annoyance of having a visual disability and having your screen reader read identical alt text and figure captions to you throughout an entire book!) Instead, the alt text should be descriptive of the image content, while the figure caption can be more creative. For example, a figure caption may be “Washington Crossing the Delaware” and the alt text could be “Denzel Washington riding a jet ski in a river”. Having good alt text would enable readers who cannot see the image to still get the joke which the figure caption makes.

Figure Captions and Alt Text Together

These are some examples of figures with both alt text and a figure caption:

{alt: "Denzel Washington on a jet ski in a river"}
![Washington Crossing the Delaware](delaware.jpg)

{alt: "Denzel Washington on a jet ski in a river", caption: "Washington Crossing the Delaware"}
![](delaware.jpg)

{caption: "Earth From Space (Simplified)", alt: "a blue circle"}
```svg
<svg width="20" height="20">
  <circle cx="10" cy="10" r="9" fill="blue"/>
</svg>
```

The Figure Attribute List Takes Precedence

It is always an error to specify an attribute both in the attribute list for a figure and in the syntactic sugar locations, either after the backticks or in the square brackets.

However, if this is done, then the value in the attribute list takes precedence.

In the following figure, the format is text not ruby:

{format: text}
```ruby
puts "hello world"
```

In the following figure, the caption would be “Foo” not “bar”:

{caption: Foo}
![bar](foo.png)

Again, both of these are not good Markua: attribute values should be specified only once.

Spans

There are three types of resources which can be inserted as spans:

Single-line inline code resources.
A math resource (regardless of location) without a caption.
An image resource without figure attributes, such as captions.

An inline code resource can be inserted as a span using the following syntax:

It's a single backtick `followed by inline resource content` and then a single backtick.

An inline math resource of latex format can be inserted as a span using the following syntax:

It's a single backtick `followed by inline resource content`$ and then a single backtick and dollar sign (\
`$`).

An inline math resource of asciimath format can be inserted as a span using the following syntax:

It's a single backtick `followed by inline resource content`@ and then a single backtick and an at sign (`\
@`).

The code and math resources are described more fully later.

Span Attribute Lists Can Be Used To Set The Format

By default, the format of an inline resource is text for code and latex for math (with $ after the closing backtick). For an image, it is determined by the file extension.

However, span attribute lists can be used to set the format explicitly.

For example, this resource would be formatted as Ruby code:

Yada yada `puts "hi"`{format: ruby} yada yada.

This resource would be treated as LaTeX math:

Yada yada `some LaTeX math here`{format: latex} yada yada.

This resource would be treated as AsciiMath:

Yada yada `some AsciiMath math here`{format: asciimath} yada yada.

This resource would be treated as MathML math:

Yada yada `some MathML math here`{format: mathml} yada yada.

Yes, you can actually insert a math resource of mathml format as a span, but it’s so verbose that it’s a bad idea. You’re much better off using AsciiMath or LaTeX math for spans.

When a resource is inserted as a span, the resource is inserted as part of the flow of text of a paragraph with no newlines before or after it. A span resource is intended to be extremely short and simple. However, to support rare use cases, any span can have an attribute list. The attribute list on a span is specified immediately after the closing backtick. Examples of this are shown in the code and math sections.

Note that inside a code span, whitespace is preserved. The reasoning here is simple: in source code, whitespace matters, so it must not get collapsed into a single space.

Inserting Resources Into a Span Context

In Markua, resources can be inserted into a span context (within a paragraph or other block element) or into a block context (with blank lines above and below it).

Now, it doesn’t make sense for many types of resources to be inserted into, say, the middle of a sentence. Specifically, the only ones where this really does make sense is images without captions: the rise of emoji has shown that there is an entirely mainstream use for inserting images mid-sentence, with no captions or other formatting around the image.

So, the rules for inserting resources into a span context are as follows:

Any resource can be inserted into a span context, such as the middle of a paragraph.
Any resource with a caption which is inserted into a span context is treated as though there is a single newline before and after it, causing it to be inserted as a figure within the span context.
The following resource types, when they do not have a caption, can be inserted into a span context without causing single newlines to implicitly precede and follow them:
1. a image without a caption, regardless of location or format
2. a math resource, regardless of location or format
3. a single-line inline code resource
All other resources cause single newlines to implicitly precede and follow them when being inserted into a span context.

In terms of inserting resources into a block context: all resource types and formats can be inserted into a block context, with and without captions.

If a resource is inserted in a span context, and it can fit in the span context, it is inserted as a span, with whitespace before and after it. Examples of resources which can fit in a span context are images without captions, video without captions (since an image is used as a placeholder) and single-line code samples. Now, there are certain types of resources which, when inserted into a span context, cause the addition of single newlines before and after the resource. These include any resource with a caption and a multi-line code sample.

If a local or web resource is inserted with no newlines before or after it,

The following two paragraphs are equivalent:

Here's some text ![Foo](bar.png) and more text.

Here's some text
![Foo](bar.png)
and more text.

In both cases, the bar.png image is inserted as a figure, and the text in the square brackets is the figure caption, not the alt text. The text in square brackets before a local or web resource is always the figure caption. Also, in both cases, the text which follows the figure is part of the same paragraph as the text which precedes the figure, unless there are two newlines after it to start a new paragraph.

Even though both images above are inserted as figures, in the first case there is no way to specify alt text. This is why the implicit newline approach is inferior to using explicit newlines, since with explicit newlines an attribute list can be defined on the figure like this:

Here's some text
{alt: "a shoal"}
![Foo](bar.png)
and more text.

Finally, note that this is all true for all local or web resources, regardless of resource type. The following two paragraphs which contain a web code resource are also equivalent:

Hello in Ruby is a simple ![Hello World in Ruby](http://markua.com/hello.rb) statement.

Hello in Ruby is a simple
![Hello World in Ruby](http://markua.com/hello.rb)
statement.

For the purpose of brevity, this point will not be explained in each section about different resource formats.

To be clear:

All local or web resources are inserted as figures. It is not possible to insert any type of local or web resource as a span.
All table, image, audio and video resources are inserted as figures. It is not possible to insert table, image, audio or video resources inline as a span.
It is only possible to insert code and math resources inline as spans. The code is formatted as text, and the math is formatted as latex. The specific syntax for these use cases is covered later.

Resource Locations

A resource is either considered a local, web or inline resource based on its location:

Local Resource: The resource is stored along with the manuscript–either in a resources directory on a local filesystem, or uploaded to the same web service where the Markua document is being written.
Web Resource: The resource is referred to via an http or https URL.
Inline Resource: The resource is defined right in the body of a Markua document.

Local Resources

If local resources are used, all local resources must be stored inside a resources directory, or one of its subdirectories. The resources directory is not part of the path to the resource. You cannot navigate upward with ../ in paths for security reasons.

A file called foo.jpg in the resources directory should be referenced as ![](foo.jpg)–not as ![](/foo.jpg), ![](resources/foo.jpg) or ![](/resources/foo.jpg). (Leanpub may support the ![](/resources/foo.jpg) leading-slash syntax for now, but this is not guaranteed to be true in future.)
A file called bar.png in a subdirectory images of the resources directory should be referenced as ![](images/bar.png)–not as ![](/images/bar.png) or ![](/resources/images/bar.png).

Note, however, that Leanpub also ignores the part of a path which starts with resources/. So, you can also do the following:

A file called foo.jpg in the resources directory can also be referenced as ![](resources/foo.jpg).
A file called bar.png in a subdirectory images of the resources directory can also be referenced as ![](resources/images/bar.png).

The reason for this is that there are, and always will be, more Markdown-aware tools in the world than Markua-aware tools. So, supporting relative paths is a must, and a relative path does include the resources/ part of that path. One unfortunate consequence of this, however, is that you cannot have a directory called resources inside the resources directory. So, any paths which are resources/resources/ are illegal. Everything has tradeoffs, and this is the pragmatic choice.

Note that you cannot have spaces in the directory names. If you have a directory called foo bar containing an image called baz.png, you will have a really bad time trying to refer to it. Instead, use hypens or underscores in your directory names: foo_bar/baz.png is fine, as is foo-bar/baz.png.

Nested directory trees work as well. A file called foo.rb in a ch1/examples/ruby directory tree inside the resources directory is referenced as ![](ch1/examples/ruby/foo.rb).

Markua does not specify whether there are any subdirectories of the resources directory, or what their names are. Since any subdirectories have their names as part of the path to the resource, implementations can do whatever they want. For example, Leanpub will create subdirectories of the resources directory for every type of resource (images, audio, video, code, math and tables), but this is not a requirement. (To be clear, the names of these directories have no meaning; they could be anything.)

The local resources approach can also be used by hosted services. Internally, services can store resources wherever they want, but if they provide a download (say as a zip file) they should create the resources directory and provide the uploaded resources in that directory. If a nested structure is used, it should be exported that way–if a web service produces paths which reference images inside an images directory (e.g. as images/foo.png), then the zip file containing an export should contain a resources directory which contains an images subdirectory with the images.

Web Resources

If web resources are supported, both http: and https: resources should be supported.

Web resources are identified by the absolute URL of the resource on the internet.

Inline Resources

Inline resources can be of type code, math (regardless of format), table, or an image resources of svg format. Since an SVG image is just XML text, it can be contained inline in the text of a Markua document. This is not something that is true for binary resources like PNG or JPEG images or any type of audio or video file–these can only be local or web resources.

Resource Types and Formats

Leanpub supports these types of resources: audio, code, image and video. Each type of resource has a number of supported formats. Any of the seven resource types can be inserted as a local resource or web resource, and many of the resource types can also be inserted as an inline resource.

Both the type and the format can be specified in an attribute list, by the respective type and format attributes.

The type and the format can also be inferred from the file extension and, in the case of web resources, the URL. The following table shows the mapping of file extensions to the default format and type inferred. Note that these are just defaults: a resource can be set to be any type and format using the attribute list, and this overrides what is inferred from the file extension.

Formats Mapped to Resource Types
Extension	`format`	`type`	Description
`.txt`	`text`	`code`	Unformatted code
(other)	`guess`	`code`	Formatted code
`.gif`	`gif`	`image`	GIF image
`.jpeg`	`jpeg`	`image`	JPEG image
`.jpg`	`jpeg`	`image`	JPEG image
`.png`	`png`	`image`	PNG image
`.svg`	`svg`	`image`	SVG image

Note that these file extensions are case-insensitive.

Also, as discussed in the code section, Leanpub interprets all unspecified file extensions as specifying a resource of type code with a format of guess, unless the resource is a web resource. If the type and format are not specified and the resource is a web resource, Leanpub may use the domain to decide what type of resource to assume. For example, a domain of youtube.com may be assumed to be of type video, a domain of instagram.com may be assumed to be of type image, and a domain of github.com may be assumed to be of type code.

If the type is not specified in the attribute list, the format determines the type. The formats can either be specified by the format attribute or (in most cases) inferred from the file extension for local and web resources. (Inline resources obviously have no file extension, since they are contained in the body of a Markua manuscript file.)

As an author, all you typically do is provide the correct file extension or set the format in the attribute list. Markua recognizes the format, and uses it to determine the type. If the format is unrecognized, then the resource is treated as a resource of type code and with a format of guess.

It’s important to emphasize that the type and format of a resource can be overridden using an attribute list. In rare instances, it is useful to override the type and format which have been inferred by Leanpub based on the file extension of the resource. This is done by specifying a type and/or format in the attribute list of the resource.

Three examples of when this could be desired are:

When writing about, say, the SVG file format, you may want to treat a .svg file as a resource of type code instead of type image. This way, the SVG image (which is just XML text) would be shown as code, instead of interpreted as an image. This would be accomplished by the attribute list {type: code, format: text}.
When writing about a programming language which is not identified correctly by Leanpub, you may want to force the format of the language.
When writing about LaTeX math, you may want to force the type to be code not math.

We will now consider each of the types of resources in more detail, as well as the various formats that they support. We will also discuss the supported attributes for each resource type. Resources have different default attributes based on their type, format and insertion method.

Images

The syntax to insert an image is the same compact and consistent syntax that is used for any resource. Local and web resource locations are supported for any type of image; inline resource locations are supported for SVG images only.

Per the table of resource types and formats, the following types of images are supported in Markua: GIF, PNG, JPEG, SVG and zipped SVG.

Images are always inserted as figures.

We will discuss the supported and the default attributes for images, and then show examples of images being inserted for local, web and inline images.

Note that regardless of the image location, Leanpub embeds the image in the output format.

Images have some of the only non-semantic formatting in Markua. Images can have width, height, and align or float attributes, or can be fullbleed. (However, our advice is to save your time and not use the float attribute. See below for details.) These settings, which also apply to the posters for videos, are so universal when applied to images that it would be too purist for Markua to insist that the only way to format images was to add a class element, and then style the class of the image elsewhere. Markua is semantic, but it’s also pragmatic: by providing a few basic ways to format images, it enables authors to make in-progress books look good enough to publish in-progress.

Supported Attributes for Images

The following are the supported attributes for image resources, in addition to the type, format, caption and class attributes which all resources support:

align: The align can be left, right or middle. The default is middle. Combined with width and height, this provides basic image formatting. When align is specified, text goes above and below the image, but the image and its surrounding whitespace occupies the entire width of the page. In terms of the specific values of align, Leanpub interprets left as “on the left side of the page”, right as “on the right side of the page” and middle as “in the middle of the content area of the page, respecting margins” in all cases. Finally, note that inside and outside are not supported for align. If you are using those attributes, chances are you should be floating the text around the image by using the float attribute, not the align attribute.
alt: The alt is the alt text, to be displayed when the image cannot be shown. This is provided in the figure attribute list.
float: The float can be left, right, inside or outside. The left and right attribute values mean the same thing as they do with align. When float is specified, text flows around the image. It is an error to specify both align and float. Note that middle is not supported for float, since Markua is not a good choice for the types of advanced layouts which flow text on both sides of an image. For that, you should use something like InDesign; this is why Leanpub can export InDesign files. Also, note that float supports inside or outside, but align does not. What Leanpub does with inside and outside is more complex. Leanpub must interpret inside as “near the spine” and outside as “away from the spine” in a print book. In an ebook, however, Leanpub has some flexibility in terms of the meaning of inside and outside: it can either interpret inside as “left” or it can interpret inside as “left if the language is left-to-right, and right if the language is right-to-left”. Similarly, Leanpub can either interpret outside as “right” or it can interpret outside as “right if the language is left-to-right, and left if the language is right-to-left”. If that makes your head hurt, just use left and right instead. Frankly, our recommendation about using the float attribute is to save your time and not do it. Floating images and wrapping text occasionally do work nicely, but more often than not they leave something to be desired. Basically, it really only works decently for small images, and not in conjunction with anything but normal paragraphs. Our PDF rendering is done by producing LaTeX from Markua. LaTeX is great, but its support for floating images requires some manual tweaking at times, and this is not something that Markua encourages or supports: Markua is all about fully-automated layout of books. Finally, for the people who read your book in EPUB on a phone, they will not care about, or benefit from, any work spent floating images.
fullbleed: true or false. The default is false. If true, Leanpub should ensure that the image is the full size of the page, with no margins on the page. If false, the width, height and align attributes are used instead and margins are respected.
height: The height of the image, in percentage of page content area height (respecting margins). This is specified as a number (integer or float) between 1 and 100 followed by a percentage sign (%). The quotes are optional. So, you can say {height: "70%"}, {height: 70%}, {height: "70.5%"} or {height: 70.5%}.
width: The width of the image, in percentage of page content area width (respecting margins). This is specified as an number (integer or float) between 1 and 100 followed by a percentage sign (%). The quotes are optional. So, you can say {width: "70%"}, {width: 70%}, {width: "70.5%"} or {width: 70.5%}.

Note that if only one of width and height are specified, Leanpub should scale the image proportionally if possible (again, respecting margins). If both width and height are specified, Leanpub should scale the image accordingly, ignoring the aspect ratio. (So, it’s almost always a bad idea to specify both width and height.)

Local Images

The following are some examples of local images:

Here's a paragraph before the first figure.

![A Piece of Cake](cake.jpg)

Here's a paragraph between the first and second figures.

{alt: "a slice of chocolate cake", fullbleed: true}
![A Piece of Cake](images/cake.jpg)

Here's a paragraph between the second and third figures.

{alt: "a slice of apple pie with ice cream on top", class: "food-closeup"}
![A Piece of Pie](pie.jpg)

Here's a paragraph after the third figure.

In the above example, the first and third images were directly in the resources directory, whereas the second image was in an images subdirectory of the resources directory.

Web Images

The following are some examples of web images:

Here's a paragraph before the first figure.

![A Piece of Cake](http://markua.com/cake.jpg)

Here's a paragraph between the first and second figures.

{alt: "a slice of chocolate cake", fullbleed: true}
![A Piece of Cake](http://markua.com/cake.jpg)

Here's a paragraph between the second and third figures.

{alt: "a slice of apple pie with ice cream on top", class: "food-closeup"}
![A Piece of Pie](http://markua.com/pie.jpg)

Here's a paragraph after the third figure.

Inline Images (SVG only)

SVG images are just XML text, so they can be inserted inline in Markua:

Here's a paragraph before the figure.

{caption: "Earth From Space (Simplified)", alt: "a blue circle"}
```svg
<svg width="20" height="20">
  <circle cx="10" cy="10" r="9" fill="blue"/>
</svg>
```

Here's a paragraph after the figure.

Adding a Link Around an Image

You can also use the Markua link syntax around an images itself. This is the standard Markdown link syntax which Markua inherited unchanged.

So, you can do the following:

[![A Piece of Cake](cake.jpg)](https://peterarmstrong.com/pictures/1.jpg)

Frankly, this syntax has enough line noise to remind me a bit of JWZ’s “now you have two problems” joke about regular expressions.

What this is doing is inserting an image as a resource with a caption ![A Piece of Cake](cake.jpg) and then wrapping the entire thing with a link. If you think of the image resource as r, this is just [r](https://peterarmstrong.com/pictures/1.jpg). Simple!

Video

The syntax to insert a video is the same compact and consistent syntax that is used for any resource. Local and web resource locations are supported for both video formats; inline resource locations for video are obviously not supported.

Leanpub may choose to not support video at all, or to only support one of local or web video due to bandwidth or copyright concerns.

Unlike images, which are supported in most circumstances, with video files it’s currently a bit of a crapshoot. There’s currently a dominant proprietary format (H.264, or .mp4) and a new open source challenger (WebM). It’s entirely likely that many ebook readers won’t support either.

Also, unlike images where many images will accompany the manuscript itself, with video it’s expected that authors will be uploading their videos to sites such as YouTube first, and then reusing these videos in the contents of their Markua books. So, while video can be local or web video, web video will be much more prominent than web images in a Markua book.

Furthermore, unlike with web images where the format (and thus the type) are typically discoverable from the file extension in the URL, with web video it’s usually not. So, for web videos, there will typically be a {type: video} attribute list at a minimum. That said, if the type and format are not specified and the resource is a web resource, Leanpub may use the domain to decide what type of resource to assume. So YouTube videos just work in Leanpub, without specifying either the type or format.

Per the table of resource types and formats, the following types of videos are supported in Markua: MP4 and WebM.

We will discuss the supported and the default attributes for videos, and then show examples of videos being inserted for both local and web videos.

Supported Attributes for Video

The following are the supported attributes for video resources, in addition to the type, format, caption and class attributes which all resources support. Note that the caption, class, fullbleed, height and width attributes apply to the poster image for the video–not to the video itself during playback.

align: The align can be left, right or middle. This applies to the poster image for the video, and works just like it does with images.
embed: true or false. If true, then you can actually embed the video file or reference it and play it. If false, then it’s from a site like YouTube which disallows this. In this case, this should function like a link to external web page, but open an appropriate app (e.g. the YouTube app) instead of a browser. Leanpub can be smart about defaults, and parse the URL to set the value of the embed attribute.
float: The float can be left, right, inside or outside. This applies to the poster image for the video, and works just like it does with images. It is an error to specify both align and float.
fullbleed: true or false. The default is false. This applies to the poster image for the video, and works just like it does with images.
height: This applies to the poster image for the video, and works just like it does with images.
poster: The poster is the URL or path to an image which should be shown instead of the video before the video is played. If Leanpub is outputting some format where it is known that video resources are not supported, it must choose the poster to use as a replacement for the video. Books are not just ebooks–books can also be printed on the fibers of trees that have been chopped down (“paper”), producing something called a “book”. These “books”, whether they are bound in a sturdy fashion (“hardcover books”) or a flimsy fashion (“paperback books”), have one thing in common with respect to embedded video: they do not support it. Finally, if Leanpub is embedding a web video from a web video service (e.g. YouTube) which has a known algorithm for the location of the poster images for its videos, Leanpub may choose to use that poster image if a poster attribute is not explicitly specified. However, if a poster attribute is specified, then it must be used by Leanpub.
poster-format: The format of the poster image, if it exists. If this attribute is not specified, the format of the poster is inferred from the poster image file extension. This attribute needs to exist only to support poster images which do not have file extensions.
transcript: The URL or path to a transcript of the video, which should be shown or dictated to people who cannot view video. This helps people with visual disabilities view course material, and helps with ADA compliance. For example, what Leanpub does with a transcript is as follows: a URL is linked to in the caption (but in a way which does not affect the Table of Contents), and a path is assumed to be a path to a Markua file which is then used to produce a web page at a public URL, which then is also linked to in the caption in a way which does not affect the Table of Contents. With the Markua files for transcripts, Leanpub only supports certain resource types to be included in the transcript files themselves. Specifically, images, video, audio are not supported, but code and math are supported. When Leanpub generates a transcript, the URLs are publicly accessible but obscure. Identical transcripts should not make duplicate transcript files on the web, and using a new UUID every time would violate this. However, not changing the transcript URL when its content changed could lead to bad outcomes. So, the URL of a transcript on the web should be scoped to the book and affected both by its filename and its content. What Leanpub does is: (filename minus extension minus period plus hyphen plus the SHA hash).html. Including the filename eliminates collisions if filenames are unique but the hashes are not.
width: This applies to the poster image for the video, and works just like it does with images.

Local Video

Here's a paragraph before the figure.

![A Piece of Cake](cake-eating-contest.webm)

Here's a paragraph after the figure.

Web Video

Here's a paragraph before the figure.

{type: video, poster: "http://img.youtube.com/vi/VOCYL-FNbr0/mqdefault.jpg"}
![Introducing Markua](https://www.youtube.com/watch?t=105&v=VOCYL-FNbr0)

Here's a paragraph after the figure.

Ironically, it took me about a year after that talk was recorded to finally figure out what Markua was.

Audio

Just as with video, the audio support in ebooks and on the web is more varied than for images. With audio, there are MP3, AAC, Ogg and WAV formats all in widespread use, and there are a number of other formats with supporters. It’s entirely likely that many ebook readers won’t support any of them.

Leanpub may choose to not support audio at all, or to only support one of local or web audio due to bandwidth or copyright concerns.

Per the table of resource types and formats, the following types of audio resources are supported in Markua: MP3, AAC, WAV and Ogg Vorbis.

The syntax to insert an audio file is the same compact and consistent syntax that is used for any resource. Local and web resource locations are supported for both audio formats; inline resource locations for audio are obviously not supported.

We will discuss the supported and the default attributes for audio files, and then show examples of audio being inserted for both local and web audio files.

Supported Attributes for Audio

The following are the supported attributes for audio resources, in addition to the type, format, caption and class attributes which all resources support.

transcript: The URL or path to a transcript of the audio, which should be shown to people who cannot hear audio. This helps people with auditory disabilities view course material, and helps with ADA compliance. Transcripts should be produced and handled in an identical way to video resources. For example, Leanpub does this. See the Video resource section above for more information.

Local Audio

The full version of the talk is here:

![Full Talk](talk.m4a)

Web Audio

The full version of the talk is here:

![Full Talk](http://markua.com/talk.m4a)

Code

Code can be a local, web or inline resource, just like any other resource, and the same resource syntax applies to code as to all other resources.

As discussed, code cannot have alt text. It’s just text. If any alt text is provided for a code resource, it is ignored.

Markua specifies only one specific file extension to be associated with a type of code: the .txt extension, which is for the format of text. However, Leanpub interprets all unspecified file extensions as specifying a resource of type code with a format of guess.

Regardless of whether syntax highlighting is supported and the programming language is detected, all code must be formatted as monospaced text by Leanpub.

The text format means to not do any syntax highlighting as well.

The guess format is a request for Leanpub to guess at the programming language based on the file extension and/or the syntax of the code itself. Then, if the detected language corresponds to a particular programming language which Leanpub recognizes, it can format the resource as nicely syntax-highlighted code. Leanpub uses Pygments for syntax highlighting. If Leanpub cannot detect a matching supported programming language, then it formats the code as though the format was text–i.e. to format it as unformatted monospaced text.

Besides the text and guess values of the format attribute, you can also specify the programming language by setting the format attribute to a specific programming language. This is more reliable than guess. Unlike other resource types, Markua does not specify the complete set of the values of the format attribute–there are so many programming languages in the world, and new ones are added so frequently, that doing so would be impractical.

However, while a complete set of the values of the format attribute is not specified, Markua does specify the console value of the format attribute to indicate console input. Leanpub should format console input as such. (For example, Leanpub uses the open source Pygments library for its code formatting, and Pygments handles console format correctly, so Leanpub gets this for free.)

The default value of the format attribute for code is complex:

For code which is inserted as a span (which is only supported with inline resources), the default format is text.
For code which is inserted as a figure which is inserted as an inline resource using three tildes, the default format is text.
For all other code, the default format is guess. This includes local and web resources inserted as figures, and code inserted as an inline figure using three backticks.

Note that the default format can be overridden by specifying it via an attribute list, or after the three backticks in syntactic sugar.

Supported Attributes for Code

The following are the supported attributes for code resources, in addition to the type, format, caption and class attributes which all resources support.

line-numbers: This determines whether the code sample shows line numbers. Legal values are true or false. The default value is false. Any value other than true is interpreted as false.
number-from: If line numbers are shown, this lets you override the starting number of the line numbers. The default value is 1.
crop-start: Sometimes it’s desirable to only show part of a code resource defined in an external file as the code example. The crop-start and crop-end attributes let you accomplish this. The crop-start attribute defines the line which represents the first line included from the resource. For example, {crop-start: 10, crop-end: 15, line-numbers: true, number-from: 10} ensures that lines 10-15 are shown and are numbered as lines 10-15. The default value is 1, which is the first line of the file.
crop-end: This attribute ends the range started with crop-start. The default value of crop-end is to be omitted, which is equivalent to specifying the last line of the file.

Default Value of the `format` attribute in Inline Code Samples

The default value of the format attribute for a code resource inserted as a figure varies based on context.

If the code resource is a local or web resource, it defaults to guess.

If the code resource is an inline resource, the default varies based on the delimiter, and whether the code is inserted as a span or as a block.

With three backticks the default format is guess, and with three tildes, the default format is text. This way, you can vary the default without having to type an attribute list: if you want the code language guessed at, use backticks; if you don’t, use tildes. Of course, you can specify any attributes you wish with either delimiter, and specified attributes override default ones. The only reason there are different defaults are to make things easier to type. Programmers refer to such niceties as “syntactic sugar”.

The default value of block code resources inserted with three backticks can be overridden from guess to some other value by setting by the default-code-language attribute on the entire Markua document. (This attribute has no effect on resources inserted with three tildes.) The default value of code span resources inserted as spans with single backticks can be overridden from the default value of text to some other value by setting the default-code-span-language on the entire Markua document.

Local Code Resources

Local code resources can be inserted as a figure. In all the following examples of figures, the text in the square brackets is the figure caption, like it is in all figures.

This first figure will be a type of code and a format of guess. Leanpub which associates .rb file extensions with Ruby code will treat this as Ruby code; Leanpub which has no association for .rb files will treat it as plain text:

Here's a paragraph before the figure.

![Hello World in Ruby](hello.rb)

Here's a paragraph after the figure.

That is equivalent to:

Here's a paragraph before the figure.

{format: guess}
![Hello World in Ruby](hello.rb)

Here's a paragraph after the figure.

If you don’t want to take chances you can do this:

Here's a paragraph before the figure.

{format: ruby}
![Hello World in Ruby](hello.rb)

Here's a paragraph after the figure.

Note that the caption is optional in all figures:

Here's a paragraph before the figure.

![](hello.rb)

Here's a paragraph after the figure.

Web Code Resources

Web code resources function identically to how local code resources work, including the significance of file extensions. The only differences is that the files are on the web.

This will be a type of code and a format of guess since the file extension is not specified:

![Hello World in Ruby](http://markua.com/hello.rb)

That is equivalent to:

{format: guess}
![Hello World in Ruby](http://markua.com/hello.rb)

If you don’t want to take chances you can do this:

{format: ruby}
![Hello World in Ruby](http://markua.com/hello.rb)

Note that in the above examples of figures, the text in the square brackets is the figure caption, like it is in all figures.

Inline Code Resources

Inline code resources are the most flexible way to insert code. They are the only way to insert code as a span resource, and the most straightforward way to add short code examples as figures.

Span

The format of an inline code resource inserted as a span is:

Yada yada `some code here` yada yada.

The format of code inserted as a span defaults to text. However, you can override this by attaching an attribute list to the end of a span.

In the following example, the first statement let the format of the code default to text, whereas the second statement specifies the format of the code as ruby:

Hello World in Ruby is a simple `puts "hello world"` statement.

Hello World in Ruby is a simple `puts "hello world"`{format: ruby} statement.

Note that there is no syntactic sugar for this, since I don’t like this, and I want it to be as distasteful as possible. So, this is a sort of “syntactic salt”. Syntax highlighting does not make much sense for code which is inserted in the middle of a sentence–there’s just not enough code there for it to be worthwhile. However, in Markua, any span can have an attribute list attached to it (in order to add index entries, for example), so there is no reason to explicitly forbid specifying a format in the attribute list.

Figure

Inline code resources work great as figures.

This will be a type of code and a format of guess since three backticks are used and since the format is not specified:

Some paragraph.

```
puts "hello"
```

Some paragraph.

That is equivalent to:

Some paragraph.

```guess
puts "hello"
```

Some paragraph.

If you don’t want to take chances you can do this to explicitly specify the format:

Some paragraph.

```ruby
puts "hello"
```

Some paragraph.

This Ruby code may be formatted as such if Leanpub understands ruby. If not, the ruby format will be ignored.

If you don’t like syntactic sugar you can do:

Some paragraph.

{format: ruby}
```
puts "hello"
```

Some paragraph.

If you want a figure caption, you can add it to the attribute list with any of the above. For example:

Some paragraph.

{caption: "Hello World in Ruby"}
```ruby
puts "hello"
```

Some paragraph.

Finally, if you want the code to definitely not get syntax highlighted, you can force format to be text in one of two ways.

First, you can set it explicitly:

Some paragraph.

```text
puts "hello"
```

Some paragraph.

Second, you can use three tildes instead of three backticks, since the default with tildes is text not guess:

Some paragraph.

~~~
puts "hello"
~~~

Some paragraph.

Finally, as discussed previously, console input and output should be formatted as such by Leanpub:

```console
$ git init
Initialized empty Git repository in /path/to/repo
```

Marking Code as Added or Deleted

Markua supports marking code as added or deleted, which can be helpful if you are writing a computer programming book and want to indicate what code should be added or removed to a larger program.

The way to do this is to add special comment lines to your code.

The magic words are markua-start-insert, markua-end-insert, markua-start-delete and markua-end-delete. Any line containing one of those words will be removed completely by Leanpub before being inserted into the output.

The Leanpub will then be able to determine which code is being deleted or inserted, and format it accordingly. The recommended way for Leanpub to do this is to make code which is being inserted get bolded, and to make code which is getting deleted to be put in strikethrough.

Finally, while syntax highlighting is optional in Leanpub, if Leanpub does support syntax highlighting it is allowed for Leanpub to not do any syntax highlighting when there is the presence of any of any special markua-* comments. Syntax highlighting may make it harder to notice the added and removed code, if they are formatted with bold and strikethrough respectively.

Line Wrapping in Code Resources

Code resources should have newlines added by the author to ensure that automatic line wrapping is not relied upon. Leanpub wraps lines to ensure that all code is visible on a page, and adds backslash \ continuation characters in the output to indicate that a line has been automatically wrapped.

Math

Math can be a local, web or inline resource, just like any other resource, and the same resource syntax applies to code as to all other resources.

Leanpub currently only supports LaTeX math.

Supported Attributes for Math

The following is the supported attribute for math resources, in addition to the type, format, caption and class attributes which all resources support:

alt: The alt is the alt text, to be displayed when the mathematical equations cannot be shown. The default alt text for math is “math”. This can be provided in the figure attribute list.

Note that for math, the format is the name of the syntax used to write the mathematical equations. There are two special types of format for math baked into Markua: latex for LaTeX math and mathml for MathML math.

Inline Math Resources

Inline math resources are the most flexible way to insert math. They are the only way to insert math as a span resource, and the most straightforward way to add short math examples as figures. LaTeX math, AsciiMath and MathML can be inserted inline as a span or figure.

Span

Being able to insert a math resource as a span is important, as it lets you write things like one of the kinematic equations $d = v_i t + \frac{1}{2} a t^2$ inside sentences. This can be done with LaTeX math.

To insert math as inline math, use a $ after closing backtick for LaTeX math.

LaTeX math

There is syntactic sugar for LaTeX math which is inserted as a span, using the $ character after the closing backtick:

Here's one of the kinematic equations `d = v_i t + \frac{1}{2} a t^2`$ inside a sentence.

The $ character indicates the inline resource is LaTeX math.

If you don’t like syntactic sugar, you can also use after the inline span resource:

Here's one of the kinematic equations `d = v_i t + \frac{1}{2} a t^2`{format: latex} inside a sentence.

Figure

LaTeX math can be inserted inline as a figure, by specifying either latex or $ after three backticks, or by specifying an attribute list of {format: latex}.

All three let you produce mathematical equations like this:

$$ \left|\sum_{i=1}^n a_ib_i\right| \le \left(\sum_{i=1}^n a_i^2\right)^{1/2} \left(\sum_{i=1}^n b_i^2\right)^{1/2} $$

LaTeX math

Here’s how you do this using LaTeX math…

Here’s the version with the syntactic sugar for the format after the backticks:

Here's a paragraph before the figure.

```$
\left|\sum_{i=1}^n a_ib_i\right|
\le
\left(\sum_{i=1}^n a_i^2\right)^{1/2}
\left(\sum_{i=1}^n b_i^2\right)^{1/2}
```

Here's a paragraph after the figure.

Here’s the same thing, with the full format after the backticks:

Here's a paragraph before the figure.

```latex
\left|\sum_{i=1}^n a_ib_i\right|
\le
\left(\sum_{i=1}^n a_i^2\right)^{1/2}
\left(\sum_{i=1}^n b_i^2\right)^{1/2}
```

Here's a paragraph after the figure.

Here’s the same thing again, with a full attribute list:

Here's a paragraph before the figure.

{format: latex}
```
\left|\sum_{i=1}^n a_ib_i\right|
\le
\left(\sum_{i=1}^n a_i^2\right)^{1/2}
\left(\sum_{i=1}^n b_i^2\right)^{1/2}
```

Here's a paragraph after the figure.

Tables

Tables are important elements in many Markua documents.

Markua uses the tables that are specified by GitHub Flavored Markdown, otherwise known as GFM.

Here’s how GFM tables look:

| Header 1  | Header 2  |
| --------- | --------- |
| Content 1 | Content 2 |
| Content 3 | Content 4 |

GFM tables don’t need to line up:

| Header 1  | Header 2 |
| --- | --- |
| Content 1 | Content 2 |
| Content 3 | Content 4 Can be Different Length |

Finally, to specify column alignment, you add a colons to the header separator row. You still need at least three hyphens per header separator cell:

| Left | Middle  | Right |
| :--- |  :---:  |  ---: |
| a    | b       | c     |
| d    | e       | f     |

Supported Attributes for Tables

If there are any errors with the supported attributes for tables, such as the column-widths not adding up correctly or missing % signs, Leanpub must add these errors to a list of errors and warnings that it shows the author, and just output the table with either the erroneous attribute not set or with none of the attributes set.

The following is the supported attribute for table resources, in addition to the type, format, caption and class attributes which all resources support:

column-widths: The column widths as a comma-separated list of numbers (integers and/or floats) and/or * symbols, from left to right, as a percentage of the total table width. In this attribute value, * means for the column to use the remaining space, equally divided between it and any other column with the * attribute. Examples: {column-widths: "10%,30%,*,10%"}, {column-widths: "10%,*,40%,*"}, {column-widths: "10%, 30%, *, 12.5%"}, {column-widths: "95%, *, *"}. The numbers used for the column-widths percentages must sum to exactly 100 (if only numbers are used), or to less than 100 (if there are any *s used). Every specified value must be at least 1, and every * must compute to at least 1. The number of values (numbers or *s) must match the number of columns. Like with the width attribute, the percentage sign (%) is required, to make it absolutely clear that these are not measurements in pixels or points. Finally, the list may contain optional whitespace before and/or after each comma.
width: The width of the table, in percentage of page content area width (respecting margins). This is specified as a number (integer or float) between 1 and 100 followed by a percentage sign (%). The quotes are optional. So, you can say {width: "70%"}, {width: 70%}, {width: "70.5%"} or {width: 70.5%}.

Leanpub may do whatever it wants when outputting a table. For example, Leanpub may choose to transform the table into an image, for maximum ebook reader compatibility–but at the expense of accessibility support in newer ebook readers.

Resources

Resource Insertion Methods

Figures

Figure Attributes

Figure Captions

Figure Alt Text

Figure Captions and Alt Text Together

The Figure Attribute List Takes Precedence

Spans

Span Attribute Lists Can Be Used To Set The Format

Inserting Resources Into a Span Context

Resource Locations

Local Resources

Web Resources

Inline Resources

Resource Types and Formats

Images

Supported Attributes for Images

Local Images

Web Images

Inline Images (SVG only)

Adding a Link Around an Image

Video

Supported Attributes for Video

Local Video

Web Video

Audio

Supported Attributes for Audio

Local Audio

Web Audio

Code

Supported Attributes for Code

Default Value of the format attribute in Inline Code Samples

Local Code Resources

Web Code Resources

Inline Code Resources

Span

Figure

Marking Code as Added or Deleted

Line Wrapping in Code Resources

Math

Supported Attributes for Math

Inline Math Resources

Span

LaTeX math

Figure

LaTeX math

Tables

Supported Attributes for Tables

Default Value of the `format` attribute in Inline Code Samples