src attribute, has some special considerations, however.
In EPUB there is no webroot concept. Therefore an
href="/css/style.css" is wrong because the leading
/ does not resolve to anything, and instead causes an error. Instead paths must always be relative to the current document. Instead you might have
Another limitation is that EPUB readers typically do not have an Internet connection. Where a website might reference a stylesheet from a CDN, or pull down images from an image service, it's really bad form to do so in an EPUB. In cases like an image or CSS file, the URL must be a local file reference and the corresponding resource file must be contained in the EPUB.
It is possible to use an
<a> tag to link to external web pages. Just be clear that in some cases the person reading the document will not be able to click on the link.
The constraints of the EPUB container mean for some special considerations when linking to content within and outside the EPUB.
There are three linking scenarios to consider:
There are two basic constraints that make linking in an EPUB different from linking on a website.
The first constraint means we cannot use an inner
/foo/bar/baz.html. Instead the file must be referenced with an appropriate
On a normal website we have a short-cut to reference files at a known location within the website hierarchy. For example, typical practice is to put CSS files in
/css, and image asset files in
/images (or similarly defined directory names). Because EPUB's don't have a webroot those URL's break. Instead all URL's have to be relative from the document that's doing the linking.
Consider an EPUB with these files
css/style.css images/logo.png chap1/intro.html chap2/install.html chap3/macosx/install.html
.html file will want to reference both
chap2/install.html the HTML would be:
<html> <head> ... <link rel="stylesheet" type="text/css" href="../css/style.css"/> ... </head> <body> ... <img src="../images/logo.png"/> ... </body> </html>
chap3/macosx/install.html the relative paths have to start with
../../ instead of just
../ because that file is located two levels deep in the file structure.
Most of these references are what you, the author, will write in your files.
atags must be written with relative URL's like this.
It's possible to use an absolute URL for both these instances, and AkashaEPUB will convert that into a relative URL. In the above example, one could put
<img src="/images/logo.png"/> and AkashaEPUB will automatically compute the relative URL.
The stylesheet link we show above is not something you will write yourself. Instead, you list stylesheets in the Configuration file, which we discuss later. (see Configuration files for AkashaEPUB projects)
AkashaEPUB does have a nice assistance feature to automatically make nice links between documents. If you leave out the anchor text from the link, AkashaEPUB will look up the
title metadata from the linked document and insert it as the anchor text.
For example, inside this guide a tag written as
<a href="2-installation.html"></a> (or in Markdown
(2-installation.html)) will be rendered as
<a href="2-installation.html">Installing the AkashaEPUB toolchain</a> (or Installing the AkashaEPUB toolchain).
Because an EPUB is presumed to be "offline", we can't write
<img src="http://example.com/images/logo.png"/>. The Internet isn't available from an EPUB, and therefore that image cannot be loaded.
EPUB3 does have a mechanism for referencing external files. Multimedia files (video, audio) can be quite large and perhaps best stored on a website rather than inside the EPUB. AkashaEPUB doesn't support such files, however.