DocumentArtefact

DocumentArtefact manifests define standalone PDF documents rendered from Markdown source files. Unlike ReportArtefact which renders data-driven layouts, DocumentArtefact is designed for text-heavy documents like manuals, specifications, or narrative reports.

Spec outline

apiVersion: bino.bi/v1alpha1
kind: DocumentArtefact
metadata:
  name: technical_manual
spec:
  format: a4
  orientation: portrait
  locale: en
  filename: technical-manual.pdf
  title: "Technical Manual"
  author: "Engineering Team"
  subject: "Product Documentation"
  keywords: ["manual", "technical", "documentation"]
  sources:
    - ./docs/introduction.md
    - ./docs/installation.md
    - ./docs/configuration.md
  stylesheet: ./styles/manual.css
  tableOfContents: true
  math: true
  pageBreakBetweenSources: true
  displayHeaderFooter: true
  marginTop: "20mm"
  marginBottom: "15mm"
  signingProfile: corporateSigner

Fields

Basic settings

• spec.format – Page size: a4, a5, letter, or legal. Default: a4.
• spec.orientation – portrait or landscape. Default: portrait.
• spec.locale – Document locale (e.g., en, de). Default: en.
• spec.filename – Required output filename (relative to output directory).
• spec.title – Required document title; used in PDF metadata and default header.

Metadata

• spec.author – Optional author name for PDF metadata.
• spec.subject – Optional subject for PDF metadata.
• spec.keywords – Optional list of keywords for PDF metadata.

Content sources

• spec.sources – List of Markdown file paths or glob patterns to include in the document. Files matching glob patterns are sorted alphabetically for deterministic ordering. Supports patterns like ./docs/*.md or ./docs/**/*.md.
• spec.stylesheet – Optional path to a custom CSS file for styling.
• spec.pageBreakBetweenSources – Insert page breaks between source files. Default: false.

Glob patterns

You can use glob patterns to include multiple markdown files:

sources:
  - ./docs/**/*.md       # All .md files in docs folder (recursive)
  - ./appendix/*.md      # All .md files directly in appendix folder
  - ./README.md          # Single file

Files are deduplicated if patterns overlap, and sorted alphabetically within each pattern expansion.

Table of contents

• spec.tableOfContents – Generate a table of contents from headings. Default: false.

When enabled, the table of contents is automatically generated from all h1-h6 headings that have an id attribute (standard Markdown headings get IDs automatically). The TOC includes page numbers for each heading, calculated during a two-pass rendering process.

The TOC appears at the beginning of the document and includes a page break after it.

Math rendering

• spec.math – Enable LaTeX math rendering via KaTeX. Default: true.

When enabled, you can include mathematical expressions in your Markdown:

• Inline math: Use single dollar signs $...$ for inline expressions like $E = mc^2$
• Block math: Use double dollar signs $$...$$ for display equations

The quadratic formula is $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$.

For summations, use display mode:

$$\sum_{i=1}^n x_i = x_1 + x_2 + \cdots + x_n$$

Math is rendered server-side using KaTeX, so no JavaScript is required in the output PDF.

Header and footer

• spec.displayHeaderFooter – Enable header and footer in the PDF. Default: false.
• spec.headerTemplate – Custom HTML template for the header.
• spec.footerTemplate – Custom HTML template for the footer.
• spec.marginTop – Top margin (e.g., 20mm). Required when using headers.
• spec.marginBottom – Bottom margin (e.g., 15mm). Required when using footers.

When displayHeaderFooter is enabled without custom templates, default templates are used:

• Header: Document title centered
• Footer: Current date on the left, page number on the right

Custom header/footer templates

Templates use Chromium’s PDF header/footer format. Available CSS classes:

• .title – Document title
• .date – Current date
• .pageNumber – Current page number
• .totalPages – Total page count

Example custom footer:

spec:
  displayHeaderFooter: true
  marginBottom: "15mm"
  footerTemplate: |
    <div style="font-size: 10px; width: 100%; text-align: center;">
      <span class="pageNumber"></span> / <span class="totalPages"></span>
    </div>

Signing

• spec.signingProfile – Optional reference to a SigningProfile manifest for digital signatures.

Markdown features

DocumentArtefact supports standard Markdown plus:

Component references

Use the :ref[Kind:name] syntax to embed report components (tables, charts) in your document:

## Sales Overview

The following table shows quarterly sales:

:ref[Table:quarterly_sales]

And here's the trend chart:

:ref[ChartTime:sales_trend]

Referenced components must be defined as Table, ChartTime, ChartTree, ChartStructure, Text, Image, LayoutCard, or Grid manifests in your project.

Figure captions

Add captions to referenced components using the {caption="..."} syntax:

:ref[Table:quarterly_sales]{caption="Table 1: Quarterly Sales by Region"}

:ref[ChartTime:revenue_trend]{caption="Figure 2: Revenue Growth 2020-2024"}

This wraps the component in an HTML <figure> element with a <figcaption>, which:

• Centers the caption below the component
• Prevents page breaks inside the figure
• Uses italic styling for the caption text

Refs without a caption are rendered as before, without the figure wrapper.

Syntax highlighting

Code blocks with language hints are syntax-highlighted:

```sql
SELECT * FROM sales WHERE year = 2024;
```

Examples

Minimal document

apiVersion: bino.bi/v1alpha1
kind: DocumentArtefact
metadata:
  name: readme
spec:
  filename: readme.pdf
  title: "Project README"
  sources:
    - ./README.md

Document with TOC and page numbers

apiVersion: bino.bi/v1alpha1
kind: DocumentArtefact
metadata:
  name: user_guide
spec:
  format: a4
  orientation: portrait
  filename: user-guide.pdf
  title: "User Guide"
  author: "Documentation Team"
  tableOfContents: true
  displayHeaderFooter: true
  marginTop: "20mm"
  marginBottom: "15mm"
  sources:
    - ./docs/getting-started.md
    - ./docs/features.md
    - ./docs/troubleshooting.md
  pageBreakBetweenSources: true

Document with embedded report components

apiVersion: bino.bi/v1alpha1
kind: DocumentArtefact
metadata:
  name: quarterly_report
spec:
  format: a4
  filename: q4-report.pdf
  title: "Q4 2024 Report"
  tableOfContents: true
  displayHeaderFooter: true
  marginTop: "20mm"
  marginBottom: "15mm"
  sources:
    - ./narrative/executive-summary.md
    - ./narrative/financial-analysis.md
    - ./narrative/outlook.md

Where executive-summary.md might contain:

# Executive Summary

This quarter showed strong growth across all regions.

## Revenue by Region

:ref[Table:revenue_by_region]{caption="Table 1: Revenue by Region (in millions)"}

## Growth Trend

:ref[ChartTime:quarterly_growth]{caption="Figure 1: Quarterly Growth Rate"}

Document with custom styling

apiVersion: bino.bi/v1alpha1
kind: DocumentArtefact
metadata:
  name: branded_manual
spec:
  filename: manual.pdf
  title: "Product Manual"
  stylesheet: ./styles/brand.css
  tableOfContents: true
  displayHeaderFooter: true
  marginTop: "25mm"
  marginBottom: "20mm"
  headerTemplate: |
    <div style="font-size: 10px; width: 100%; border-bottom: 1px solid #ccc; padding-bottom: 5px;">
      <span style="float: left;">ACME Corp</span>
      <span style="float: right;" class="title"></span>
    </div>
  footerTemplate: |
    <div style="font-size: 9px; width: 100%; text-align: center; color: #666;">
      Page <span class="pageNumber"></span> of <span class="totalPages"></span> | Confidential
    </div>
  sources:
    - ./manual/introduction.md
    - ./manual/usage.md
    - ./manual/reference.md

Document with glob patterns

apiVersion: bino.bi/v1alpha1
kind: DocumentArtefact
metadata:
  name: complete_docs
spec:
  filename: complete-documentation.pdf
  title: "Complete Documentation"
  tableOfContents: true
  pageBreakBetweenSources: true
  sources:
    - ./docs/**/*.md    # Include all markdown files recursively

Document with math equations

apiVersion: bino.bi/v1alpha1
kind: DocumentArtefact
metadata:
  name: research_paper
spec:
  format: a4
  filename: research-paper.pdf
  title: "Statistical Analysis Methods"
  author: "Research Team"
  tableOfContents: true
  math: true
  sources:
    - ./paper/abstract.md
    - ./paper/methodology.md
    - ./paper/results.md
    - ./paper/conclusion.md

Where methodology.md might contain:

# Methodology

We use the standard deviation formula:

$$\sigma = \sqrt{\frac{1}{N}\sum_{i=1}^N (x_i - \mu)^2}$$

The correlation coefficient $r$ is calculated as:

$$r = \frac{\sum_{i=1}^n (x_i - \bar{x})(y_i - \bar{y})}{\sqrt{\sum_{i=1}^n (x_i - \bar{x})^2 \sum_{i=1}^n (y_i - \bar{y})^2}}$$