@cenk1cenk2/md-printer 3.3.0 → 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.                                                           |
@@ -177,7 +177,7 @@ 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>`, published from the `templates/` directory of this repository. 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.
+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                                                                                                    |
 | ----------- | -------------------------------------------------------------------------------------------------------------- |
@@ -187,18 +187,83 @@ Every built-in template is a package of its own, `@cenk1cenk2/md-printer-templat
 | `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                                                                                  |
@@ -208,6 +273,7 @@ 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>`.
 
@@ -227,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`:
@@ -240,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>
@@ -266,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'
 
@@ -309,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
@@ -334,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/commands/index.mjs

@@ -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/index.mjs

@@ -1,6 +1,6 @@
 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_PACKAGE_PREFIX, TemplateFiles } from "./template.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 { 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_PACKAGE_PREFIX, 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";
@@ -17,6 +32,12 @@ let MediaType = /* @__PURE__ */ function(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["COMPONENTS"] = "components";
 	Directory["I18N"] = "i18n";
@@ -26,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) {
@@ -33,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";
@@ -57,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, TEMPLATE_PACKAGE_PREFIX, 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/modules/md-printer/md-printer.handler.mjs

@@ -34,6 +34,8 @@ let MdPrinterHandler = class MdPrinterHandler {
 			outputFiletype: flags["output-filetype"],
 			stdout: flags.stdout,
 			template: flags.template,
+			templateType: flags["template-type"],
+			templateDirectory: flags["template-directory"],
 			title: flags.title,
 			language: flags.language,
 			continuous: flags.continuous,

package/dist/modules/md-printer/md-printer.schema.mjs

@@ -1,6 +1,7 @@
 import { InputFileType, OutputFileType } from "../../constants/file.constants.mjs";
 import { PreviewHost } from "../../constants/preview.constants.mjs";
 import { SignatureProvider } from "../../constants/signature.constants.mjs";
+import "../../constants/template.constants.mjs";
 import { z } from "zod";
 // src/modules/md-printer/md-printer.schema.ts
 const MdPrinterSchema = z.object({
@@ -9,7 +10,9 @@ const MdPrinterSchema = z.object({
 		["input-filetype"]: z.enum(InputFileType).optional().describe("Input file type. Detected from the file extension, markdown for stdin and unknown extensions."),
 		["output-filetype"]: z.enum(OutputFileType).optional().describe("Output file type, defaults to pdf. Overwrites the one defined in front-matter."),
 		stdout: z.boolean().default(false).describe("Write the output to stdout instead of a file."),
-		template: z.string().optional().describe("Built-in template name or path to a template directory, defaults to \"default\". Overwrites the one defined in front-matter."),
+		template: z.string().optional().describe("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."),
+		["template-type"]: z.string().optional().describe("How to read --template, one of builtin, package or directory, like the type of the object form in front-matter."),
+		["template-directory"]: z.string().optional().describe("Directory inside the package to use as the template, only valid with --template-type package."),
 		title: z.string().optional().describe("Document title. Overwrites the one defined in front-matter or the template."),
 		language: z.string().optional().describe("Language for template translations. Overwrites the one defined in front-matter and template settings."),
 		browser: z.string().optional().describe("Browser executable used for printing. Discovered automatically when omitted (Brave, Chrome, Chromium, Edge)."),
@@ -35,6 +38,14 @@ const MdPrinterSchema = z.object({
 		code: "custom",
 		message: "Reading from --stdin takes only the output file argument."
 	});
+	if (flags["template-type"] && !flags.template) ctx.addIssue({
+		code: "custom",
+		message: "--template-type needs --template to read."
+	});
+	if (flags["template-directory"] !== void 0 && flags["template-type"] !== "package") ctx.addIssue({
+		code: "custom",
+		message: "--template-directory is only valid with --template-type package."
+	});
 	if (flags.stdout && flags.preview) ctx.addIssue({
 		code: "custom",
 		message: "Writing to stdout is not supported with --preview."

package/dist/services/i18n.service.mjs

@@ -14,14 +14,16 @@ let I18nService = class I18nService {
 		this.fs = fs;
 		this.parser = parser;
 	}
-	async load(directory, options) {
+	/** Loads the folders in order, a key of a later folder replacing the same key of an earlier one while nested keys merge. */
+	async load(directories, options) {
 		const instance = i18next.createInstance();
 		await instance.init({
 			lng: options.language,
 			fallbackLng: options.fallback ?? options.language ?? "en",
-			resources: this.fs.exists(directory) ? await this.resources(directory) : {},
+			resources: {},
 			interpolation: { escapeValue: false }
 		});
+		for (const directory of directories.filter((directory) => this.fs.exists(directory))) for (const [language, { translation }] of Object.entries(await this.resources(directory))) instance.addResourceBundle(language, "translation", translation, true, true);
 		return instance.getFixedT(options.language);
 	}
 	async resources(directory) {

package/dist/services/printer.service.mjs

@@ -5,6 +5,7 @@ import { RendererService } from "./renderer/renderer.service.mjs";
 import { SignatureVerificationError } from "./signature/cms.mjs";
 import { SignatureService } from "./signature/signature.service.mjs";
 import { inlineHtml } from "./template/assets.mjs";
+import { TemplateSourceSchema, issues } from "./template/template.schema.mjs";
 import { TemplateService } from "./template/template.service.mjs";
 import { AttachmentPosition } from "../constants/attachment.constants.mjs";
 import { DEFAULT_PDF_OPTIONS } from "../constants/template.constants.mjs";
@@ -12,7 +13,7 @@ import { OutputFileType } from "../constants/file.constants.mjs";
 import __decorateMetadata from "../_virtual/_@oxc-project_runtime@0.157.0/helpers/esm/decorateMetadata.mjs";
 import __decorate from "../_virtual/_@oxc-project_runtime@0.157.0/helpers/esm/decorate.mjs";
 import { Injectable } from "@nestjs/common";
-import { basename, dirname, extname, join, resolve } from "path";
+import { basename, dirname, extname, resolve } from "path";
 import { ConfigService, FileSystemService, LoggerService } from "@cenk1cenk2/oclif-common";
 import { cloneDeep, mergeWith, uniq } from "es-toolkit";
 import { parse } from "yaml";
@@ -65,13 +66,14 @@ let PrinterService = class PrinterService {
 	}
 	async options(flags, input) {
 		const { data } = input;
-		const template = this.template.resolve(flags.template ?? data.template ?? "default");
-		const settings = await this.template.settings(template);
+		const source = this.templateSource(this.templateFlags(flags) ?? data.template) ?? "default";
+		const { directory: template, settings, files } = await this.template.resolve(source, input.directory);
 		const output = flags.outputFiletype ?? data.outputFiletype ?? "pdf";
 		if (!Object.values(OutputFileType).includes(output)) throw new Error(`Output file type is not supported: ${output}, use one of ${Object.values(OutputFileType).join(", ")}.`);
 		const dest = flags.stdout ? void 0 : flags.output ?? data.dest ?? (input.file ? `${basename(input.file, extname(input.file))}.${output}` : void 0);
 		return {
 			template,
+			files,
 			output,
 			dest: dest && resolve(dest),
 			title: flags.title ?? data.documentTitle,
@@ -87,7 +89,7 @@ let PrinterService = class PrinterService {
 		};
 	}
 	bundle(options) {
-		return this.template.bundle(options.template);
+		return this.template.bundle(options.files);
 	}
 	/**
 	* Resolves the signing time and the visible signature description, which the template renders before the document is signed.
@@ -104,7 +106,7 @@ let PrinterService = class PrinterService {
 		const { input, options } = ctx;
 		const document = await this.template.render(options.template, bundle, {
 			data: input.data,
-			t: await this.i18n.load(join(options.template, "i18n"), {
+			t: await this.i18n.load(options.files.i18n, {
 				...options.i18n,
 				language: options.language
 			}),
@@ -158,6 +160,21 @@ let PrinterService = class PrinterService {
 			throw err;
 		});
 	}
+	templateFlags({ template, templateType, templateDirectory }) {
+		if (!templateType) return template;
+		return {
+			type: templateType,
+			[templateType === "directory" ? "path" : "name"]: template,
+			...templateDirectory !== void 0 && { directory: templateDirectory }
+		};
+	}
+	templateSource(value) {
+		if (value === void 0 || value === null) return;
+		if (typeof value === "string") return value;
+		const { success, data, error } = TemplateSourceSchema.safeParse(value);
+		if (!success) throw new Error(`Template is invalid: ${issues(error)}`);
+		return data;
+	}
 	attachments(value) {
 		if (value === void 0 || value === null) return [];
 		if (!Array.isArray(value)) throw new Error("Front-matter attachments must be a list of { file, position, compress }.");

package/dist/services/session/session.service.mjs

@@ -5,6 +5,7 @@ import __decorate from "../../_virtual/_@oxc-project_runtime@0.157.0/helpers/esm
 import { Injectable } from "@nestjs/common";
 import { dirname, join, resolve } from "path";
 import { LoggerService } from "@cenk1cenk2/oclif-common";
+import { isEqual } from "es-toolkit";
 import { EventEmitter } from "events";
 import { watch } from "chokidar";
 import { debounce } from "perfect-debounce";
@@ -53,7 +54,7 @@ let SessionService = class SessionService extends EventEmitter {
 		const file = resolve(path);
 		if (this.ignored.has(file)) return;
 		this.logger.debug("Changed: %s", file);
-		if (this.modules.has(file) || this.bundle && dirname(file) === join(this.bundle.template, "components")) this.bundle = void 0;
+		if (this.modules.has(file) || this.bundle?.files.components.includes(dirname(file))) this.bundle = void 0;
 		this.build();
 	}
 	async run() {
@@ -62,18 +63,17 @@ let SessionService = class SessionService extends EventEmitter {
 		try {
 			const input = await this.printer.input(this.flags);
 			const options = await this.printer.options(this.flags, input);
-			const template = join(options.template, "Template.svelte");
-			this.modules.add(template);
+			const { files } = options;
+			this.modules = /* @__PURE__ */ new Set([...this.modules, files.template]);
 			this.watch([
 				input.file,
-				template,
+				files.template,
+				...files.candidates,
 				join(options.template, "settings.json"),
-				join(options.template, "i18n"),
-				join(options.template, "components"),
 				options.sign.certificate && resolve(options.sign.certificate)
 			]);
-			if (this.bundle?.template !== options.template) this.bundle = {
-				template: options.template,
+			if (!isEqual(this.bundle?.files, files)) this.bundle = {
+				files,
 				bundle: this.printer.bundle(options)
 			};
 			const cached = this.bundle;
@@ -82,7 +82,7 @@ let SessionService = class SessionService extends EventEmitter {
 				throw err;
 			});
 			if (this.bundle !== cached) return;
-			this.modules = /* @__PURE__ */ new Set([template, ...bundle.modules]);
+			this.modules = /* @__PURE__ */ new Set([files.template, ...bundle.modules]);
 			this.watch(bundle.modules);
 			const ctx = {
 				input,

package/dist/services/template/render.entry.ts

@@ -1,3 +1,4 @@
+import modules from 'md-printer:extension'
 import Template from 'md-printer:template'
 import components from 'md-printer:template-components'
 import { render } from 'svelte/server'
@@ -7,7 +8,10 @@ import Document from './Document.svelte'
 import Margin from './Margin.svelte'
 import type { DocumentShellProps, MarginShellProps, MarkdownNode, RenderedPart, TemplateProps } from '@interfaces'
 
-export { components }
+// a CommonJS module also comes with module.exports as the default
+const extension = Object.fromEntries(modules.flatMap((module) => Object.entries(module).filter(([name]) => name !== 'default')))
+
+export { components, extension }
 
 /**
  * Entry of every template bundle, compiled at runtime together with the template it renders.

package/dist/services/template/svelte.plugin.mjs

@@ -1,7 +1,7 @@
 import { dataUri, isInlinableAsset } from "./assets.mjs";
 import "../../constants/template.constants.mjs";
 import { readFile, readdir } from "fs/promises";
-import { basename, dirname, extname, join } from "path";
+import { basename, extname, join } from "path";
 import { pathToFileURL } from "url";
 import { existsSync } from "fs";
 import { createRequire } from "module";
@@ -10,9 +10,10 @@ import { compile, preprocess } from "svelte/compiler";
 /**
 * `svelte` resolves to md-printer's copy, since templates can live outside any `node_modules`. `<style lang="postcss">` blocks are collected
 * instead of compiled per component, so the template's stylesheet goes through Tailwind once. `md-printer:template-components` maps the shared
-* components and the template's `components/*.svelte` by name, the template's winning.
+* components and the `*.svelte` files of the template's components directory by name, the template's winning. `md-printer:extension` is the extension module of the
+* template, or an empty module without one.
 */
-function sveltePlugin({ template, components, root, stylesheets }) {
+function sveltePlugin({ template, components, templateComponents, root, stylesheets, extension }) {
 	const require = createRequire(root);
 	return {
 		name: "md-printer:svelte",
@@ -20,6 +21,7 @@ function sveltePlugin({ template, components, root, stylesheets }) {
 			if (id === "md-printer:template") return template;
 			if (id === "@cenk1cenk2/md-printer/components") return components;
 			if (id === "md-printer:template-components") return `\0${id}`;
+			if (id === "md-printer:extension") return `\0${id}`;
 			if (id === "svelte" || id.startsWith("svelte/")) return {
 				id: pathToFileURL(require.resolve(id)).href,
 				external: true
@@ -28,15 +30,18 @@ function sveltePlugin({ template, components, root, stylesheets }) {
 		},
 		async load(id) {
 			if (id === `\0md-printer:template-components`) {
-				const directory = join(dirname(template), "components");
-				const files = existsSync(directory) ? (await readdir(directory)).filter((file) => extname(file) === ".svelte").sort() : [];
+				const files = (await Promise.all((templateComponents ?? []).map(async (folder) => existsSync(folder) ? (await readdir(folder)).filter((file) => extname(file) === ".svelte").sort().map((file) => join(folder, file)) : []))).flat();
 				return [
 					`import * as shared from ${JSON.stringify("@cenk1cenk2/md-printer/components")}`,
-					...files.map((file, index) => `import $${index} from ${JSON.stringify(join(directory, file))}`),
-					"const { Markdown, ...builtins } = shared",
+					...files.map((file, index) => `import $${index} from ${JSON.stringify(file)}`),
+					"const { Markdown, getExtension, ...builtins } = shared",
 					`export default { ...builtins, ${files.map((file, index) => `${JSON.stringify(basename(file, ".svelte"))}: $${index}`).join(", ")} }`
 				].join("\n");
 			}
+			if (id === `\0md-printer:extension`) {
+				const modules = extension ?? [];
+				return [...modules.map((file, index) => `import * as $${index} from ${JSON.stringify(file)}`), `export default [${modules.map((_, index) => `$${index}`).join(", ")}]`].join("\n");
+			}
 			if (!isInlinableAsset(id)) return null;
 			return `export default ${JSON.stringify(dataUri(id, await readFile(id)))}`;
 		},

package/dist/services/template/template.schema.mjs

@@ -0,0 +1,27 @@
+import { TemplateSourceType } from "../../constants/template.constants.mjs";
+import { z } from "zod";
+const TemplateSourceSchema = z.discriminatedUnion("type", [
+	z.strictObject({
+		type: z.literal("builtin"),
+		name: z.string().regex(/^[^\\/]+$/, "Built-in template names have no path separator.")
+	}),
+	z.strictObject({
+		type: z.literal("package"),
+		name: z.string().regex(/^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/, "Not an npm package name."),
+		directory: z.string().optional()
+	}),
+	z.strictObject({
+		type: z.literal("directory"),
+		path: z.string().min(1)
+	})
+], { error: () => `Use a string or an object with a type of ${Object.values(TemplateSourceType).join(", ")}.` });
+const TemplateSettingsSchema = z.looseObject({ files: z.strictObject({
+	template: z.string().min(1).optional(),
+	components: z.union([z.string().min(1), z.array(z.string().min(1)).min(1)]).optional(),
+	extension: z.union([z.string().min(1), z.array(z.string().min(1)).min(1)]).optional(),
+	i18n: z.union([z.string().min(1), z.array(z.string().min(1)).min(1)]).optional()
+}).optional() });
+function issues({ issues }) {
+	return issues.map(({ path, message }) => [...path, message].join(": ")).join(", ");
+}
+export { TemplateSettingsSchema, TemplateSourceSchema, issues };

package/dist/services/template/template.service.mjs

@@ -1,12 +1,13 @@
-import { inlineCss, inlineHtml } from "./assets.mjs";
+import { inlineCss, inlineHtml, resolveConfined } from "./assets.mjs";
 import { sveltePlugin } from "./svelte.plugin.mjs";
-import { TEMPLATE_PACKAGE_PREFIX } from "../../constants/template.constants.mjs";
+import { TemplateSettingsSchema, issues } from "./template.schema.mjs";
+import { TEMPLATE_EXTENSION_FILES, TEMPLATE_LAYOUT, TEMPLATE_PACKAGE_PREFIX } from "../../constants/template.constants.mjs";
 import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.157.0/helpers/esm/decorateMetadata.mjs";
 import __decorate from "../../_virtual/_@oxc-project_runtime@0.157.0/helpers/esm/decorate.mjs";
 import { Injectable } from "@nestjs/common";
-import { dirname, isAbsolute, join, resolve } from "path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "path";
 import { FileSystemService } from "@cenk1cenk2/oclif-common";
-import { fileURLToPath } from "url";
+import { fileURLToPath, pathToFileURL } from "url";
 import { homedir } from "os";
 import { compile } from "@tailwindcss/node";
 import { Scanner } from "@tailwindcss/oxide";
@@ -45,21 +46,20 @@ let TemplateService = class TemplateService {
 	constructor(fs) {
 		this.fs = fs;
 	}
-	resolve(template) {
-		const path = template.replace(/^~(?=\/|$)/, homedir());
-		const directory = isAbsolute(path) || path.startsWith(".") || /[\\/]/.test(path) ? resolve(path) : this.builtin(path);
-		if (!this.fs.exists(join(directory, "Template.svelte"))) throw new Error(`Template does not exist, expected Template.svelte in: ${directory}`);
-		return directory;
-	}
-	async settings(directory) {
-		const file = join(directory, "settings.json");
-		if (!this.fs.exists(file)) return {};
-		return JSON.parse(await this.fs.read(file));
+	async resolve(template, base) {
+		const directory = await this.locate(template, base);
+		const settings = await this.settings(directory);
+		return {
+			directory,
+			settings,
+			files: await this.paths(directory, settings.files)
+		};
 	}
-	async bundle(directory) {
+	async bundle(files) {
 		const stylesheets = [];
-		const { module: entry, modules } = await this.compile(_TemplateService.ENTRY, join(directory, "Template.svelte"), stylesheets);
+		const { module: entry, modules } = await this.compile(_TemplateService.ENTRY, stylesheets, files);
 		return {
+			template: files.template,
 			entry,
 			modules,
 			stylesheets,
@@ -67,17 +67,22 @@ let TemplateService = class TemplateService {
 		};
 	}
 	async page(file) {
-		const { module } = await this.compile(file, file, []);
+		const { module } = await this.compile(file, [], {
+			directory: dirname(file),
+			template: file
+		});
 		return `<!doctype html>${render(module.default).body}`;
 	}
 	async render(directory, bundle, document, markdown, options) {
 		const context = [
 			["md-printer:document", document],
 			["md-printer:markdown", markdown],
-			["md-printer:components", bundle.entry.components]
+			["md-printer:components", bundle.entry.components],
+			["md-printer:extension", bundle.entry.extension]
 		];
 		const props = {
 			...document,
+			extension: bundle.entry.extension,
 			content: bundle.entry.content(markdown, context)
 		};
 		const [body, header, footer] = await Promise.all([
@@ -108,16 +113,90 @@ let TemplateService = class TemplateService {
 			dependencies
 		};
 	}
+	locate(template, base) {
+		if (typeof template === "string") {
+			const path = this.expand(template);
+			return isAbsolute(path) || path.startsWith(".") || /[\\/]/.test(path) ? resolve(path) : this.builtin(path);
+		}
+		switch (template.type) {
+			case "builtin": return this.builtin(template.name);
+			case "package": return this.package(template, base);
+			case "directory": return resolve(base, this.expand(template.path));
+		}
+	}
+	expand(path) {
+		return path.replace(/^~(?=\/|$)/, homedir());
+	}
 	/** A built-in template is a package of its own, so it brings its own fonts, icons and stylesheets as dependencies. */
 	builtin(name) {
 		const pkg = `${TEMPLATE_PACKAGE_PREFIX}${name}`;
 		try {
 			return dirname(this.require.resolve(`${pkg}/package.json`));
 		} catch {
-			throw new Error(`Template does not exist, expected the built-in template package ${pkg} or a path to a directory with Template.svelte.`);
+			throw new Error(`Template does not exist, expected the built-in template package ${pkg} or a path to a template directory.`);
+		}
+	}
+	async package({ name, directory }, base) {
+		const root = this.installed(name, [.../* @__PURE__ */ new Set([base, process.cwd()]), _TemplateService.ROOT]);
+		if (directory === void 0) return root;
+		const confined = await resolveConfined(resolve(root, directory), root);
+		if (!confined) throw new Error(`Template directory "${directory}" of the package ${name} has to exist inside the package: ${root}`);
+		return confined;
+	}
+	installed(name, roots) {
+		for (const root of roots) try {
+			return dirname(createRequire(join(root, "package.json")).resolve(`${name}/package.json`));
+		} catch {
+			continue;
+		}
+		throw new Error(`Template does not exist, the package ${name} is not installed in any of: ${roots.join(", ")}`);
+	}
+	async settings(directory) {
+		const file = join(directory, "settings.json");
+		if (!this.fs.exists(file)) return {};
+		const { success, data, error } = TemplateSettingsSchema.safeParse(JSON.parse(await this.fs.read(file)));
+		if (!success) throw new Error(`Template settings are invalid in ${file}: ${issues(error)}`);
+		return data;
+	}
+	async paths(directory, files = {}) {
+		const template = files.template ? await this.configured(directory, "template", files.template) : this.first(directory, TEMPLATE_LAYOUT.template);
+		const components = files.components ? await Promise.all([files.components].flat().map((path) => this.configured(directory, "components", path))) : [this.first(directory, TEMPLATE_LAYOUT.components) ?? join(directory, TEMPLATE_LAYOUT.components[0])];
+		const i18n = files.i18n ? await Promise.all([files.i18n].flat().map((path) => this.configured(directory, "i18n", path))) : [this.first(directory, TEMPLATE_LAYOUT.i18n) ?? join(directory, TEMPLATE_LAYOUT.i18n[0])];
+		const extension = files.extension ? await Promise.all([files.extension].flat().map((path) => this.configured(directory, "extension", path))) : [this.extension(directory)].filter((path) => path !== void 0);
+		if (!template) throw new Error(`Template does not exist, expected ${TEMPLATE_LAYOUT.template.join(" or ")} in: ${directory}`);
+		return {
+			directory,
+			template,
+			components,
+			i18n,
+			extension,
+			candidates: [
+				...files.template ? [template] : TEMPLATE_LAYOUT.template.map((path) => join(directory, path)),
+				...files.components ? components : TEMPLATE_LAYOUT.components.map((path) => join(directory, path)),
+				...files.i18n ? i18n : TEMPLATE_LAYOUT.i18n.map((path) => join(directory, path)),
+				...files.extension ? extension : TEMPLATE_LAYOUT.extension.flatMap((path) => TEMPLATE_EXTENSION_FILES.map((file) => join(directory, path, file)))
+			]
+		};
+	}
+	async configured(directory, key, value) {
+		const path = resolve(directory, value);
+		const rel = relative(directory, path);
+		const outside = rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+		if (!outside && !this.fs.exists(path)) throw new Error(`Template settings point files.${key} to a path that does not exist: ${path}`);
+		if (outside || !await resolveConfined(path, directory)) throw new Error(`Template settings point files.${key} outside of the template directory: ${value}`);
+		return path;
+	}
+	first(directory, paths) {
+		return paths.map((path) => join(directory, path)).find((path) => this.fs.exists(path));
+	}
+	extension(directory) {
+		for (const location of TEMPLATE_LAYOUT.extension) {
+			const files = TEMPLATE_EXTENSION_FILES.filter((file) => this.fs.exists(join(directory, location, file)));
+			if (files.length > 1) throw new Error(`Template has more than one extension module, keep one of ${files.join(", ")} in: ${join(directory, location)}`);
+			if (files.length === 1) return join(directory, location, files[0]);
 		}
 	}
-	async compile(input, template, stylesheets) {
+	async compile(input, stylesheets, files) {
 		const build = await rolldown({
 			input,
 			platform: "node",
@@ -125,14 +204,16 @@ let TemplateService = class TemplateService {
 			onLog(_, log, handler) {
 				if (log.code === "UNRESOLVED_IMPORT") handler("error", {
 					...log,
-					message: `${log.message} Install it in the template directory: ${dirname(template)}`
+					message: `${log.message} Install it in the template directory: ${files.directory}`
 				});
 			},
 			plugins: [sveltePlugin({
-				template,
+				template: files.template,
 				components: _TemplateService.COMPONENTS,
+				templateComponents: files.components,
 				root: _TemplateService.ROOT,
-				stylesheets
+				stylesheets,
+				extension: files.extension
 			})]
 		});
 		try {
@@ -140,8 +221,9 @@ let TemplateService = class TemplateService {
 				format: "esm",
 				sourcemap: "inline"
 			});
+			const code = chunk.code.replaceAll("createRequire(import.meta.url)", `createRequire(${JSON.stringify(pathToFileURL(files.template).href)})`);
 			return {
-				module: await import(`data:text/javascript;base64,${Buffer.from(chunk.code).toString("base64")}`),
+				module: await import(`data:text/javascript;base64,${Buffer.from(code).toString("base64")}`),
 				modules: chunk.moduleIds.filter((id) => isAbsolute(id))
 			};
 		} finally {
@@ -164,7 +246,7 @@ let TemplateService = class TemplateService {
 		const theme = `:root { ${readFileSync(this.highlightTheme(highlight), "utf8")} pre:has(> code.hljs) { padding: 0; background: transparent; } }`;
 		const compiler = await compile([theme, ...bundle.stylesheets.map(({ source }) => source)].join("\n"), {
 			base: directory,
-			from: bundle.stylesheets[0]?.file ?? join(directory, "Template.svelte"),
+			from: bundle.stylesheets[0]?.file ?? bundle.template,
 			shouldRewriteUrls: true,
 			onDependency: (path) => dependencies.push(path),
 			customCssResolver: async (id, base) => this.resolveFrom(this.stylesheets, id, [

package/oclif.manifest.json

@@ -94,12 +94,26 @@
         },
         "template": {
           "char": "t",
-          "description": "Built-in template name or path to a template directory, defaults to \"default\". Overwrites the one defined in front-matter.",
+          "description": "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.",
           "name": "template",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
+        "template-type": {
+          "description": "How to read --template, one of builtin, package or directory, like the type of the object form in front-matter.",
+          "name": "template-type",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "template-directory": {
+          "description": "Directory inside the package to use as the template, only valid with --template-type package.",
+          "name": "template-directory",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "title": {
           "char": "T",
           "description": "Document title. Overwrites the one defined in front-matter or the template.",
@@ -198,5 +212,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "3.3.0"
+  "version": "3.4.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cenk1cenk2/md-printer",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "Render markdown or yaml through Svelte templates into PDF or HTML with Puppeteer.",
   "type": "module",
   "repository": {
@@ -49,11 +49,11 @@
     "cenk1cenk2"
   ],
   "dependencies": {
-    "@cenk1cenk2/md-printer-template-cv": "1.0.0",
-    "@cenk1cenk2/md-printer-template-default": "1.0.0",
-    "@cenk1cenk2/md-printer-template-invoice": "1.0.0",
-    "@cenk1cenk2/md-printer-template-kilic.dev": "1.0.0",
-    "@cenk1cenk2/md-printer-template-mail": "1.0.0",
+    "@cenk1cenk2/md-printer-template-cv": "^1.0.0",
+    "@cenk1cenk2/md-printer-template-default": "1.1.0",
+    "@cenk1cenk2/md-printer-template-invoice": "^1.0.0",
+    "@cenk1cenk2/md-printer-template-kilic.dev": "1.1.0",
+    "@cenk1cenk2/md-printer-template-mail": "1.1.0",
     "@cenk1cenk2/oclif-common": "^8.0.2",
     "@listr2/manager": "^4.3.3",
     "@nestjs/common": "^12.3.2",
@@ -123,7 +123,7 @@
     "tsdown": "^0.23.4",
     "typescript": "^6.0.3",
     "vite": "^8.3.5",
-    "vitest": "^5.0.5"
+    "vitest": "^5.1.0"
   },
   "bugs": {
     "url": "https://gitlab.kilic.dev/utils/md-printer/-/issues"