In this chapter we'll learn how to use AkashaRender to generate the XHTML, CSS files, and asset files used in your eBook. In later chapters we'll look into packaging those files into an EPUB. Generating these files in AkashaEPUB leverages AkashaRender and a couple plugins for EPUB-specific features.
The AkashaRender model is writing files in an easy-to-write markup format like Markdown, processing the files with partials and templates, generating HTML, then packaging the HTML for the destination. Each destination has its own packaging and delivery considerations. With AkashaCMS the destination is a web server for display on web browsers, and for AkashaEPUB the destination is an EPUB ebook reader.
In a later chapter we'll make a deep dive into the configuration files. Understanding this section requires a little preview of the Configuration object.
Content files are stored in two kinds of directories:
|Directory type||Config method||Discussion|
||Files that are simply copied to the
||Files requiring processing (a.k.a. rendering), with the rendered result copied to the
There is only one RenderDestination directory. With AssetsDir, DocumentsDir, LayoutsDir, and PartialsDir, there can be and often are multiple directories, since each is an array/list. When AkashaRender looks for an instance of a given type of file, it searches each directory in the the corresponding list stopping on the first match.
We'll go over details of the configuration in a later section: Configuration files for AkashaEPUB projects You can read more about AkashaCMS configuration at: http://akashacms.com/akasharender/configuration.html
AkashaRender detects which files require what processing by inspecting the file name extension. The rendering process is named by the extension as so:
||A Markdown file, that produces HTML.|
||for HTML with EJS markup, that produces HTML.|
||for PHP with EJS markup, that produces PHP.|
||Straight HTML, copied with no processing.|
||A LESS file, that produces CSS.|
Hence, a RenderDestination file named
css/style.css could either come from an AssetsDir file
css/style.css or a DocumentsDir file
css/style.css.less. Likewise, a RenderDestination file
chapter2/install.html must come from a DocumentsDir file named either
chapter2/install.html.ejs or simply
You can use any directory hierarchy that you wish. AkashaRender creates in the rendering directory the structure you create in the DocumentsDir and AssetsDir directories. For the purpose of packing EPUB's, authors must remember the directory named
META-INF cannot be used for your content. AkashaEPUB automatically generates that directory, because it has special significance to packaging EPUB files.
Some files in DocumentsDir's render to HTML, depending on their file extension. These files use a fairly straightforward file format supporting metadata in addition to the content.
--- layout: page.html.ejs title: Four Scores and Seven Years Ago --- Four score and seven years ago our forefathers brought forth ...
The first part, between the
--- lines, is the metadata, a.k.a. frontmatter. The rest is the content. The content will be rendered through the processing steps dictated by the filename. The metadata is used by the rendering process in various ways. The
layout tag declares the layout template, and the
title tag gives the page title, for example.
If the file ends in
.html.md the content will be treated as Markdown and rendered through the Markdown processor. If it ends in
.html.ejs the content will instead be rendered through the EJS template engine.
At its simplest the metadata follows a simple
tag: value system:
--- tag1: value1 tag2: value2 tag3: value3 --- The lazy brown fox jumped over the quick green tortoise causing many heads to be scratched.
The metadata section is actually YAML (
https://en.wikipedia.org/wiki/YAML). Most of the time we'll simply use
tag: value constructs in the metadata. But by using YAML, AkashaRender has the flexibility to use structured data when it's needed.
Many more details about the docuyment format are available at: http://akashacms.com/akasharender/3-create-content.html
Metadata comes not just from the frontmatter in the content document. The configuration file can declare metadata as well.
addDocumentsDir()in the configuration file
The metadata is carried alongside the content all through AkashaRender's processing. The purpose of the metadata is to either instruct choices made at different rendering steps, or to provide data that's rendered into the document.
An example of an instruction to the rendering process is the
layout metadata tag. It tells the system the layout template to use for the final rendering.
--- layout: template-file-name.html.ejs title: The quick brown fox ... other metadata --- .... content
Depending on the value in
layout one template file or another will be used. That choice determines the final rendered output.
Some rendering modules can inject the metadata into the rendered document. For example, with the EJS template engine every metadata value is available as a variable inside the template.
This EJS snippet brings the
title value into the rendered document:
<h1><%= title %></h1>
For more information on both, see: http://akashacms.com/akasharender/layouts-partials.html