Name	Name	Last commit message	Last commit date
parent directory ..
README.md	README.md

Presentation Extension

Extension ID: codex.presentation Version: 0.1 Status: Draft

1. Overview

The Presentation Extension provides advanced layout and styling capabilities beyond the core specification:

Advanced page layout (columns, grids)
Print-specific features (bleeds, crop marks)
Master pages and templates
Advanced typography

File Paths

Presentation extension data is stored within the presentation/ directory in the Codex archive:

File	Purpose
`presentation/styles.json`	Typography, colors, and style definitions
`presentation/layout.json`	Master pages, templates, and layout rules
`presentation/toc.json`	Table of contents configuration

These files are referenced from the manifest's extension declaration.

2. Extension Declaration

{
  "extensions": [
    {
      "id": "codex.presentation",
      "version": "0.1",
      "required": false
    }
  ]
}

3. Advanced Page Layout

3.1 Multi-Column Layout

{
  "layout": {
    "type": "columns",
    "columns": 2,
    "gap": "0.25in",
    "balance": true
  }
}

Field	Type	Description
`columns`	integer	Number of columns (1-6)
`gap`	string	Gap between columns
`balance`	boolean	Balance column heights
`rule`	object	Column rule (separator line)

3.2 Grid Layout

{
  "layout": {
    "type": "grid",
    "columns": 12,
    "rows": "auto",
    "gap": "16px",
    "areas": [
      { "name": "header", "column": "1 / 13", "row": "1" },
      { "name": "sidebar", "column": "1 / 4", "row": "2" },
      { "name": "content", "column": "4 / 13", "row": "2" }
    ]
  }
}

3.3 Flow Regions

Define multiple regions for text to flow through:

{
  "flowRegions": [
    {
      "id": "main-flow",
      "regions": [
        { "page": 1, "area": "content" },
        { "page": 2, "area": "full" },
        { "page": 3, "area": "content" }
      ]
    }
  ]
}

4. Print Features

4.1 Bleed and Trim

For professional printing:

{
  "print": {
    "bleed": {
      "top": "0.125in",
      "right": "0.125in",
      "bottom": "0.125in",
      "left": "0.125in"
    },
    "trim": {
      "width": "8.5in",
      "height": "11in"
    },
    "cropMarks": true,
    "registrationMarks": true,
    "colorBars": false
  }
}

4.2 Spot Colors

{
  "colors": {
    "brand-blue": {
      "type": "spot",
      "name": "PANTONE 286 C",
      "fallback": "#0033a0"
    }
  }
}

4.3 Overprint

{
  "styles": {
    "blackText": {
      "color": "#000000",
      "overprint": true
    }
  }
}

4.4 PDF/X Compliance

{
  "print": {
    "standard": "PDF/X-4",
    "outputIntent": {
      "profile": "sRGB IEC61966-2.1",
      "condition": "sRGB"
    }
  }
}

5. Master Pages

5.1 Definition

Master pages define reusable page templates:

{
  "masterPages": {
    "default": {
      "margins": { "top": "1in", "right": "1in", "bottom": "1in", "left": "1in" },
      "header": { "height": "0.5in" },
      "footer": { "height": "0.5in" }
    },
    "chapter-start": {
      "basedOn": "default",
      "margins": { "top": "2in" },
      "header": null
    },
    "full-bleed": {
      "margins": { "top": "0", "right": "0", "bottom": "0", "left": "0" }
    }
  }
}

5.2 Application

Apply master pages to specific pages:

{
  "pages": [
    { "number": 1, "master": "chapter-start" },
    { "number": 2, "master": "default" },
    { "number": 3, "master": "full-bleed" }
  ]
}

5.3 Auto-Application Rules

{
  "masterRules": [
    { "match": { "first": true }, "master": "chapter-start" },
    { "match": { "contains": "full-bleed-image" }, "master": "full-bleed" },
    { "match": { "default": true }, "master": "default" }
  ]
}

6. Advanced Typography

6.1 OpenType Features

{
  "styles": {
    "body": {
      "fontFamily": "Source Serif Pro",
      "fontFeatureSettings": {
        "liga": true,
        "kern": true,
        "onum": true,
        "smcp": false
      }
    }
  }
}

Common features:

liga - Standard ligatures
kern - Kerning
onum - Oldstyle numerals
lnum - Lining numerals
smcp - Small caps
swsh - Swash
frac - Fractions

6.2 Variable Fonts

{
  "styles": {
    "heading": {
      "fontFamily": "Roboto Flex",
      "fontVariationSettings": {
        "wght": 700,
        "wdth": 100,
        "slnt": 0
      }
    }
  }
}

6.3 Hyphenation

{
  "typography": {
    "hyphenation": {
      "enabled": true,
      "language": "en-US",
      "minWordLength": 6,
      "minBefore": 3,
      "minAfter": 2,
      "maxConsecutive": 2
    }
  }
}

6.4 Widow/Orphan Control

{
  "typography": {
    "widows": 2,
    "orphans": 2,
    "avoidBreakInside": ["blockquote", "table"]
  }
}

6.5 Drop Caps

{
  "styles": {
    "chapter-first-para": {
      "dropCap": {
        "lines": 3,
        "fontFamily": "inherit",
        "fontWeight": "bold",
        "marginRight": "0.1em"
      }
    }
  }
}

6.6 Baseline Grid

{
  "typography": {
    "baselineGrid": {
      "enabled": true,
      "lineHeight": "14pt",
      "offset": "0pt"
    }
  }
}

6.7 Line Numbering

Line numbering in margins is common for legal briefs, manuscripts, and code review documents.

{
  "typography": {
    "lineNumbering": {
      "enabled": true,
      "start": 1,
      "interval": 1,
      "side": "left",
      "restart": "page"
    }
  }
}

Field	Type	Required	Description
`enabled`	boolean	Yes	Whether line numbering is active
`start`	integer	No	Starting line number (default: 1)
`interval`	integer	No	Number every N lines (default: 1, every 5 is common)
`side`	string	No	Which margin: `"left"` (default) or `"right"`
`restart`	string	No	When to restart numbering (see below)
`style`	object	No	Number styling (see below)

6.7.1 Restart Options

Value	Description
`page`	Restart numbering on each page
`section`	Restart at section boundaries
`none`	Continuous numbering throughout document

6.7.2 Line Number Styling

{
  "typography": {
    "lineNumbering": {
      "enabled": true,
      "interval": 5,
      "side": "left",
      "restart": "page",
      "style": {
        "fontSize": "8pt",
        "color": "#666666",
        "fontFamily": "monospace",
        "marginRight": "0.5em"
      }
    }
  }
}

6.7.3 Selective Line Numbering

For documents where only certain blocks should be numbered (e.g., code blocks only):

{
  "typography": {
    "lineNumbering": {
      "enabled": true,
      "scope": ["codeBlock", "blockquote"]
    }
  }
}

When scope is specified, only the listed block types receive line numbers. If omitted, all content is numbered.

7. Figures and Floats

Note: The figure and figcaption block types are now part of the core specification (see Content Blocks, Sections 4.20-4.21). This extension provides additional float positioning and advanced numbering capabilities.

7.1 Float Positioning

{
  "type": "image",
  "src": "assets/images/figure1.avif",
  "float": {
    "position": "top",
    "span": "column",
    "clearance": "1em"
  }
}

Position options: top, bottom, inline, page-top, page-bottom Span options: column, page, spread

7.2 Advanced Figure Numbering

The core figure block supports basic numbering ("auto", "none", or explicit number). This extension adds chapter-based numbering via the numberingConfig field:

The numberingConfig field provides extended numbering configuration beyond the core numbering field. The core numbering field (string or integer) controls basic numbering mode, while numberingConfig provides presentation-specific formatting options.

{
  "type": "figure",
  "children": [
    { "type": "image", "src": "..." },
    {
      "type": "figcaption",
      "children": [{ "type": "text", "value": "Figure 1: System architecture" }]
    }
  ],
  "numberingConfig": {
    "style": "Figure #",
    "chapter": true
  }
}

7.3 Cross-References

The presentation:reference block's target field uses Content Anchor URI syntax (see core Anchors and References specification). The # prefix identifies internal document references. The block uses the presentation: namespace prefix as required by the core content blocks spec (section 5) for extension block types:

{
  "type": "text",
  "value": "See ",
  "marks": []
},
{
  "type": "presentation:reference",
  "target": "#fig-architecture",
  "format": "Figure #"
}

8. Table of Contents

8.1 TOC Generation

{
  "tableOfContents": {
    "title": "Contents",
    "levels": [1, 2, 3],
    "styles": {
      "toc1": { "fontWeight": "bold", "marginTop": "1em" },
      "toc2": { "marginLeft": "1em" },
      "toc3": { "marginLeft": "2em", "fontSize": "0.9em" }
    },
    "pageNumbers": true,
    "leaders": "dots"
  }
}

8.2 List of Figures/Tables

{
  "listOfFigures": {
    "title": "List of Figures",
    "style": "toc2"
  },
  "listOfTables": {
    "title": "List of Tables",
    "style": "toc2"
  }
}

9. Index

9.1 Index Entries

In content:

{
  "type": "text",
  "value": "algorithm",
  "marks": [
    { "type": "index", "term": "algorithm", "subterm": "sorting" }
  ]
}

9.2 Index Generation

{
  "index": {
    "title": "Index",
    "columns": 2,
    "style": {
      "mainEntry": { "fontWeight": "bold" },
      "subEntry": { "marginLeft": "1em" }
    }
  }
}

10. Footnotes and Endnotes

10.1 Footnote Definition

Cross-Extension Note: When both the presentation and semantic extensions are active, the semantic extension provides the canonical footnote model with separate semantic:footnote blocks for footnote content. In this configuration, the presentation extension's footnote marks control styling and positioning only — the inline content array on presentation footnote marks is not used. The inline content array is a simplified alternative for documents that use the presentation extension without the semantic extension.