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, Tree, 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.

Asset images

You can embed images from Asset manifests using the asset: URL scheme in standard Markdown image syntax:

![Company Logo](asset:companyLogo)

The asset: prefix is resolved at build time to the actual URL based on the asset’s source type (localPath, remoteURL, or inlineBase64). See the Asset reference for details.

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}}$$