@cenk1cenk2/md-printer 3.2.24 → 3.4.0

package/README.md

@@ -92,7 +92,7 @@ Markdown files take YAML front-matter. For YAML input the same keys are top-leve
 
 | Key               | Description                                                                                   |
 | ----------------- | --------------------------------------------------------------------------------------------- |
-| `template`        | Built-in template name or path to a template directory.                                       |
+| `template`        | Built-in template name, path to a template directory or an object, see [Template sources](#template-sources). |
 | `dest`            | Output file, relative to the current directory, not to the input file.                        |
 | `outputFiletype` | `pdf` (default) or `html`.                                                                    |
 | `language`        | Language for template translations.                                                           |
@@ -100,6 +100,8 @@ Markdown files take YAML front-matter. For YAML input the same keys are top-leve
 | `documentTitle`  | Document title.                                                                               |
 | `pdfOptions`     | Puppeteer [PDF options](https://pptr.dev/api/puppeteer.pdfoptions), merged over the defaults. |
 | `sign`            | Signing options, see [Signing](#signing).                                                     |
+| `attachments`     | PDFs merged into the output, see [Attachments and compression](#attachments-and-compression). |
+| `compress`        | `true` compresses the images of the whole output PDF, attachments included.                   |
 
 A template may carry a `settings.json` with defaults for its documents:
 
@@ -133,6 +135,29 @@ pdfOptions:
 - `continuous` is enabled when any of `--continuous`, front-matter or `settings.json` enables it.
 - The document title is `--title`, then `documentTitle`, then the `<title>` set by the template, then the input file name.
 
+## Attachments and compression
+
+PDF output can carry other PDFs, such as certificates or reference letters, and can be compressed.
+
+```yaml
+---
+compress: true
+attachments:
+  - file: ./assets/references/diploma.pdf
+    position: before
+  - file: https://example.com/certificate.pdf
+    position: 2
+    compress: true
+  - file: ./assets/references/letter.pdf
+---
+```
+
+- `file` is a path relative to the input file, confined to its directory like every other local asset, or an `http(s)` URL.
+- `position` is `before` the document, `after` it (the default) or a page number: the attachment starts at that page of the rendered document, so `2` places it between the first and the second page, and the page after the last one appends it. Page numbers always count pages of the rendered document, not of other attachments, and attachments sharing a position keep the order they are listed in.
+- `compress: true` on an attachment re-encodes its images, `compress: true` at the top level does the same for the whole output, attachments included. Images are scaled down to at most 2000px and stored as JPEG at quality 75 whenever that makes them smaller; masks and images with transparency keep their lossless encoding.
+- Attachments and compression are applied before signing, so a signature covers them. They are only supported for PDF output.
+- `--preview` rebuilds when a local attachment changes.
+
 ## Development
 
 ```sh
@@ -152,25 +177,93 @@ md-printer document.md out.pdf --preview --no-open
 
 ### Built-in templates
 
+Every built-in template is a package of its own, `@cenk1cenk2/md-printer-template-<name>`. md-printer depends on all of them, so they install with it, and each one brings the fonts, icons and stylesheets it uses as its own dependencies. `default`, `kilic.dev` and `mail` are published from the `templates/` directory of this repository, `cv` from https://gitlab.kilic.dev/cenk/cv and `invoice` from https://gitlab.kilic.dev/cenk/invoices.
+
 | Name        | Description                                                                                                    |
 | ----------- | -------------------------------------------------------------------------------------------------------------- |
 | `default`   | GitHub-flavoured Markdown styling with Montserrat. This is the default.                                        |
 | `kilic.dev` | Same styling with a logo in the header and a footer with title and page numbers.                               |
 | `invoice`   | Invoice from YAML data (`company`, `client`, `payment`, `items`, `currency`, `date`, `id`) and Markdown notes. Translations in `en` and `de`, a signature block when signing. See `test/invoice.md`. |
+| `cv`        | CV in the table layout of a classic Word CV, from front-matter (`name`, `suffix`, `title`, `tagline`, `photo`) and Markdown sections placed with the `::section`, `:::details` / `::detail` / `:::pair`, `:::entry`, `::::group` / `:::course`, `::skill`, `:::note` and `:::languages` / `::language` components. The PDF is tagged and has an outline, so screening tools read it as text. See `test/cv.md`. |
 | `mail`      | Plain content with no margin and Tailwind typography, meant for HTML output.                                   |
 
+### Template sources
+
+`-t` and a string `template` in front-matter take a built-in name or a path. A value without a path separator is a built-in name, anything with `/` or starting with `.` or `~` is a path, relative to the current directory.
+
+`template` in front-matter can also be an object selecting the source by `type`. This is the only way to use a template from an npm package.
+
+```yaml
+---
+template:
+  type: package
+  name: '@cenk1cenk2/md-printer-template-cv'
+---
+```
+
+| `type`      | Keys                 | Description                                                                                                                                                                                                                                                  |
+| ----------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `builtin`   | `name`               | The package `@cenk1cenk2/md-printer-template-<name>` from md-printer's own dependencies.                                                                                                                                                                     |
+| `package`   | `name`, `directory?` | An npm package, resolved from the directory of the input file (its `node_modules`, walking up like Node does), then from the current directory, then from md-printer's own dependencies. The package directory is the template directory. `directory` selects a subdirectory of the package instead, and may not leave the package, symlinks included. |
+| `directory` | `path`               | A template directory, relative to the directory of the input file.                                                                                                                                                                                           |
+
+The same on the command line, where flags win over front-matter. `--template-type` says how to read `-t`, and `--template-directory` is the `directory` of a package. A `--template-type directory` path is relative to the input file too. Without `--template-type`, `-t` is a built-in name or a path as above.
+
+```sh
+md-printer document.md --template-type package -t @cenk1cenk2/md-printer-template-cv
+md-printer document.md --template-type package -t my-templates --template-directory letters
+md-printer document.md --template-type builtin -t cv
+md-printer document.md --template-type directory -t ./template
+```
+
+An unknown `type`, a missing or unknown key, or a `package` that is not installed fails the run. A package has to allow access to its `package.json`, so one with an `exports` map lists `./package.json` there.
+
 ### Authoring a template
 
-A template is a directory. Pass it with `-t ./path` or `template: ./path`. A value without a path separator is a built-in name, anything with `/` or starting with `.` or `~` is a path.
+A template is a directory. Pass it with `-t ./path`, `template: ./path` or as one of the other [template sources](#template-sources). Its Svelte files and its TypeScript are kept apart, so ESLint, Prettier and tsconfig can target each group:
 
 ```
 my-template/
-  Template.svelte   required
-  settings.json     optional
-  i18n/             optional, en.yaml, de.json, ...
-  components/       optional, *.svelte placed from markdown, see Markdown components
+  package.json             optional, see below
+  settings.json            optional, always at the root
+  i18n/                    optional, en.yaml, de.json, ...
+  template/
+    Template.svelte        required
+    components/*.svelte    optional, placed from markdown, see Markdown components
+  src/
+    extension.ts           optional, see Extension module
+    *.ts                   optional, plain modules
 ```
 
+`files` in `settings.json` moves any of these. Every key is optional and defaults to the layout above:
+
+```json
+{
+  "files": {
+    "template": "template/Template.svelte",
+    "components": "template/components",
+    "extension": "src/extension.ts",
+    "i18n": "i18n"
+  }
+}
+```
+
+- `components`, `extension` and `i18n` also take an array, read in order: a component of a later folder replaces one of the same name, an export of a later extension module replaces one of the same name, and a key of a later i18n folder replaces the same key while nested keys merge. Use this to share components or translations between templates:
+
+  ```json
+  {
+    "files": {
+      "components": ["template/shared", "template/components"],
+      "extension": ["src/format.ts", "src/extension.ts"],
+      "i18n": ["i18n/shared", "i18n"]
+    }
+  }
+  ```
+
+- Paths are relative to the template directory. A path leaving it, a path that does not exist and an unknown key each fail the build.
+- A template written for 3.x keeps working: for each key `files` does not set, when the default location is missing, the root location is used if it exists, that is `Template.svelte`, `components/` and `extension.*`. A path set in `files` never falls back.
+- A package keeps what it does not publish out with an `.npmignore`, as the built-in templates do, for example `release.config.cjs` and `CHANGELOG.md`.
+
 `Template.svelte` is a Svelte 5 component receiving these props:
 
 | Prop        | Description                                                                                  |
@@ -180,10 +273,15 @@ my-template/
 | `t`         | i18next translate function, loaded from `i18n/<language>.(yaml\|yml\|json)`.                |
 | `language`  | The resolved language.                                                                       |
 | `signature` | `{ date, name?, issuer?, serial? }` while signing is enabled, otherwise `undefined`.         |
+| `extension` | The named exports of the [extension module](#extension-module), empty without one.           |
 
 Set the document title with `<svelte:head><title>...</title></svelte:head>`.
 
-Styles that need Tailwind CSS v4 or package imports go into a `<style lang="postcss">` block in `Template.svelte` or any component it imports. These blocks are collected and compiled together, so they can `@import 'tailwindcss'` and use `@plugin`, `@theme` and utility classes. Plain `<style>` blocks stay scoped Svelte styles. `@import` of packages (for example `@fontsource/*`, `github-markdown-css`) resolves from the template directory first and also from md-printer's own dependencies, so the template does not need a `node_modules`. The selected highlight.js theme is always included. Local `url()` and image references are inlined as data URIs.
+Components may be written in TypeScript with `<script lang="ts">`, and `.ts` modules can be imported, as `./round.js` or `./round.ts`. Svelte strips the types of components, so only type annotations are allowed there, no enums or other TypeScript that emits code; `.ts` modules take full TypeScript. Types are not checked while rendering. The built-in templates are written this way.
+
+A template can bring its own dependencies: give the template directory a `package.json` and install it there, as the built-in templates do. Imports in components, `.ts` modules, `@import` in `<style lang="postcss">` and imported images such as `@fortawesome/fontawesome-free/svgs/solid/user.svg` resolve from the template's `node_modules` first and fall back to md-printer's own dependencies. md-printer does not install them for you; a missing one fails the build with the directory to install it in.
+
+Styles that need Tailwind CSS v4 or package imports go into a `<style lang="postcss">` block in `Template.svelte` or any component it imports. These blocks are collected and compiled together, so they can `@import 'tailwindcss'` and use `@plugin`, `@theme` and utility classes. Plain `<style>` blocks stay scoped Svelte styles. `@import` of packages (for example `@fontsource/*`, `github-markdown-css`) resolves from the template directory first and then from md-printer's own dependencies, which cover `tailwindcss` and the highlight.js themes. The selected highlight.js theme is always included. Local `url()` and image references are inlined as data URIs.
 
 Images are imported, which inlines them as data URIs:
 
@@ -195,6 +293,31 @@ Images are imported, which inlines them as data URIs:
 <img src={logo} alt="logo" />
 ```
 
+#### Extension module
+
+A template may contain one extension module, `src/extension.ts`, `.mts`, `.cts`, `.js`, `.mjs` or `.cjs`, so the template can bring its own functions. More than one at the default location fails the build, naming the files; to combine several modules, list them in `files.extension`.
+
+```ts
+// src/extension.ts
+export function money(value: number): string {
+  return `${value.toFixed(2)} EUR`
+}
+```
+
+It is compiled in the same bundle as the template, so TypeScript works and its imports resolve like those of the template's own modules, from its `node_modules` first. Its named exports are available as the `extension` prop of `Template.svelte`, through the `md-printer:extension` context with `getContext`, and in any component with the `getExtension` helper:
+
+```svelte
+<script lang="ts">
+  import { getExtension } from '@cenk1cenk2/md-printer/components'
+
+  const { money } = getExtension<typeof import('../../src/extension.js')>()
+</script>
+
+<span>{money(12)}</span>
+```
+
+The default export is left out. An extension only exposes its exports, md-printer calls none of them by itself. `--preview` rebuilds when the module changes, is added or is removed.
+
 #### Shared components
 
 Import from `@cenk1cenk2/md-printer/components`:
@@ -208,7 +331,9 @@ Import from `@cenk1cenk2/md-printer/components`:
 | `TotalPages`     | Total page count, filled by Chrome. Header and footer only.                                       |
 | `Title`          | Document title, filled by Chrome. Header and footer only.                                         |
 | `Date`           | Print date, filled by Chrome. Header and footer only.                                             |
-| `SignatureBlock` | Visible signature block for the `signature` prop. Needs Tailwind in a `<style lang="postcss">` block. Optional `labels` prop overrides its texts. |
+| `Localized`      | Text for the language of the document from props named after languages, `<Localized en="Invoice" de="Rechnung" />` or `:localized{en="Invoice" de="Rechnung"}`, for words that need no entry in `i18n/`. Takes the language, then its base language (`de` for `de-AT`), then `fallback`, otherwise nothing. In a template a prop can also be a snippet for markup. Plain text without a wrapper element. |
+| `Translate`      | Text translated with the `i18n/` directory of the template, `<Translate key="present" />` or `::translate{key="present"}`, inline as `:translate{key="present"}`. Plain text without a wrapper element. Optional `fallback` for a missing key, otherwise the key itself is printed. |
+| `SignatureBlock` | Hands the signature, `{ date, name?, issuer?, serial? }`, to its `children` snippet, so the template draws the visible block with its own markup and styles. Takes the `signature` prop, or as `::signature-block` the signature of the document. Renders nothing without a signature or without `children`, so a template gives `::signature-block` its markup with its own `template/components/SignatureBlock.svelte`, see below. |
 
 ```svelte
 <script>
@@ -234,10 +359,32 @@ Import from `@cenk1cenk2/md-printer/components`:
 
 #### Markdown components
 
-Every `*.svelte` file in the template's `components/` directory can be placed from markdown, see [Components](#components). The shared components can be placed the same way, for example `::page-break` or `::signature-block`, except `Markdown`. A template component with the same name as a shared one replaces it.
+Every `*.svelte` file in the template's `template/components/` directory can be placed from markdown, see [Components](#components). The shared components can be placed the same way, for example `::page-break` or `::signature-block`, except `Markdown`.
+
+A template replaces or extends any shared component, `SignatureBlock` and `Translate` included, with a file of the same name in `template/components/`:
+
+- **Replace:** `template/components/SignatureBlock.svelte` is what `::signature-block` renders from then on. This is about directives: a component that imports `SignatureBlock` from `@cenk1cenk2/md-printer/components` keeps getting the original, so import `./components/SignatureBlock.svelte` to use the replacement in the template itself.
+- **Extend:** that import always reaches md-printer's original, also from a file with the same name, so a component can wrap it:
+
+```svelte
+<!-- template/components/SignatureBlock.svelte -->
+<script>
+  import { SignatureBlock } from '@cenk1cenk2/md-printer/components'
+
+  let props = $props()
+</script>
+
+<SignatureBlock {...props}>
+  {#snippet children(signature)}
+    <section class="my-8">
+      <strong>Digitally signed</strong> by {signature.name} on {signature.date}
+    </section>
+  {/snippet}
+</SignatureBlock>
+```
 
 ```svelte
-<!-- components/Callout.svelte -->
+<!-- template/components/Callout.svelte -->
 <script>
   import { getContext } from 'svelte'
 
@@ -277,7 +424,7 @@ md-printer invoice.yaml -t invoice --sign --sign-certificate ~/id-austria.pem
 - Signing only works for PDF output and is skipped with `--preview`.
 - The signing session has to run in your browser. md-printer opens a temporary local page in an app window of the discovered browser, using your normal profile (or with `xdg-open` when none is found), you log in with ID Austria in the A-Trust page, and paste the resulting signature (starts with `MII`) back into the local page. A paste that is cut short is refused on the page, so you can copy it again. It waits until the signature arrives, press Ctrl+C to abort.
 - The returned signature is always verified before it is embedded: its digest must match this document and it must be cryptographically valid. The result is printed with the signer name, serial and issuer. A failed verification fails the run, and with `--log-level debug` the returned signature is written next to the output as `<output>.cms.der`.
-- With a certificate, the signer name, issuer and serial are passed to the template as `signature`, so `SignatureBlock` can show who signed and when. The certificate must be valid at signing time, and the returned signature is rejected if it was not made with it. Without a certificate only the date is available.
+- With a certificate, the signer name, issuer and serial are passed to the template as `signature`, so the template can show who signed and when through `SignatureBlock`. The certificate must be valid at signing time, and the returned signature is rejected if it was not made with it. Without a certificate only the date is available.
 - Verify the result at https://www.signaturpruefung.gv.at.
 
 ## Migrating from 2.x
@@ -302,58 +449,67 @@ Renders a markdown or yaml file through a Svelte template into a PDF or HTML doc
 USAGE
   $ md-printer  [FILE] [OUTPUT] [--log-level
     silent|direct|fatal|error|warn|info|verbose|debug|trace] [-I] [-f
-    md|yaml|yml] [-F pdf|html] [-O] [-t <value>] [-T <value>] [-l <value>] [-b
-    <value>] [--continuous] [-p] [--host 127.0.0.1|localhost|::1] [--port
-    <value>] [--open] [--sign] [--sign-provider a-trust] [--sign-certificate
-    <value>]
+    md|yaml|yml] [-F pdf|html] [-O] [-t <value>] [--template-type <value>]
+    [--template-directory <value>] [-T <value>] [-l <value>] [-b <value>]
+    [--continuous] [-p] [--host 127.0.0.1|localhost|::1] [--port <value>]
+    [--open] [--sign] [--sign-provider a-trust] [--sign-certificate <value>]
 
 ARGUMENTS
   [FILE]    Markdown or yaml file to render.
   [OUTPUT]  Output file. Overwrites the one defined in front-matter.
 
 FLAGS
-  -F, --output-filetype=<option>  Output file type, defaults to pdf. Overwrites
-                                  the one defined in front-matter.
-                                  <options: pdf|html>
-  -I, --stdin                     Read the input from stdin.
-  -O, --stdout                    Write the output to stdout instead of a file.
-  -T, --title=<value>             Document title. Overwrites the one defined in
-                                  front-matter or the template.
-  -b, --browser=<value>           Browser executable used for printing.
-                                  Discovered automatically when omitted (Brave,
-                                  Chrome, Chromium, Edge).
-  -f, --input-filetype=<option>   Input file type. Detected from the file
-                                  extension, markdown for stdin and unknown
-                                  extensions.
-                                  <options: md|yaml|yml>
-  -l, --language=<value>          Language for template translations. Overwrites
-                                  the one defined in front-matter and template
-                                  settings.
-  -p, --preview                   Rebuild whenever the input, the template or
-                                  its assets change, show the HTML and the PDF
-                                  in a live preview and rewrite the output file
-                                  when there is one.
-  -t, --template=<value>          Built-in template name or path to a template
-                                  directory, defaults to "default". Overwrites
-                                  the one defined in front-matter.
-      --continuous                Render the PDF as a single continuous page
-                                  without page breaks.
-      --host=<option>             [default: 127.0.0.1] Loopback host for the
-                                  preview server, it serves the files next to
-                                  the input and is never exposed to the network.
-                                  <options: 127.0.0.1|localhost|::1>
-      --[no-]open                 Open the preview window, --no-open keeps
-                                  rebuilding and writing without one.
-      --port=<value>              Port for the preview server, random when 0.
-      --sign                      Sign the PDF with a qualified electronic
-                                  signature through ID Austria (A-Trust).
-      --sign-certificate=<value>  Signer certificate (DER or PEM) used for the
-                                  visible signature block and to verify the
-                                  returned signature.
-      --sign-provider=<option>    Signature provider, defaults to a-trust.
-                                  Overwrites the one defined in front-matter and
-                                  template settings.
-                                  <options: a-trust>
+  -F, --output-filetype=<option>    Output file type, defaults to pdf.
+                                    Overwrites the one defined in front-matter.
+                                    <options: pdf|html>
+  -I, --stdin                       Read the input from stdin.
+  -O, --stdout                      Write the output to stdout instead of a
+                                    file.
+  -T, --title=<value>               Document title. Overwrites the one defined
+                                    in front-matter or the template.
+  -b, --browser=<value>             Browser executable used for printing.
+                                    Discovered automatically when omitted
+                                    (Brave, Chrome, Chromium, Edge).
+  -f, --input-filetype=<option>     Input file type. Detected from the file
+                                    extension, markdown for stdin and unknown
+                                    extensions.
+                                    <options: md|yaml|yml>
+  -l, --language=<value>            Language for template translations.
+                                    Overwrites the one defined in front-matter
+                                    and template settings.
+  -p, --preview                     Rebuild whenever the input, the template or
+                                    its assets change, show the HTML and the PDF
+                                    in a live preview and rewrite the output
+                                    file when there is one.
+  -t, --template=<value>            Built-in template name or path to a template
+                                    directory, defaults to "default", read as
+                                    --template-type when given. Overwrites the
+                                    one defined in front-matter.
+      --continuous                  Render the PDF as a single continuous page
+                                    without page breaks.
+      --host=<option>               [default: 127.0.0.1] Loopback host for the
+                                    preview server, it serves the files next to
+                                    the input and is never exposed to the
+                                    network.
+                                    <options: 127.0.0.1|localhost|::1>
+      --[no-]open                   Open the preview window, --no-open keeps
+                                    rebuilding and writing without one.
+      --port=<value>                Port for the preview server, random when 0.
+      --sign                        Sign the PDF with a qualified electronic
+                                    signature through ID Austria (A-Trust).
+      --sign-certificate=<value>    Signer certificate (DER or PEM) used for the
+                                    visible signature block and to verify the
+                                    returned signature.
+      --sign-provider=<option>      Signature provider, defaults to a-trust.
+                                    Overwrites the one defined in front-matter
+                                    and template settings.
+                                    <options: a-trust>
+      --template-directory=<value>  Directory inside the package to use as the
+                                    template, only valid with --template-type
+                                    package.
+      --template-type=<value>       How to read --template, one of builtin,
+                                    package or directory, like the type of the
+                                    object form in front-matter.
 
 CLI FLAGS
   --log-level=<option>  [default: INFO, env: LOG_LEVEL] Set the log level of the

package/dist/_virtual/{_@oxc-project_runtime@0.156.0 → _@oxc-project_runtime@0.157.0}/helpers/esm/decorate.mjs

@@ -1,4 +1,4 @@
-// \0@oxc-project+runtime@0.156.0/helpers/esm/decorate.js
+// \0@oxc-project+runtime@0.157.0/helpers/esm/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
 	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);

package/dist/_virtual/{_@oxc-project_runtime@0.156.0 → _@oxc-project_runtime@0.157.0}/helpers/esm/decorateMetadata.mjs

@@ -1,4 +1,4 @@
-// \0@oxc-project+runtime@0.156.0/helpers/esm/decorateMetadata.js
+// \0@oxc-project+runtime@0.157.0/helpers/esm/decorateMetadata.js
 function __decorateMetadata(k, v) {
 	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }

package/dist/_virtual/{_@oxc-project_runtime@0.156.0 → _@oxc-project_runtime@0.157.0}/helpers/esm/decorateParam.mjs

@@ -1,4 +1,4 @@
-// \0@oxc-project+runtime@0.156.0/helpers/esm/decorateParam.js
+// \0@oxc-project+runtime@0.157.0/helpers/esm/decorateParam.js
 function __decorateParam(paramIndex, decorator) {
 	return function(target, key) {
 		decorator(target, key, paramIndex);

package/dist/commands/index.mjs

@@ -1,7 +1,7 @@
 import { MdPrinterHandler } from "../modules/md-printer/md-printer.handler.mjs";
 import { MdPrinterModule } from "../modules/md-printer/md-printer.module.mjs";
 import { MdPrinterSchema } from "../modules/md-printer/md-printer.schema.mjs";
-import __decorate from "../_virtual/_@oxc-project_runtime@0.156.0/helpers/esm/decorate.mjs";
+import __decorate from "../_virtual/_@oxc-project_runtime@0.157.0/helpers/esm/decorate.mjs";
 import { Args, Command, Flags, UseHandler } from "@cenk1cenk2/oclif-common";
 // src/commands/index.ts
 let MDPrinter = class MDPrinter extends Command {
@@ -12,6 +12,8 @@ let MDPrinter = class MDPrinter extends Command {
 		["output-filetype"]: Flags.string({ char: "F" }),
 		stdout: Flags.boolean({ char: "O" }),
 		template: Flags.string({ char: "t" }),
+		["template-type"]: Flags.string(),
+		["template-directory"]: Flags.string(),
 		title: Flags.string({ char: "T" }),
 		language: Flags.string({ char: "l" }),
 		browser: Flags.string({ char: "b" }),

package/dist/components/Localized.svelte

@@ -0,0 +1,18 @@
+<!--
+  @component
+  Text picked by the language of the document from props named after languages, such as `en` and `de`, for words that need no entry in `i18n/`. Takes the
+  language as it is, then its base language, then `fallback`. In a template a prop can also be a snippet. Plain text without a wrapper element, like Translate.
+-->
+<script>
+  import { getContext } from 'svelte'
+
+  /** @type {{ fallback?: string | import('svelte').Snippet } & Record<string, string | import('svelte').Snippet | undefined>} */
+  let { fallback, ...languages } = $props()
+
+  /** @type {import('../interfaces/template.interface.js').DocumentContext} */
+  const { language } = getContext('md-printer:document')
+
+  const value = $derived(languages[language] ?? languages[language.split('-')[0]] ?? fallback)
+</script>
+
+{#if typeof value === 'function'}{@render value()}{:else}{value ?? ''}{/if}

package/dist/components/SignatureBlock.svelte

@@ -1,56 +1,18 @@
 <!--
   @component
-  Visible block for a digitally signed document, filled from the `signature` prop md-printer passes to templates when signing is enabled.
-  Styled with Tailwind classes, so the template needs a `<style lang="postcss">` block importing Tailwind.
+  Passes the signature of a digitally signed document to the `children` snippet, which draws the block, so the template owns its markup and styles. The
+  signature comes from the `signature` prop or, as a directive, from the document context. Renders nothing without a signature or without `children`.
 -->
 <script>
+  import { getContext } from 'svelte'
+
   /**
    * @type {{
-   *   signature: { date: string, name?: string, issuer?: string, serial?: string },
-   *   labels?: { title?: string, by?: string, date?: string, issuer?: string, verify?: string },
-   *   class?: string
+   *   signature?: import('../interfaces/signature.interface.js').MdPrinterSignature,
+   *   children?: import('svelte').Snippet<[import('../interfaces/signature.interface.js').MdPrinterSignature]>
    * }}
    */
-  let { signature, labels = {}, class: className = '' } = $props()
-
-  const text = $derived({
-    title: 'Digitally signed',
-    by: 'Signed by',
-    date: 'Date',
-    issuer: 'Certificate',
-    verify: 'This document carries a qualified electronic signature. Verify it at',
-    ...labels
-  })
+  let { signature = getContext('md-printer:document').signature, children } = $props()
 </script>
 
-<div class="w-full overflow-hidden rounded-xl border-y-2 shadow-md shadow-gray-300 border-gray-900! text-xs {className}">
-  <div class="flex items-center gap-3 px-5 py-3 bg-gray-900 text-white">
-    <svg class="w-5 h-5 shrink-0" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
-      <path d="M12 3l7 3v6c0 4.5-3 7.5-7 9-4-1.5-7-4.5-7-9V6l7-3z" />
-      <path d="M9 12l2 2 4-4" />
-    </svg>
-    <span class="font-extrabold uppercase tracking-wider">{text.title}</span>
-  </div>
-  <div class="flex flex-col px-5 py-2">
-    {#if signature.name}
-      <div class="flex justify-between gap-4 py-2">
-        <span class="font-semibold text-gray-400">{text.by}</span>
-        <span class="font-semibold text-right">{signature.name}</span>
-      </div>
-    {/if}
-    <div class="flex justify-between gap-4 py-2 border-t border-t-gray-100/30">
-      <span class="font-semibold text-gray-400">{text.date}</span>
-      <span class="text-right">{signature.date}</span>
-    </div>
-    {#if signature.issuer}
-      <div class="flex justify-between gap-4 py-2 border-t border-t-gray-100/30">
-        <span class="font-semibold text-gray-400">{text.issuer}</span>
-        <span class="text-right text-[0.6rem]">{signature.issuer} · {signature.serial}</span>
-      </div>
-    {/if}
-  </div>
-  <p class="px-5 py-3 bg-gray-50 text-[0.6rem] text-gray-400 leading-snug">
-    {text.verify}
-    <a href="https://www.signaturpruefung.gv.at" class="font-semibold text-gray-900 underline">signaturpruefung.gv.at</a>
-  </p>
-</div>
+{#if signature && children}{@render children(signature)}{/if}

package/dist/components/Translate.svelte

@@ -0,0 +1,15 @@
+<!--
+  @component
+  Text translated with the `i18n/` directory of the template. Plain text without a wrapper element, so it flows inside paragraphs and table cells.
+-->
+<script>
+  import { getContext } from 'svelte'
+
+  /** @type {{ key: string, fallback?: string }} */
+  let { key, fallback } = $props()
+
+  /** @type {import('../interfaces/template.interface.js').DocumentContext} */
+  const { t } = getContext('md-printer:document')
+</script>
+
+{t(key, { defaultValue: fallback ?? key })}

package/dist/components/extension.ts

@@ -0,0 +1,8 @@
+import { getContext } from 'svelte'
+
+import type { TemplateExtension } from '../interfaces/template.interface.js'
+
+/** The named exports of the extension module of the template, empty without one. */
+export function getExtension<T extends TemplateExtension = TemplateExtension>(): T {
+  return getContext('md-printer:extension')
+}

package/dist/components/index.ts

@@ -1,4 +1,6 @@
+export { getExtension } from './extension.js'
 export { default as Date } from './Date.svelte'
+export { default as Localized } from './Localized.svelte'
 export { default as Markdown } from './Markdown.svelte'
 export { default as Page } from './Page.svelte'
 export { default as PageBreak } from './PageBreak.svelte'
@@ -6,3 +8,4 @@ export { default as PageNumber } from './PageNumber.svelte'
 export { default as SignatureBlock } from './SignatureBlock.svelte'
 export { default as Title } from './Title.svelte'
 export { default as TotalPages } from './TotalPages.svelte'
+export { default as Translate } from './Translate.svelte'

package/dist/constants/attachment.constants.mjs

@@ -0,0 +1,7 @@
+// src/constants/attachment.constants.ts
+let AttachmentPosition = /* @__PURE__ */ function(AttachmentPosition) {
+	AttachmentPosition["BEFORE"] = "before";
+	AttachmentPosition["AFTER"] = "after";
+	return AttachmentPosition;
+}({});
+export { AttachmentPosition };

package/dist/constants/index.mjs

@@ -1,5 +1,6 @@
-import { ContextKey, DEFAULT_HIGHLIGHT_STYLE, DEFAULT_LANGUAGE, DEFAULT_PDF_OPTIONS, DEFAULT_TEMPLATE, DIRECTIVE_TAG, Directory, I18N_ACCEPTED_TYPES, MediaType, ModuleSpecifier, PAGE_BREAK_CLASS, PRINTER_MODULE_OPTIONS, RenderMode, TAILWIND_STYLE_LANG, TemplateFiles } from "./template.constants.mjs";
+import { AttachmentPosition } from "./attachment.constants.mjs";
+import { ContextKey, DEFAULT_HIGHLIGHT_STYLE, DEFAULT_LANGUAGE, DEFAULT_PDF_OPTIONS, DEFAULT_TEMPLATE, DIRECTIVE_TAG, Directory, I18N_ACCEPTED_TYPES, MediaType, ModuleSpecifier, PAGE_BREAK_CLASS, PRINTER_MODULE_OPTIONS, RenderMode, TAILWIND_STYLE_LANG, TEMPLATE_EXTENSION_FILES, TEMPLATE_LAYOUT, TEMPLATE_PACKAGE_PREFIX, TemplateFiles, TemplateSourceType } from "./template.constants.mjs";
 import { InputFileType, OutputFileType } from "./file.constants.mjs";
 import { PreviewHost } from "./preview.constants.mjs";
 import { SignatureProvider } from "./signature.constants.mjs";
-export { ContextKey, DEFAULT_HIGHLIGHT_STYLE, DEFAULT_LANGUAGE, DEFAULT_PDF_OPTIONS, DEFAULT_TEMPLATE, DIRECTIVE_TAG, Directory, I18N_ACCEPTED_TYPES, InputFileType, MediaType, ModuleSpecifier, OutputFileType, PAGE_BREAK_CLASS, PRINTER_MODULE_OPTIONS, PreviewHost, RenderMode, SignatureProvider, TAILWIND_STYLE_LANG, TemplateFiles };
+export { AttachmentPosition, ContextKey, DEFAULT_HIGHLIGHT_STYLE, DEFAULT_LANGUAGE, DEFAULT_PDF_OPTIONS, DEFAULT_TEMPLATE, DIRECTIVE_TAG, Directory, I18N_ACCEPTED_TYPES, InputFileType, MediaType, ModuleSpecifier, OutputFileType, PAGE_BREAK_CLASS, PRINTER_MODULE_OPTIONS, PreviewHost, RenderMode, SignatureProvider, TAILWIND_STYLE_LANG, TEMPLATE_EXTENSION_FILES, TEMPLATE_LAYOUT, TEMPLATE_PACKAGE_PREFIX, TemplateFiles, TemplateSourceType };

package/dist/constants/template.constants.mjs

@@ -4,6 +4,21 @@ let TemplateFiles = /* @__PURE__ */ function(TemplateFiles) {
 	TemplateFiles["SETTINGS"] = "settings.json";
 	return TemplateFiles;
 }({});
+/** Where a template keeps its files unless `files` in its settings says otherwise, the root locations of 3.x come last. */
+const TEMPLATE_LAYOUT = {
+	template: ["template/Template.svelte", "Template.svelte"],
+	components: ["template/components", "components"],
+	extension: ["src", "."],
+	i18n: ["i18n"]
+};
+const TEMPLATE_EXTENSION_FILES = [
+	"extension.ts",
+	"extension.mts",
+	"extension.cts",
+	"extension.js",
+	"extension.mjs",
+	"extension.cjs"
+];
 let RenderMode = /* @__PURE__ */ function(RenderMode) {
 	RenderMode["BODY"] = "body";
 	RenderMode["HEADER"] = "header";
@@ -15,8 +30,15 @@ let MediaType = /* @__PURE__ */ function(MediaType) {
 	MediaType["PRINT"] = "print";
 	return MediaType;
 }({});
+/** Built-in templates are packages named with this prefix, which md-printer depends on. */
+const TEMPLATE_PACKAGE_PREFIX = "@cenk1cenk2/md-printer-template-";
+let TemplateSourceType = /* @__PURE__ */ function(TemplateSourceType) {
+	TemplateSourceType["BUILTIN"] = "builtin";
+	TemplateSourceType["PACKAGE"] = "package";
+	TemplateSourceType["DIRECTORY"] = "directory";
+	return TemplateSourceType;
+}({});
 let Directory = /* @__PURE__ */ function(Directory) {
-	Directory["TEMPLATES"] = "templates";
 	Directory["COMPONENTS"] = "components";
 	Directory["I18N"] = "i18n";
 	return Directory;
@@ -25,6 +47,7 @@ let ModuleSpecifier = /* @__PURE__ */ function(ModuleSpecifier) {
 	ModuleSpecifier["TEMPLATE"] = "md-printer:template";
 	ModuleSpecifier["COMPONENTS"] = "@cenk1cenk2/md-printer/components";
 	ModuleSpecifier["TEMPLATE_COMPONENTS"] = "md-printer:template-components";
+	ModuleSpecifier["EXTENSION"] = "md-printer:extension";
 	return ModuleSpecifier;
 }({});
 let ContextKey = /* @__PURE__ */ function(ContextKey) {
@@ -32,6 +55,7 @@ let ContextKey = /* @__PURE__ */ function(ContextKey) {
 	ContextKey["DOCUMENT"] = "md-printer:document";
 	ContextKey["MARKDOWN"] = "md-printer:markdown";
 	ContextKey["COMPONENTS"] = "md-printer:components";
+	ContextKey["EXTENSION"] = "md-printer:extension";
 	return ContextKey;
 }({});
 const TAILWIND_STYLE_LANG = "postcss";
@@ -56,4 +80,4 @@ const DEFAULT_PDF_OPTIONS = {
 		left: "20mm"
 	}
 };
-export { ContextKey, DEFAULT_HIGHLIGHT_STYLE, DEFAULT_LANGUAGE, DEFAULT_PDF_OPTIONS, DEFAULT_TEMPLATE, DIRECTIVE_TAG, Directory, I18N_ACCEPTED_TYPES, MediaType, ModuleSpecifier, PAGE_BREAK_CLASS, PRINTER_MODULE_OPTIONS, RenderMode, TAILWIND_STYLE_LANG, TemplateFiles };
+export { ContextKey, DEFAULT_HIGHLIGHT_STYLE, DEFAULT_LANGUAGE, DEFAULT_PDF_OPTIONS, DEFAULT_TEMPLATE, DIRECTIVE_TAG, Directory, I18N_ACCEPTED_TYPES, MediaType, ModuleSpecifier, PAGE_BREAK_CLASS, PRINTER_MODULE_OPTIONS, RenderMode, TAILWIND_STYLE_LANG, TEMPLATE_EXTENSION_FILES, TEMPLATE_LAYOUT, TEMPLATE_PACKAGE_PREFIX, TemplateFiles, TemplateSourceType };

package/dist/interfaces/attachment.interface.mjs

@@ -0,0 +1 @@
+export {};