Letterhead

by Johannes Kaindl
5
4
3
2
1
Score: 53/100

Description

Generate professionally formatted business letters (DIN 5008 and modern) from note frontmatter and export them to PDF via the print dialog, on desktop and iPhone.

Reviews

No reviews yet.

Stats

2
stars
1,649
downloads
0
forks
122
days
1
days
1
days
0
total PRs
0
open PRs
0
closed PRs
0
merged PRs
0
total issues
0
open issues
0
closed issues
220
commits

Latest Version

a day ago

Changelog

Fixed

  • A heading no longer stays alone at the bottom of a page. When a heading was followed by an image, table or code block that did not fit on the same page, the heading was left behind alone and the block moved to the next page. The heading now moves with it (obsidian-kit 0.96.0). This concerns the vector PDF (iPhone, iPad, and the "Export as PDF (vector)" command).

Changed

  • Mermaid diagrams are now drawn in the browser PDF. A ```mermaid block in your letter, also inside a callout or a quote, used to print as source text. The browser PDF (the main export command on the desktop) now waits for Obsidian to draw the diagram and prints it. If a diagram is not drawn within 10 seconds, it is missing from the PDF and the console says how many. The vector PDF keeps the source text.

README file from

Github

Letterhead – DIN 5008 & modern letters

🇬🇧 English · 🇩🇪 Deutsch

An Obsidian plugin that turns a note into a professionally formatted business letter — German DIN 5008 or a clean modern layout — and exports it to PDF: on desktop as a PDF file straight from the rendered letter (the OS print dialog stays available for paper), on iPhone/iPad as a real, text-selectable PDF shared with one tap.

License: AGPL-3.0 Docs: CC BY-SA 4.0 Platform

DIN 5008 (German) · Modern (English) — two layouts, two letter languages.

The letter preview, the settings tab and a note whose properties hold the letter fields.

Features

  • Letters from your notes: a note's frontmatter holds the metadata, the note body (Markdown) becomes the letter text — one command turns it into a finished, formatted business letter.
  • PDF export & printing, everywhere: one command, Export letter as PDF, picks the way itself. Desktop (macOS/Windows/Linux) → the letter is rendered as HTML/CSS and printed to a PDF file by the browser engine inside Obsidian — no print dialog, and your Custom CSS applies; iPhone/iPad → a real, text-selectable vector PDF generated inside the plugin and shared with one tap (system share sheet → “Save to Files” or send anywhere). The built-in PDF engine has no runtime dependencies and works fully offline — no network, no Electron, no Node — and renders rich letter bodies (tables, embedded images, code blocks, multi-page pagination), not just plain text. Anything it cannot represent is reported as a notice rather than silently dropped. Two more commands: Export letter as PDF (vector, fixed DIN layout) builds that vector PDF on any platform (it reads only the plain --bk-* values from your Custom CSS), and Print letter (print dialog) opens the operating system's print dialog for paper (desktop only). If the browser PDF fails, the export falls back to the vector PDF and tells you. Page margins are set automatically (page 1: 10 mm top, continuation pages: 25 mm, bottom: 20 mm) — DIN positions stay paper-exact. The mobile PDF uses the standard PDF typefaces (Helvetica/Times/Courier), so files stay tiny and open identically in any viewer.
  • Two layouts: DIN 5008 (German standard, ready for a window envelope) and Modern (international) — choose in Settings → Layout.
  • Three styles via dropdown: matter-of-fact (sans), classic (serif), technical (monospaced accents) — plus a full info block or a plain date line; both overridable per letter in frontmatter.
  • Bilingual: the plugin UI follows the Obsidian app language (English/German); the letter language is a separate setting — German or English letter labels (Anlagen/Enclosures, Ihr Zeichen/Your ref., …), switchable per letter via the sprache frontmatter field.
  • Metadata from frontmatter: recipient and sender as YAML lists, subject, salutation, closing, date, info block (incl. tax number + free-form rows), enclosures — German and English field aliases. The command Insert letter frontmatter into note scaffolds the fields; the settings tab shows a field reference.
  • Sender profile in the settings, overridable per letter (list absender/sender or individual fields).
  • Paginated preview: shows the final A4 sheets including page breaks.
  • DIN extras: fold marks (105/210 mm or 87/192 mm), hole mark (148.5 mm), print-offset fine-tuning for the envelope window.
  • No CSS required — style and info line are plain settings; for fine-tuning there are documented CSS design tokens + a one-click commented preset.
  • Fully offline — no network calls, no telemetry; rendering happens locally (Obsidian's built-in browser engine on desktop, the plugin's own PDF engine on mobile).
  • TypeScript, esbuild-bundled, no runtime dependencies, mobile-ready (isDesktopOnly: false), AGPL-3.0.

Requirements

  • Obsidian 1.8.7 or newer (desktop and mobile — the plugin is not desktop-only).
  • Desktop: macOS, Windows or Linux. Export writes a PDF file with Obsidian's built-in browser engine; the operating system's print dialog is a separate command for paper.
  • iPhone/iPad: iOS/iPadOS. Export produces a vector PDF inside the plugin and hands it to the system share sheet.
  • Nothing else. No runtime dependencies, no network access, no Node or Electron APIs — the plugin works fully offline.
  • For building from source: Node.js and npm (see Development).

Install

Repository: github.com/johannes-kaindl/obsidian-letterhead (canonical: git.jkaindl.de/jkaindl/obsidian-letterhead)

Letterhead is listed in the Community plugins browser:

  1. Open Settings → Community plugins → Browse.
  2. Search for "Letterhead" and select Install.
  3. Enable Letterhead, then fill in your sender profile in the settings.

Alternative: AnySource Sideloader

AnySource Sideloader installs and updates plugins from any git forge, independent of the Community Store.

  1. Install and enable AnySource Sideloader. (Its own first install is manual — being independent of the store is the point — but it only has to be done once, and it then keeps itself and everything else updated.)
  2. Subscribe to the catalog, which lists Letterhead alongside the other plugins from the same author: https://git.jkaindl.de/jkaindl/obsidian-catalog/raw/branch/main/catalog.json — or add just this one repository as a source: https://git.jkaindl.de/jkaindl/obsidian-letterhead
  3. Install Letterhead, then fill in your sender profile in the settings.

Updates then arrive the same way any other plugin update does.

Manual install

Download main.js, manifest.json and styles.css from the latest release and copy them into your vault.

Or download letterhead.zip from the release — it contains exactly these files — and unpack it into .obsidian/plugins/; checksums.sha256 lets you verify the download: shasum -a 256 -c checksums.sha256.

# Copy the plugin into your vault
cp manifest.json main.js styles.css versions.json \
   "<your-vault>/.obsidian/plugins/letterhead/"

# …or, from a clone with OBSIDIAN_PLUGIN_DIR exported:
npm run deploy

Then: Obsidian → Settings → Community plugins → reload → enable Letterhead → fill in your sender profile.

Usage

  1. Open a note and scaffold the fields with Insert letter frontmatter into note (or see the example), then fill them in.
  2. Run Export letter as PDF (command palette or the envelope ribbon icon). Use Open letter preview for a paginated preview first.
  3. Desktop: the PDF is written to your Output target (next to the note by default) — no dialog. For paper run Print letter (print dialog) instead and keep scaling at 100%. iPhone/iPad: the finished PDF is saved to your Output target and, where that target is share directly, handed to the system share sheet — tap Save to Files or send it anywhere.

The note body below the frontmatter is the letter text and is rendered as Markdown.

Configuration

Everything is configured in Settings → Letterhead; nothing requires CSS. The essentials:

Group What you set there
Layout & style DIN 5008 or Modern; one of three styles (matter-of-fact / classic / technical); full info block or plain date line; DIN form A (27 mm) or B (45 mm).
Sender profile Name, addition, street, postcode/city, phone, email, web — plus the return-address line for the envelope window. Every field is overridable per letter in the frontmatter.
Elements Fold marks, hole mark, print offset (shifts the content down if the address sits too high in the window), logo instead of the sender name (optionally with the name next to it).
Typography & language Font and font size overrides, date locale, letter language (German or English printed labels — separate from the plugin's UI language), default closing.
Advanced Output target, filename scheme, custom CSS.

Two settings decide where your PDF ends up and what it is called:

  • Output target — where the exported PDF is written: next to the note, into Obsidian's attachment folder, into a folder of your choice, or not saved at all and shared directly. An existing file is never overwritten; a " (2)" is appended instead. Applies to both PDF exports, not to the print dialog.
  • Filename scheme — the name of the exported PDF, and the one the print dialog proposes. Placeholders {notiz} {datum} {datum_lang} {empfaenger} {betreff} {unserzeichen}; anything else in the field is kept literally. {datum} yields YYYY-MM-DD so letters sort chronologically in a file manager, {datum_lang} prints the date as it appears in the letter.

Existing installations keep their previous behaviour (share directly, {notiz}); only fresh installations start with the new defaults. Full reference: docs/reference/settings.md.

How it works

A letter is an ordinary note. Its frontmatter carries the metadata (recipient, subject, salutation, closing, enclosures, …) and the note body is the letter text, rendered as Markdown. Field names exist as German and English aliases, so subject: and betreff: are the same field.

Export then takes one of two deliberately different routes:

  • Desktop renders the letter as HTML/CSS and prints it to a PDF file with the browser engine inside Obsidian (the same engine as the print dialog), without a dialog; the result matches what any other application on your machine would print. Print letter (print dialog) hands the same letter to the operating system's print dialog for paper. If printing to a file fails, the plugin builds the vector PDF instead and shows a notice.
  • iPhone/iPad cannot print this way, so the plugin builds the PDF itself (on desktop the command Export letter as PDF (vector, fixed DIN layout) does the same): a real, text-selectable vector PDF (PDF 1.7, standard PDF typefaces), generated on device and passed to the share sheet with one tap. Tables, embedded images, code blocks and multi-page pagination are rendered directly into the PDF. Anything the engine cannot represent is reported as a notice rather than silently dropped.

Both routes share the same geometry. DIN 5008 positions — address field, fold marks at 105/210 mm (or 87/192 mm), hole mark at 148.5 mm — are placed as absolute paper coordinates so the recipient address lines up with a window envelope. Print margins are set automatically (page 1: 10 mm top, continuation pages: 25 mm, 20 mm bottom).

Documentation

Theming

Pick a style and info-line mode directly in the settings — no CSS required. For fine-tuning beyond that, the look is driven entirely by CSS custom properties (design tokens): the Custom CSS field (Settings → Advanced) comes pre-filled with a fully commented-out preset — uncomment a line and adjust it; the Reset preset button restores that initial state after a confirmation (your previous CSS is saved to custom-css-backup.css in the plugin folder), or you can copy presets/letterhead-theme.css. Geometry tokens marked DIN-critical keep the address block aligned with the envelope window — change them deliberately. Full token list: docs/reference/theming.md.

Development

TypeScript, bundled to main.js with esbuild. main.js is build output (gitignored, not committed) — install dependencies once, then build and deploy into your vault.

npm install
npm run build     # typecheck + esbuild → main.js
npm test          # vitest
npm run gate      # typecheck (src, tests, scripts) + test + check:pure + lint + build
npm run deploy    # build, then copy manifest.json main.js styles.css versions.json → $OBSIDIAN_PLUGIN_DIR

See docs/internal/architecture.md for the full architecture notes and docs/internal/decisions.md for the reasons behind them; the remaining deliberate deviations from the workspace ts-node · obsidian-plugin profile are listed in AGENTS.md.

Privacy & security

Letterhead runs entirely on your device: no network calls, no telemetry, no tracking. The source is TypeScript in src/, readable and auditable; main.js itself is build output, not a committed file. The only btoa() call embeds your configured logo as an inline data: URL. GitHub releases built by the release workflow carry a Sigstore/SLSA build-provenance attestation, made fresh from the tagged source by GitHub Actions — confirm the main.js you run came from this source with gh attestation verify main.js --repo johannes-kaindl/obsidian-letterhead. 1.6.5 and 1.6.6 were not built that way and have no attestation; they ship checksums.sha256 instead; SECURITY.md explains what each channel proves, how to verify a build yourself in the meantime, and how to report a vulnerability.

License

Code: AGPL-3.0-or-later — see LICENSE; commercial dual-license option in LICENSING.md. Documentation/text: CC BY-SA 4.0 — see LICENSE-DOCS.