Markdown as markup language

The markup language used for the content of the book is markdown. However, it is not the plain, original markdown by Gruber (2004), but the much extended flavour used by Pandoc. Important extensions here are:

• citations
• cross references
• section, table and figure numbering
• special syntax for <div> (blocks) and <span> (inline) type elements

So, the content of the book is being written in Pandoc's markdown. It is conforming to the commonmark specification. Content in the definition here means all texts that go into the body of the book. This is different from front matter (including the foreword), back matter and metadata in general. This kind of data and texts go into different yaml metadata files, depending on the output format:

• metadata-general.yaml = overarching metadata such as the title, author, year, bibliography information, foreword, disclaimer and copyright information
• metadata-latex.yaml = information for the LaTeX produced from the source to make a PDF, such as the LaTeX document class or font options
• metadata-html.yaml = information specific to the HTML production from the source

Literal strings in the metadata files are being processed as markdown themselves when included into the Pandoc workflow. This means that texts such as the foreword or the disclaimer can themselves use markdown but are treated differently from the body text e.g. in terms of the section or page numbering. Depending on the document template used (see below), these texts will end up in specific places in the final document.

Markdown extensions

The book will make extensive use of the fenced_div extension in Pandoc. Using this extension, we will have the following syntax for various admonition blocks. These will be rendered equivalent to how e.g. MkDocs does it:

Text above the block ...

::: Note
Text in the 'note' block
:::

Text after the block ...

Currently, the following admonitions are planned:

• Note, for general notes that should stand out
• Warning, for some more alerting information
• Shell, for displaying a fossil command line, followed by its output (the latter should optically be distinct from the former)
• GoodToKnow, for hint and tips and some more advanced information

Pandoc filters

We will use various Pandoc filters to include material that needs to be processed before inclusion in the HTML and PDF. One such filter is able to render a Pikchr code section and display the rendered image in the final document. Here's the filter code.

Conversion of source texts to PDF

The PDF version will be produced via LaTeX as intermediate format and subsequently using pdflatex to make a PDF. This is all done from within Pandoc. A LaTeX template document is specifying where in the document various pieces of the markdown source texts or the metadata will be placed.

The admonitions are rendered by defining a LaTeX environment for each admonition type, then letting a Pandoc lua filter wrap the fenced_div markdown text into the correct LaTeX environment. One nice LaTeX package under consideration for this is awesomebox.

The Pandoc filter (written in Lua) looks like this for a simple noteblock environment of awesomebox that is reflecting the Note admonition:

function Div (elem)
  if FORMAT:match 'latex' then
    if elem.classes[1] == "Note" then
      return {
        pandoc.RawBlock('latex', '\\begin{noteblock}'),
        elem,
        pandoc.RawBlock('latex', '\\end{noteblock}')
      }
    else
      return elem
    end
  end
end

Conversion of source texts to HTML

The HTML version will be directly produced by Pandoc. A HTML template document is specifying where in the document various pieces of the markdown source texts or the metadata will be placed.

The idea here is that the table of contents is on the left of the page, always being visible and perhaps following down with the text as we scroll. We can also have a standard title frame with some navigation elements along the top of the page. The remaining area is then for the content. There should be buttons to go forward, backward and up in the document hierarchy. These elements can all be defined by the HTML template.

Of course, the types of admonitions used for the PDF can also be used in the HTML output. Pandoc makes HTML <div> elements from them with a corresponding class attribute. A subsequent CSS style is then needed to render the admonition as we want to have it. The CSS is then contained in the HTML template file.

Colours

Fossils main colour is a somewhat blueish, looking more like a green shade. This is the colour of the fossil animal. Staying inside this colour and creating a colour scheme from this, results in the following colours (the light gray is #e7eeef, a light shade of "mint creme"):

• yellow green crayola: #c8e28f
• dark sea green: #83b692
• mint cream: #e7efef
• shadow blue: #7584ad
• teal blue: #537789