What did that command do?

A lot happened under the covers:

• A configuration object was built for rendering documents into an HTML output directory.
• The input file was processed and written to the output, as were any assets (CSS etc).
  • This created out/TEST.html
• Puppeteer was invoked to print the HTML to PDF.
  • This created PDF/TEST.pdf

This is approximately what happened:

This diagram is itself an example of what's possible. This is a UML Activity Diagram describing a high-level overview of PDF Document Maker's internal implementation. The diagram is described in-line with the text, then formatted using PlantUML into a PNG.

This diagram names four kinds of directories. This comes from the underlying system, AkashaCMS, which supports four sets of input directories, assets, partials, layouts, and documents with these purposes.

For of the directory types there may be multiple actual directories. The directories are stacked with the later directories being higher in the stack. This forms four virtual filesystems and we refer to files using the relative pathname from the root.

In this example there is one documents directory. The file TEST.md was placed in that directory, giving it the file-system path documents/TEST.md. Because it is a file in a documents directory, it has a VPath (Virtual Path) of TEST.md which is the path we use on the command line.

No page layout template was named on the command-line. Within PDF Document Maker there is a layouts directory holding a single layout template, default.njk, which is used by default if no layout template is specified.

By default a print-oriented CSS stylesheet is used.

Look in the directory out and you'll find several files including TEST.html, which was rendered from TEST.md.

Partial templates

Partials are typically a small template meant to help format commonly used HTML structures.

For example, each document might have a metadata field (we'll discuss this later) named publicationDate which you might want to present somewhere. In the AkashaCMS Base plugin, the partial ak_publdate.html.njk is available for this purpose (in NJK format):

{% if publicationDate %}
    Date: {{ publicationDate | escape }}
{% endif %}

This can be invoked by the custom tag

<partial file-name="ak_publdate.html.njk" data-publication-date="Date String"/>

There are other methods such as the <publication-date> tag, or the akpublicationdate extension installed in Nunjucks, both of which invoke this same partial template.

Default metadata values in PDF Document Maker

As a convenience, PDF Document Maker supports command-line options for two metadata values:

• --title supplies the value for title, and overrides any existing value
• --layout supplies the value for layout, and overrides any existing value
• --publication-date supplies the value for publicationDate, and overrides any existing value

The meaning for certain metadata values

Generally the content metadata is simply data with no other defined purpose. It is up to the templates used for processing your documents define the purpose of each metadata value.

Some fields do have defined purposes:

• title serves as the page title, and might be used in the <title> tag as well as in a prominent <h1> tag at the top of the page.
• layout names the layout template to use with this document.
• publicationDate is a date string (it will be parsed by the Date class) on which the document was published.

Output directories

Two output directories are created:

Header and Footer text in the PDF

A key feature offered by word processing systems like Libre Office is placing text in the margin at the top and bottom of the page. This header and footer text usually carries a date, page number, copyright statement, and document title.

PDF Document Maker supports four options to control headers and footers:

• --template-header - A file name for a file containing an HTML snippet describing the text to use in the header
• --height-header - The height of the header area
• --template-footer - A file name for a file containing an HTML snippet describing the test to use in the footer
• --height-footer - The height of the footer area

The template files are HTML snippets where values are injected into HTML elements with specific class names. The class names are from the Puppeteer documentation:

• date formatted print date
• title document title
• url document location
• pageNumber current page number
• totalPages total pages in the document

For example, to output the text Page 2 of 42, use this template:

Page <span class="pageNumber"></span> of <span class="totalPages"></span>

For the <span> with class="pageNumber", the current page number is injected into the content of that HTML element.

An additional thing to know is that the context where the header and footer is rendered has zero CSS settings. It does not inherit the CSS of the main part of the page, and you must initialize any CSS settings required to ensure your header and footer shows up.

<div class="text-left"
  style="margin: 0 auto 0 20mm; text-align: left; font-size: 12px;">
    PDF Document Maker Organization
</div>
<div class="text-right"
  style="margin: 0 20mm 0 auto; text-align: right; font-size: 12px;">
    Page <span class="pageNumber"></span>
      of <span class="totalPages"></span>
  </div>

The text-left span has style which glues it to the left hand side of the row, sets the row to 20mm high, and sets the font-size to 12px. The text-right span is the same, but glues itself to the right-hand side of the row.

--template-header header-template.html \
--height-header 20mm \
--template-footer footer-template.html \
--height-footer 20mm 

Controlling page layout

As we discussed earlier, the --layout option lets us specify a page layout template.

Layout templates are stored in the Layouts Dirs, which we specify using the --layout-dir option.

Page styling using CSS stylesheets

We can further customize the document presentation using CSS stylesheets. The design allows us to use any number of stylesheets, and to use the LESS format for creating stylesheets.

For each kind of stylesheet we can repeat the option more than once:

$ npx pdf-document-maker ... \
    --style assets/style1.css --style assets/style2.css \
    --lesscss assets/style3.less --lesscss assets/style4.less
    ...

The filenames are VPaths. In this example, each of the CSS files are located in the assets virtual directory.

For --style parameters, the file is expected to be in CSS format, and is simply copied into the HTML output directory. These files can be either in an assets directory, or documents directory.

For --lesscss parameters, the file will be rendered using the LESS processor. This means the files must have an extension of .css.less or .less, and be in a documents directory.

Additionally, by default the PrintCSS stylesheet will be used. This is from an open source project, and is CSS for produces good looking print documents. This style-sheet can be disabled using the --no-printcss option.

Additionally, by default the Bootstrap v4 framework is used. For the PDF documents most of Bootstrap is not useful. It has powerful page layout capabilities, and certain components may be useful for creating visual effects. This framework may be disabled with the --no-bootstrap option.

All style-sheets, whether the default print.css file or those specified on the command line, are added to a list. The page layout template is expected to use either of these methods:

<!-- NJK macro for generating link tags to CSS files -->
{{ ak_core.stylesheets() }}
<!-- a custom HTML tag for the same purpose -->
<ak-stylesheets></ak-stylesheets>

Both of these convert the list of style-sheet references into <link> tags referencing the style-sheets.

Markdown extensions supported by PDF Document Maker

The Markdown ecosystem includes a wide variety of extensions, adding additional features to the language. PDF Document Maker uses the Node.js Markdown IT engine, and can in theory use any of the available plugins. Several are already bundled into the application, with these effects.

## A Markdown H2 tag
<!-- becomes -->
<h2 id="generated anchor">A Markdown H2 tag</h2>

[^1]: This is the body of the footnote.

# header {.style-me}
paragraph {data-toggle=modal}

<h1 class="style-me">header</h1>
<p data-toggle="modal">paragraph</p>

Col 1 | Col 2
------|------
Val 1 | Val 2
Val 1 | Val 2

{#id-table-one .example-table-class}

* This item has the last word in **primary**{.text-primary}
* If the final word is non-bold then this applies to the whole list item{.text-primary}
* This item is completely in secondary {.text-secondary}

* Every item in
* this list is in
* the danger color
{.text-danger}

* Non-indented list item
* Non-indented list item 2
* Non-indented list items are in "text-success" color
    * Indented list item
    * Indented list item 2
    * These items are in "text-info" color
{.text-info}

{.text-success}

Text with desired primary{.text-primary} attribute.

Other text using [bracketed span to utilize the primary]{.text-primary} attribute.

::: #warning
*here be dragons*
:::

<div id="warning">
<em>here be dragons</em>
</div>

# Header 1
Text.
### Header 2
Lorem?
## Header 3
Ipsum.
# Last header
Markdown rules!

<section>
  <h1>Header 1</h1>
  <p>Text.</p>
  <section>
    <h3>Header 2</h3>
    <p>Lorem?</p>
  </section>
  <section>
    <h2>Header 3</h2>
    <p>Ipsum.</p>
  </section>
</section>
<section>
  <h1>Last header</h1>
  <p>Markdown rules!</p>
</section>

<pre><code class="html">...</code></pre>

![This is an alt](fig.png "This is a title")

<figure>
    <img src="fig.png" alt="This is an alt">
    <figcaption>This is a title</figcaption>
</figure>

[![This is an alt](fig.png "This is a title")](http://some.where)

<figure>
    <a href="http://some.where">
      <img src="fig.png" alt="This is an alt">
    </a>
    <figcaption>This is a title</figcaption>
</figure>

<img id="..ID" figure src="..HREF" caption="..CAPTION"/>

<figure>
    <img id="..ID" src="..HREF">
    <figcaption>..CAPTION</figcaption>
</figure>

<img figure id="fig1" caption="Figure 1."
   class="some-class" width="400" style="CSS declarations"
   dest="http://example.com"
   src="./img/fig1.png"/>

<figure id="fig1" class="some-class" style="CSS">
  <a href="http://example.org">
    <img src="./img/fig1.png"/>
  </a>
</figure>

<img id="resizeto150" 
        src="img/Human-Skeleton.jpg"
        resize-width="150"
        resize-to="img/Human-Skeleton-150.jpg">

<img id="resizeto150" src="img/Human-Skeleton-150.jpg">

Table: A Caption

| A | B |
|---|---|
| 1 | 2 |
| 3 | 4 |
| 5 | 6 |

table caption {
    caption-side: top;
    font-weight: bold;
    font-style: italic;
    font-size: larger;
}

table.table-caption-above caption {
    caption-side: top;
}
table.table-caption-below caption {
    caption-side: bottom;
}

Table: A Caption Above

| A | B |
|---|---|
| 1 | 2 |
| 3 | 4 |
| 5 | 6 |

{.table-caption-above}

::: .card-group

::: .card
::: .card-body

CONTENT FOR FIRST CARD GROUP

:::
:::

::: .card
::: .card-body

CONTENT FOR SECOND CARD GROUP

:::
:::

:::

<div class="card-group">
  <div class="card">
    <div class="card-body">
      CONTENT FOR FIRST CARD GROUP
    </div>
  </div>
  <div class="card">
    <div class="card-body">
      CONTENT FOR SECOND CARD GROUP
    </div>
  </div>
</div>

Using draw.io diagrams in PDF Document Maker

The first, draw.io, is a diagramming tool with a built-in clip art library useful for software engineering, hardware deployment, and other technical fields. It is very easy to use, and with it one can quickly create complex diagrams.

To learn about the application, visit https://www.drawio.com/

To use it online, visit https://draw.io

There is an open-source desktop application, where the GitHub repository is at: https://github.com/jgraph/drawio-desktop However, on drawio.com there is a download link going back to the GitHub repository. And, the desktop application may be available via package management systems. On Linux, it is available via Flathub.

Once you've drawn an image, the best way to proceed is to save the drawing as PNG.

On this screen you choose the export options.

The "include a copy of my diagram" ensures that the PNG can be edited by draw.io in the future. That is, the resulting PNG has information about the drawing such that draw.io can recreate the editing experience.

The diagram is easy to include in Markdown using the normal image tag.

![Example diagram](./img/example-drawio-diagram.png)

Which results in the following:

If in the future you need to edit the diagram, simply load the PNG file back into draw.io. When done editing the file make sure to save it using the same procedure.

Using PlantUML diagrams in PDF Document Maker

PlantUML - https://plantuml.com/ - is a versatile tool for creating a number of diagrams useful in software engineering and related fields. As the name suggests it focuses mostly on UML diagrams.

With PlantUML you create a textual description of the diagram to create. The description is placed inline with the Markdown file. When the document is rendered to HTML, the description is converted to an SVG representation of the description.

The conversion can be disabled by using the --no-md-plantuml option.

@startuml

start

if (Graphviz installed?) then (yes)
  :process all\ndiagrams;
else (no)
  :process only
  __sequence__ and __activity__ diagrams;
endif

stop

@enduml

In PDF Document Maker, we use the custom tag <diagrams-plantuml> to insert a PlantUML diagram.

It looks like this:

<diagrams-plantuml input-file="img/activity-1.puml"
    output-file="activity-1.png" tpng/>

The above diagram, in this case, is saved in the file activity-1.puml in the img subdirectory. The file is read in, and passed to PlantUML for rendering.

That renders as so:

The rendered version is an <img> tag with a src attribute referencing the file named in the output-file attribute.

To render it as SVG replace tpng with tsvg.

<diagrams-plantuml input-file="img/activity-1.puml"
    output-file="activity-1.svg" tsvg/>

That renders as so:

Both tsvg and tpng are properties, not attributes, and they should be used in this way without an attribute value.

<diagrams-plantuml
      output-file="activity-1-inline.png" tpng>
@startuml

start

if (Graphviz installed?) then (yes)
  :process all
   diagrams;
else (no)
  :process only
  __sequence__ and __activity__ diagrams;
endif

stop

@enduml
</diagrams-plantuml>

Which renders as so:

In this case no input-file is given. Instead, the input comes from the element body.

Using MermaidJS diagrams in PDF Document Maker

Mermaid - https://mermaid.js.org/ - is similar to PlantUML. It supports a variety of diagrams, mostly in the UML bailiwick. One creates a textual description o the diagram, pasting it into a Markdown document.

Unlike with PlantUML we were unable to integrate Mermaid such that a code block with the mermaid class would be automatically rendered as an inline SVG.

The most convenient path is to install Mermaid-CLI - https://github.com/mermaid-js/mermaid-cli

In your project directory do this:

$ npm install @mermaid-js/mermaid-cli --save

This installs a program you can run as so:

$ npx mmdc --help
Usage: mmdc [options]

Options:
  -V, --version                                   output the version number
  -t, --theme [theme]                             Theme of the chart (choices: "default", "forest", "dark", "neutral",
                                                  default: "default")
  -w, --width [width]                             Width of the page (default: 800)
  -H, --height [height]                           Height of the page (default: 600)
  -i, --input <input>                             Input mermaid file. Files ending in .md will be treated as Markdown
                                                  and all charts (e.g. ```mermaid (...)``` or :::mermaid (...):::)
                                                  will be extracted and generated. Use `-` to read from stdin.
  -o, --output [output]                           Output file. It should be either md, svg, png, pdf or use `-` to
                                                  output to stdout. Optional. Default: input + ".svg"
  -e, --outputFormat [format]                     Output format for the generated image. (choices: "svg", "png",
                                                  "pdf", default: Loaded from the output file extension)
  -b, --backgroundColor [backgroundColor]         Background color for pngs/svgs (not pdfs). Example: transparent,
                                                  red, '#F0F0F0'. (default: "white")
  -c, --configFile [configFile]                   JSON configuration file for mermaid.
  -C, --cssFile [cssFile]                         CSS file for the page.
  -I, --svgId [svgId]                             The id attribute for the SVG element to be rendered.
  -s, --scale [scale]                             Puppeteer scale factor (default: 1)
  -f, --pdfFit                                    Scale PDF to fit chart
  -q, --quiet                                     Suppress log output
  -p --puppeteerConfigFile [puppeteerConfigFile]  JSON configuration file for puppeteer.
  -h, --help                                      display help for command

A sample Mermaid diagram is:

stateDiagram-v2
title: Simple sample

    [*] --> Still
    Still --> [*]

    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]

This must be saved as a separate file in the file-system. For example, a subdirectory img is a useful place to store images. In that case, save the text in a file ./img/simple-sample-1.mmd.

npx mmdc -i documents/guide/img/simple-sample-1.mmd \
  -o documents/guide/img/simple-sample-1.svg \
  --outputFormat svg

The -i option specifies the input file, and -o the output file. Hence, this converts to an output file in the same directory the SVG version of the diagram.

The result looks like so:

Let's talk a little about rendering SVG images in HTML. SVG is a vector image format, meaning that an SVG file contains commands for drawing lines and circles and the like. It also means SVG files do not have a defined width/height, unlike pixel image formats. Therefore SVG files can scale to any amount with no pixelation.

Initially, as a result, this image filled an entire page in the PDF file.

One way to give an SVG file a size is by editing the SVG to set width=, height= and other parameters. But the simplest way is to use HTML directly like so:

<figure>
  <img width="300px" src="./img/simple-sample-1.svg"/>
  <figcaption>Simple Sample 1</figcaption>
</figure>

This <img> is displaying the SVG, and is defined with a 300 pixel width. The SVG then renders to that size.

Next is to automate building the images before building the document. Earlier we went over using the scripts tag in package.json. Let's add to that workflow.

First, add a command to build each Mermaid file:

"build:sample-1": "npx mmdc -i documents/guide/simple-sample-1.mmd -o documents/guide/simple-sample-1.svg --outputFormat svg",
"build:guide": "npm-run-all build:sample-1 build:render",

We take the same command, and add it to the script. The tag name format is build:file-name.

The build:guide script contains the complete build procedure.

The resulting SVG file can be referenced from Markdown using:

![Simple Sample 1](./img/simple-sample-1.svg)

This is a normal Markdown image tag which will contain the alt-text Simple Sample 1.

But, if you have multiple files to render it's more efficient to use the Mermaid CLI API in a script like this:

import { run } from "@mermaid-js/mermaid-cli"

console.log(".../img/mahabhuta-workflow.mmd");
await run(
   "./documents/guide/img/mahabhuta-workflow.mmd",
   "./documents/guide/img/mahabhuta-workflow.svg",
);

console.log(".../img/pdf-document-workflow.mmd");
await run(
    "./documents/guide/img/pdf-document-workflow.mmd",
    "./documents/guide/img/pdf-document-workflow.svg",
);

console.log(".../img/simple-sample-1.mmd");
await run(
    "./documents/guide/img/simple-sample-1.mmd",
    "./documents/guide/img/simple-sample-1.svg",
);

console.log(".../img/simple-sample-2.mmd");
await run(
    "./documents/guide/img/simple-sample-2.mmd",
    "./documents/guide/img/simple-sample-2.svg",
);

This should save the time required to initialize Puppeteer four times.

./documents/guide/img/mahabhuta-workflow.mmd
Generating single mermaid chart
file:///home/david/Projects/akasharender/pdf-document-construction-set/guide/node_modules/@puppeteer/browsers/lib/esm/launch.js:303
                reject(new Error([
                       ^

Error: Failed to launch the browser process!
[254374:254374:0128/141251.817539:FATAL:zygote_host_impl_linux.cc(128)] No usable sandbox! If you are running on Ubuntu 23.10+ or another Linux distro that has disabled unprivileged user namespaces with AppArmor, see https://chromium.googlesource.com/chromium/src/+/main/docs/security/apparmor-userns-restrictions.md. Otherwise see https://chromium.googlesource.com/chromium/src/+/main/docs/linux/suid_sandbox_development.md for more information on developing with the (older) SUID sandbox. If you want to live dangerously and need an immediate workaround, you can try using --no-sandbox.

TROUBLESHOOTING: https://pptr.dev/troubleshooting

High quality equation (mathematical and chemical) rendering with KaTeX

KaTeX is a LaTeX/TeX-inspired format for rendering beautiful mathematical equations. Like with PlantUML and Mermaid, the model is to describe math equations in a textual format, which is rendered by KaTeX into the equations written by real mathematicians.

For example, take this

\sqrt{3x-1}+(1+x)^2

This is describing the square-root of 3x-1 plus 1+x squared.

In a Markdown document, the KaTeX string is surrounded with dollar signs like so:

$\sqrt{3x-1}+(1+x)^2$

Which is then rendered this way:

$\sqrt{3x-1}+(1+x)^2$

And, the equation can be put in the middle of a sentence, $\sqrt{3x-1}+(1+x)^2$, like so. This of course must be used carefully because a large equation might not look very good in the middle of a paragraph. This particular equation is about the same visual height as the line of text, which leaves the paragraph remaining to look normal.

While simple equations like $n!$ or $y^2$ renders nicely in a paragraph, a larger equation like $\begin{bmatrix} a & b \\ c & d \end{bmatrix}$ is unlikely to work when placed in-line with text in a paragraph. The issue has to do with the visual height of the taller equation in contrast to the height of text lines.

Here's some examples of taller equations displayed between paragraphs:

$$\begin{gather}
   a=b \\
   e=b+c
\end{gather}$$

$$\begin{CD}
   A @>a>> B \\
@VbVV @AAcA \\
   C @= D
\end{CD}$$

$$\begin{equation}
  \begin{pmatrix}
    A & B \\ B & C
  \end{pmatrix} 
\end{equation}$$

Which renders as:

The difference is that the delimiters $ .. $ are for inline equations, while $$ .. $$ are for what's called "block" or "display" rendering.

This also supports the mhchem extension for KaTeX which supports writing chemistry equations:

$\ce{CO2 + C -> 2 CO}$

$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$

$\ce{A -> B}$

$\ce{A ->[H2O] B}$

$\ce{A ->[{text above}][{text below}] B}$

Those are rendered as:

$\ce{CO2 + C -> 2 CO}$

$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$

$\ce{A -> B}$

$\ce{A ->[H2O] B}$

$\ce{A ->[{text above}][{text below}] B}$

References:

• https://www.npmjs.com/package/markdown-it-texmath
• https://katex.org/
• https://mhchem.github.io/MathJax-mhchem/

This feature can be disabled using the --no-md-katex option.