Integrating files

You can integrate files of various types into a webpage mainly made with Aneamal. To do so, place the right file token for your file type at the start of a block or the start of a list item, either followed by a link to the file or by an embedded file. You can add a caption to your file and a hidden clue as summary for when the file is inaccessible.

File tokens

Text

[a]
Aneamal file
[a-…]
Aneamal file using a template
[b]
TSV file
[d]
TSV file with Aneamal marks
[p]
TSV file to be transposed
[q]
TSV file with Aneamal marks and to be transposed
[h]
HTML
[t]
plain-text file
[t-…]
text file to be processed by a t-module

Text files can be embedded, linked and partially loaded. Linked text files must be available locally; their address must not be an absolute URL. Text files must be UTF-8 encoded. Declare textcap metadata to change the filesize limit for linked text files.

Media

[i]
image file
[j]
image file with an automatically generated preview
[v]
video/audio file
[w]
video/audio file played in a loop

Image, video and audio files must be linked rather than embedded. They can have a local address or an absolute URL. You can also use a data URI for small files. Media files can have hints and more than one link per file.

Other

[x-…]
file to be processed by an x-module

Linked files

All supported file types can be integrated in the webpage by adding a link right after the file token, that is an arrow consisting of a hyphen and a greater-than sign followed by the file’s address:

[d]->students.tsv

In the above example, the address is simply a filename. It refers to a file in the same folder as the Aneamal file that links to it. A slash at the start of the address makes the address relative to the Aneamal root directory instead:

[a]->/bovines/akabeko.nml

You can always enclose the address in backticks, but it is usually not necessary, if you avoid whitespace and funky special characters in your file and folder names. Here is an example how to use backticks to deal with a bad name anyway:

[t]->`The Space Race.txt`

The address must be enclosed in backticks, if it starts with any of the characters @ # , ! literally, contains whitespace or any of the characters | $ ` { ^ or -> or ends in a punctuation mark , ; : . ? !. A literal backslash must be marked as literal by adding another backslash before it. Links to media files must be valid URLs.

Absolute URLs

Media files such as images and videos can be integrated from an external source using an absolute URL. This allows to reap the benefits of content delivery networks or other specialized hosting solutions for big static files. Here is an example:

[w]->https://aneamal.org/memes/kitten.webm

Integrating linked files from an external source usually implies that the remote server can gather data about your readers. Someone else in control of that server could also change the file that you linked to at any time. Be aware of these implications for the privacy and security of your readers and for the integrity of your website. There can be legal implications as well.

Partial loading

Text files support partial loading. Choose which lines to load by putting a question mark and a comma-separated list of line numbers after the filename. You can define a range of lines by its first and last line number, separated by a colon. Positive line numbers count from the start of the file, negative line numbers count from the end.

Take the file /stuff/monuments.nml which contains a bulleted list of the five monuments of cycling as an example:

<> Milan–San Remo
<> Tour of Flanders
<> Paris–Roubaix
<> Liège–Bastogne–Liège
<> Giro di Lombardia

Let’s load just the French monument as an Aneamal file:

[a]->/stuff/monuments.nml?3
  • Paris–Roubaix

The Italian monuments are the first and last of the cycling season:

[a]->/stuff/monuments.nml?1,-1
  • Milan–San Remo
  • Giro di Lombardia

Finally load the four monuments raced in spring, but in reverse order:

[a]->/stuff/monuments.nml?4:1
  • Liège–Bastogne–Liège
  • Paris–Roubaix
  • Tour of Flanders
  • Milan–San Remo

Data URIs

You can use a data URI as address of a linked file. Here is an example:

[i:red square]->data:image/webp;base64,UklGRiIAAABXRUJQVlA4TBUAAAAvVAAVAAcQ/Y/+B4CE8P++EtH/tBQA
red square

Aneamal recognizes a shorthand to announce base64-encoded UTF-8-encoded textual data for historical reasons: a comma , after the link arrow. So the two following linked files are equivalent:

[t]->data:text/plain;charset=UTF-8;base64,SGVsbG8gd29ybGQh

[t]->,SGVsbG8gd29ybGQh
Hello world!
Hello world!

It is more elegant to embed a text file than to use a data URI though.

Metadata links

You can use metadata names that have been declared with a link value in place of the address of a linked file. Consider for example that you have the following metadata declaration in your Aneamal file:

@ icon: ->/corporate-design/2023/logo.svg

If you wanted to display the logo somewhere on your webpage as well, you could create an image file link to @icon now instead of to the file’s actual address, avoiding redundancy:

[i]->@icon

Embedded files

A file with a text type can be embedded inside an Aneamal file instead of being stored as a separate file in the file system. To embed a file, put its content directly below the file token and prepend each of its lines with a vertical bar like in a code block. Here is an embedded TSV file as example:

[b]
|German	English	Roman
|eins	one	I
|zwei	two	II
|drei	three	III
|vier	four	IV
|fünf	five	V
|sechs	six	VI
German English Roman
eins one I
zwei two II
drei three III
vier four IV
fünf five V
sechs six VI

Clue

You can provide a clue for any linked or embedded file. The clue is a short, plain textual representation of the actual file. Imagine it as substitute or summary for when the file is not available or otherwise inaccessible to a reader, for example due to a disability such as blindness. The clue is placed within the file token after the file type symbol and a colon:

[v:Two birds perch in a bush.]->sparrows.mp4

Modules may give more specific instructions on how to use clues for files processed by them, that is files integrated with [t-…] or [x-…].

Caption

Any file can have a caption. Unlike a clue, the caption is always visible to readers and can contain phrase markup. A caption for an embedded file is placed directly below the file as in the following example.

[h]
|<svg width='96' height='96'>
|<circle cx='48' cy='48' r='48' fill='#c5e1ff' />
|</svg>
pale blue dot
pale blue dot

In case of linked files, the caption can be either placed after the filename and a space or in a new line below.

The caption in the following example starts with a hash # which marks a target. If a file’s caption has a target at its very beginning, the whole file becomes the target. So a click on a link to that target will make the browser jump to the photo instead of just to the caption below it.

[j]->/stuff/PIA00452.png
#*Pale Blue Dot*, photographed by Voyager 1
Pale Blue Dot, photographed by Voyager 1

For developers

Files with a caption are wrapped in an HTML figure element when Aneamal is translated to HTML. The caption becomes a HTML figcaption element and is the figure’s last child element. The above examples become:

<figure>
<svg width='96' height='96'>
<circle cx='48' cy='48' r='48' fill='#c5e1ff' />
</svg>
<figcaption>pale blue dot</figcaption>
</figure>
<figure id='pale-blue-dot'>
<a href='/stuff/PIA00452.png'><img src='/aneamal/public/jpeg/33/e993b206be2c978a4d202b42b886c.jpg' width='453' height='614'></a>
<figcaption><b>Pale Blue Dot</b>, photographed by Voyager 1</figcaption>
</figure>

Notice how the id attribute generated from the target at the start of the second example’s caption is applied to the HTML figure element.