Linking to Files and Pages

There are multiple places where you need to specify URLs to pages or paths to media files within your content. That may be a link within your markdown or a parameter for a tool or extension represented by a variable. Most of the times you would just use the buttons in the editor to open the image or linking dialogs as shown in the video below. However in some cases that's not possible. In this regard there are some rules to be observed when linking to files and pages manually.

Linking to Pages

When linking to pages manually it is important to understand how Automad is rewriting URLs and to differentiate between relative and absolute links.

Relative Page URLs

Linking to pages relatively works quite self-explanatory. You can simply link from http://yoursite.com/page to http://yoursite.com/page/subpage by simply using subpage as URL. To link to any page on the same level, next to http://yoursite.com/page, use ../page2.

Absolute Page URLs

Absolute URLs (starting with a /) specify locations relative to Automad's base directory. It is important to understand that you do not have to prepend the base URL of your Automad installation.

The root directory / is always the Automad base directory and not the server's root!

For example, if you install Automad in a subdirectoy of your page like http://domain.com/automad-subdirectory, linking to / will link to http://domain.com/automad-subdirectory and not to http://domain.com. All URLs get automatically resolved to your real base URL to maintain portability.

Linking to Files

Generally, unlike linking to pages, files have a "real" path and not a virtual URL. The real path is the actual full file system path of the file like /pages/01.pagename/filename.png and NOT /url_to_page/filename.png.

Note that it is also possible to resize images inline!

Relative File URLs

Whenever Automad finds a link using a relative path to a file or just a filename like image.png, that link is resolved relative to the current page's file system path. So linking to image.png is enough, as long as a file with that name is stored in the page's location.

Absolute File URLs

When linking to files in another location than the page's directory, it is recommended to use absoulte paths, starting from Automad's installation directory, for examplte /shared/logo.png.

Note that you can use the Copy URL to Clipboard button in the Files tabs to get a valid URLs.

Using File Patters

There are many places, where a variable is used to define a file selection. Usually those variables expect glob patterns. For example, in case your template has a gallery or slideshow, you might have a variable to define the images to be used. Using *.jpg will select all JPG files in the page's directory while gallery_*.png will select all PNG files starting with "gallery_". It is also possible to use more complex patterns like /pages/*/*.jpg to select all JPGs of all first level pages and so on. You can specify multiple patterns or files by separating them with a comma as follows:

galleryImages: *.jpg, *.png /shared/gallery_*

The above line will select all .jpg and .png files within the page's directory as well as all files within the /shared directory starting with "gallery_".

Remote Files

It is also possible to use remote file URLs side by side with glob patterns, separated by comma. Remote files will then downloaded automatically to the cache to be used together with other local files in features such as a gallery or a slideshow.

galleryImages: *.jpg, https://domain.com/image.jpg