Markdown Compiler¶

Engrapha ships with a CLI tool that compiles standard Markdown files into themed PDFs. Two commands, Engrapha and pdfnotes, are installed by the Engrapha-notes package.

Quick Start¶

Engrapha notes.md --output notes.pdf --theme catppuccin-mocha

Other supported themes: dark, light, ocean-dark, forest-dark, sunset-dark, midnight-dark, ocean-light, sepia, catppuccin-latte, catppuccin-mocha.

CLI Reference¶

Basic usage¶

Engrapha input.md -o output.pdf -t catppuccin-mocha --title "My Notes" --author "Your Name"

Flags¶

Flag	Purpose
`input`	Required: path to input `.md` file
`-o, --output`	Custom output path. Defaults to `input.md` → `input.pdf`.
`-t, --theme`	Theme name. Default: `dark`.
`--title`	Document title metadata.
`--author`	Document author metadata.

Front matter (YAML)¶

Optional YAML front matter at the top of the file:

---
title: Java Programming
author: Bharat Dangi
theme: ocean-dark
---

# Chapter 1

title, author, and theme keys are honoured.

Supported Markdown Features¶

Headings¶

# Header 1 → en.part_box()
## Header 2 → en.chap_box()
### Header 3 → en.section()
#### Header 4 → en.subsection()

Body text¶

All paragraphs are rendered with en.body().

Code blocks¶

```python
en.set_theme(en.DARK)
en.body("Hello.")
```

Tables¶

| Algorithm | Best | Worst | Average |
| --------- | ---- | ----- | ------- |
| Quick Sort | O(N log N) | O(N^2) | O(N log N) |
| Merge Sort | O(N log N) | O(N log N) | O(N log N) |

Bullets¶

- First item
- Second item
- Third item

Alert Boxes¶

GitHub-style alert blocks map to Engrapha callouts:

> [!NOTE]
> Yellow bordered note box (via `en.note()`).

> [!TIP]
> Green tip box (via `en.tip()`).

> [!WARNING]
> Yellow-bordered highlight box (via `en.highlight()`).

> [!CAUTION]
> Yellow-bordered highlight box (via `en.highlight()`).

Diagram Fences¶

Eight built-in diagram block types are supported. Each block compiles to a vector diagram inside the Markdown.

```flowchart
width = 400
height = 200
caption = Figure 1: Basic Process Flow
direction = LR
terminal start "START"
process step "Compute Value"
terminal end "END"

edge start step
edge step end

Supported block types: `flowchart`, `sequence`, `layeredstack`, `schema`/`er`, `git`, `architecture`/`arch`, `c4`/`c4container`, `aws`/`cloud`.

Diagram-specific configuration values are passed at the top of the block as `key = value`.

## What gets compiled

The CLI invokes the same parser used by `en.include_markdown()`. Each block is mapped to the most appropriate Engrapha API. Unknown code-block languages are treated as syntax-highlighted code (using Pygments).

## Limitations

- Heading levels < 4 are supported; deeper than `<img_src>` HTML tags inside paragraphs are passed through verbatim.
- Front matter block must begin on line 1 of the file.
- No `LaTeX` math rendering yet (use `formula()` directly in Python instead).

## Programmatic alternative

For more control, use Python's `compile_markdown_to_pdf()`:

```python
from engrapha_notes.cli import compile_markdown_to_pdf
compile_markdown_to_pdf(
    input_file="notes.md",
    output_file="notes.pdf",
    theme_name="catppuccin-mocha",
)