deck

package
v0.0.23 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 30, 2026 License: MIT Imports: 27 Imported by: 0

Documentation

Overview

Package deck parses Margo Markdown and renders accessible HTML presentation decks.

After optional opening YAML frontmatter, an exact thematic break (---) outside a fenced code block separates slides. Frontmatter supplies the deck title and description. Parse returns the immutable slide model when a caller needs to inspect it directly. Render performs parsing, compiles every slide with the supplied margo.Compiler, and returns a complete HTML document:

result, err := deck.Render(ctx, compiler, deck.RenderInput{
	Name:     "talk.md",
	Markdown: source,
})
if err != nil {
	return err
}
html := result.HTML()

Result also reports the slide count, merged HTML requirements, document fingerprint, and runtime descriptor needed by later projections. Theme and color-mode defaults are Margo's modern theme and light mode. Detect inspects only opening frontmatter and returns true for `marp: true`, allowing a host to route a source into this package without changing the root compiler's ordinary Markdown behavior.

The implementation follows the versioned Margo Marpit-compatible v0.0.1 profile. It intentionally does not claim universal Marpit or Marp Core compatibility: only the built-in themes, directives, layouts, and extension contracts documented by this profile are accepted.

Index

Constants

View Source
const CompositionCatalogVersion = "r1"
View Source
const PDFMediaBoxToleranceMicrometers int64 = 170

PDFMediaBoxToleranceMicrometers covers the paper-size quantization introduced when Chromium converts CSS pixels to PDF points while preserving material geometry errors. Chromium's custom-page projection rounds to a 0.96-point grid (about 169 micrometres at its worst), so allow that renderer quantization without accepting a millimetre-scale mismatch.

Variables

This section is empty.

Functions

func CSSPixelsToMicrometers added in v0.0.7

func CSSPixelsToMicrometers(value float64) (int64, error)

func CanonicalLayoutValidationEnvelope added in v0.0.7

func CanonicalLayoutValidationEnvelope(envelope LayoutValidationEnvelope) ([]byte, error)

CanonicalLayoutValidationEnvelope serializes quantized logical evidence.

func Detect added in v0.0.7

func Detect(name string, source []byte) (bool, error)

Detect reports whether opening frontmatter explicitly opts into deck routing with `marp: true`. It does not parse or render the document body.

func FontBundleDigestV1 added in v0.0.7

func FontBundleDigestV1(faces []FontFaceAsset) (string, error)

FontBundleDigestV1 hashes the canonical margo-font-bundle/v1 preimage. Callers must provide the required faces in theme-row order and ascending weight order; accepting a different order would make two valid locks diverge.

func ValidateThemeColorPair added in v0.0.7

func ValidateThemeColorPair(theme margo.ThemeName, mode margo.ColorMode, foreground, background string) error

Types

type BackgroundState added in v0.0.7

type BackgroundState struct {
	Source     string
	Alt        string
	Decorative bool
	Position   string
	Repeat     string
	Size       string
}

BackgroundState is the typed background projection for one slide. Source, accessibility metadata, and sizing fields are reset atomically when a new background image is assigned.

type CompositionName added in v0.0.7

type CompositionName string

type CompositionSlot added in v0.0.7

type CompositionSlot struct {
	Name       string
	Role       string
	Required   bool
	SourceLine int
}

type CompositionSpec added in v0.0.7

type CompositionSpec struct {
	CatalogVersion string
	Name           CompositionName
	LayoutClass    string
	Variant        string
	MinSlots       int
	MaxSlots       int
	Slots          []CompositionSlot
	BodyRole       string
}

func ResolveComposition added in v0.0.7

func ResolveComposition(name CompositionName) (CompositionSpec, error)

type DeckGeometry added in v0.0.7

type DeckGeometry struct {
	Preset string
	Width  float64
	Height float64
	Unit   DeckUnit
}

DeckGeometry is the fixed logical canvas used by screen and print output.

func DefaultDeckGeometry added in v0.0.7

func DefaultDeckGeometry() DeckGeometry

func ParseDeckGeometry added in v0.0.7

func ParseDeckGeometry(value string) (DeckGeometry, error)

ParseDeckGeometry parses a normalized preset or an absolute custom size.

func (DeckGeometry) Equal added in v0.0.7

func (geometry DeckGeometry) Equal(other DeckGeometry) bool

func (DeckGeometry) Validate added in v0.0.7

func (geometry DeckGeometry) Validate() error

type DeckUnit added in v0.0.7

type DeckUnit string

DeckUnit is the finite absolute-unit vocabulary accepted for custom deck geometry. Public geometry is normalized to logical CSS pixels.

const (
	DeckUnitPX DeckUnit = "px"
	DeckUnitMM DeckUnit = "mm"
	DeckUnitCM DeckUnit = "cm"
	DeckUnitIN DeckUnit = "in"
	DeckUnitPT DeckUnit = "pt"
	DeckUnitPC DeckUnit = "pc"
	DeckUnitQ  DeckUnit = "Q"
)

type DirectiveState added in v0.0.7

type DirectiveState struct {
	Theme           margo.ThemeName
	Lang            string
	ColorMode       margo.ColorMode
	HeadingDivider  HeadingDivider
	Size            string
	Composition     CompositionName
	Paginate        string
	Header          string
	Footer          string
	Classes         []string
	Color           string
	BackgroundColor string
	Background      BackgroundState
}

DirectiveState is the immutable, normalized state effective for a slide. Empty local fields mean that the theme default is active.

type Document

type Document struct {
	// contains filtered or unexported fields
}

func Parse

func Parse(name string, source []byte) (*Document, error)

func (*Document) Directives added in v0.0.7

func (d *Document) Directives() DirectiveState

Directives returns the final deck-wide global directive state.

func (*Document) Metadata

func (d *Document) Metadata() Metadata

func (*Document) Slides

func (d *Document) Slides() []Slide

type FontFaceAsset added in v0.0.7

type FontFaceAsset struct {
	Family string
	Weight int
	Bytes  []byte
}

FontFaceAsset is one immutable versioned WOFF2 face used by a deck theme. Bytes are copied before hashing so callers cannot mutate a digest input.

type HeadingDivider added in v0.0.7

type HeadingDivider struct {
	Scalar int
	Levels []int
}

HeadingDivider describes the accepted Margo Marpit-compatible heading divider. Scalar values use inclusive H1-through-HN semantics; Levels uses exact heading levels when Scalar is zero.

type IDAllocator added in v0.0.7

type IDAllocator struct {
	// contains filtered or unexported fields
}

IDAllocator is a deterministic, render-wide HTML identity registry.

func NewRenderIDAllocator added in v0.0.7

func NewRenderIDAllocator(namespace string) *IDAllocator

NewRenderIDAllocator creates an allocator in a sanitized namespace.

func (*IDAllocator) Allocate added in v0.0.7

func (allocator *IDAllocator) Allocate(kind, sourceKey string) string

func (*IDAllocator) Resolve added in v0.0.7

func (allocator *IDAllocator) Resolve(kind, sourceKey string) (string, bool)

type Layout added in v0.0.7

type Layout struct {
	Class string
	Slots []LayoutSlot
}

Layout is the normalized structural layout model. A nil layout denotes the ordinary unstructured slide path.

type LayoutRect added in v0.0.7

type LayoutRect struct {
	Bottom float64 `json:"bottom"`
	Left   float64 `json:"left"`
	Right  float64 `json:"right"`
	Top    float64 `json:"top"`
}

type LayoutSlot added in v0.0.7

type LayoutSlot struct {
	Name       string
	Markdown   []byte
	SourceLine int
}

LayoutSlot is one source-ordered structural layout slot.

type LayoutValidationEnvelope added in v0.0.7

type LayoutValidationEnvelope struct {
	Version                   int                            `json:"version"`
	Mode                      LayoutValidationMode           `json:"mode"`
	LogicalCanvas             LogicalCanvas                  `json:"logicalCanvas"`
	Slides                    []SlideLayoutMetrics           `json:"slides"`
	Stage                     StageMetrics                   `json:"stage"`
	ValidationRequest         margo.RuntimeValidationRequest `json:"validationRequest"`
	CompositionCatalogVersion string                         `json:"compositionCatalogVersion,omitempty"`
}

LayoutValidationEnvelope is the canonical mode-bound browser evidence body.

type LayoutValidationMode added in v0.0.7

type LayoutValidationMode string

LayoutValidationMode identifies the two canonical deck layout tasks.

const (
	LayoutValidationModeScreen   LayoutValidationMode = "screen"
	LayoutValidationModePrintDOM LayoutValidationMode = "print-dom"
)

type LayoutValidator added in v0.0.7

type LayoutValidator interface {
	Validate(context.Context, []byte, margo.RuntimeDescriptor) (margo.RuntimeReport, error)
}

LayoutValidator is the browser-owned screen/print validation seam.

type LogicalCanvas added in v0.0.7

type LogicalCanvas struct {
	Width  float64 `json:"width"`
	Height float64 `json:"height"`
}

type Metadata

type Metadata struct {
	Title       string `yaml:"title"`
	Description string `yaml:"description"`
	Marp        *bool  `yaml:"marp"`
}

type PDFArtifactReport added in v0.0.7

type PDFArtifactReport struct {
	PageCount                 int                      `json:"pageCount"`
	MediaBoxesMicrometers     []PDFMediaBoxMicrometers `json:"mediaBoxesMicrometers"`
	EvidenceSHA256            string                   `json:"evidenceSHA256"`
	EvidenceBytes             int64                    `json:"evidenceBytes"`
	Valid                     bool                     `json:"valid"`
	CompositionCatalogVersion string                   `json:"compositionCatalogVersion,omitempty"`
	Compositions              []PDFCompositionIdentity `json:"compositions,omitempty"`
}

func BuildPDFArtifactReport added in v0.0.7

func BuildPDFArtifactReport(widthCSS, heightCSS float64, slideCount int, observed []PDFMediaBoxMicrometers) (PDFArtifactReport, error)

BuildPDFArtifactReport builds the non-recursive canonical evidence envelope for one normalized geometry and the observed page media boxes.

func BuildPDFArtifactReportWithComposition added in v0.0.7

func BuildPDFArtifactReportWithComposition(widthCSS, heightCSS float64, slideCount int, observed []PDFMediaBoxMicrometers, compositions []CompositionSpec) (PDFArtifactReport, error)

BuildPDFArtifactReportWithComposition adds the resolved R1 composition identity to the PDF evidence body while keeping the v0.0.1 four-argument builder byte-for-byte compatible when no composition is supplied.

type PDFArtifactValidator added in v0.0.7

type PDFArtifactValidator interface {
	Validate(context.Context, []byte, DeckGeometry, int) (PDFArtifactReport, error)
}

type PDFCompositionIdentity added in v0.0.7

type PDFCompositionIdentity struct {
	Name    string   `json:"name"`
	Variant string   `json:"variant"`
	Class   string   `json:"class"`
	Family  string   `json:"family"`
	Slots   []string `json:"slots,omitempty"`
}

type PDFMediaBoxMicrometers added in v0.0.7

type PDFMediaBoxMicrometers struct {
	Index             int   `json:"index"`
	LeftMicrometers   int64 `json:"leftMicrometers"`
	BottomMicrometers int64 `json:"bottomMicrometers"`
	RightMicrometers  int64 `json:"rightMicrometers"`
	TopMicrometers    int64 `json:"topMicrometers"`
}

func ParsePDFMediaBoxes added in v0.0.7

func ParsePDFMediaBoxes(data []byte) ([]PDFMediaBoxMicrometers, error)

ParsePDFMediaBoxes extracts page media boxes from a PDF byte stream and normalizes PDF points into integer micrometres. Chromium emits one media box per page in the artifacts accepted by the deck profile.

type PaginationIconConfig added in v0.0.7

type PaginationIconConfig struct {
	Symbol     string
	Placement  PaginationIconPlacement
	Label      string
	Decorative bool
}

PaginationIconConfig describes one trusted Goshtoso catalog icon in the bottom-right pagination cluster.

type PaginationIconPlacement added in v0.0.7

type PaginationIconPlacement string

PaginationIconPlacement fixes the icon's position relative to the ordinal.

const (
	PaginationIconBefore PaginationIconPlacement = "before"
	PaginationIconAfter  PaginationIconPlacement = "after"
)

type RenderInput

type RenderInput struct {
	Name      string
	Markdown  []byte
	BaseURL   string
	Theme     margo.ThemeName
	ColorMode margo.ColorMode
	Geometry  DeckGeometry
}

type RenderOption added in v0.0.7

type RenderOption func(*renderOptions) error

RenderOption overrides one immutable deck render setting.

func WithColorMode added in v0.0.7

func WithColorMode(mode margo.ColorMode) RenderOption

func WithConfidentialityBadge added in v0.0.7

func WithConfidentialityBadge(label string) RenderOption

WithConfidentialityBadge adds trusted host chrome before each visible page ordinal. Markdown cannot set or override this label.

func WithGeometry added in v0.0.7

func WithGeometry(geometry DeckGeometry) RenderOption

func WithPaginationIcon added in v0.0.7

func WithPaginationIcon(config PaginationIconConfig) RenderOption

WithPaginationIcon adds one trusted Goshtoso icon to each paginated slide. Placement is explicit; informative icons must provide a label.

func WithRenderIDAllocator added in v0.0.7

func WithRenderIDAllocator(allocator margo.RenderIDAllocator) RenderOption

WithRenderIDAllocator supplies a trusted render-wide identity registry to every slide and structural slot.

func WithTheme added in v0.0.7

func WithTheme(theme margo.ThemeName) RenderOption

func WithValidationRequest added in v0.0.7

func WithValidationRequest(request margo.RuntimeValidationRequest) RenderOption

WithValidationRequest selects a pinned viewport/profile for runtime evidence. The expected font digest is derived from the selected theme lock; a caller may only repeat that value, never replace it.

type Result

type Result struct {
	// contains filtered or unexported fields
}

func Render

func Render(ctx context.Context, compiler *margo.Compiler, input RenderInput, options ...RenderOption) (*Result, error)

func (*Result) DocumentFingerprint

func (r *Result) DocumentFingerprint() margo.DocumentFingerprint

func (*Result) Geometry added in v0.0.7

func (r *Result) Geometry() DeckGeometry

Geometry returns the fixed logical canvas selected for the deck.

func (*Result) HTML

func (r *Result) HTML() []byte

func (*Result) Requirements

func (r *Result) Requirements() margo.HTMLRequirements

func (*Result) RuntimeDescriptor

func (r *Result) RuntimeDescriptor(instance margo.RenderInstanceID) (margo.RuntimeDescriptor, error)

func (*Result) ScreenRuntimeDescriptor added in v0.0.7

func (r *Result) ScreenRuntimeDescriptor(instance margo.RenderInstanceID) (margo.RuntimeDescriptor, error)

ScreenRuntimeDescriptor returns the advisory profile-bound descriptor used by embedded hosts; it deliberately omits the print-DOM task.

func (*Result) SlideCount

func (r *Result) SlideCount() int

func (*Result) ValidationRequest added in v0.0.7

func (r *Result) ValidationRequest() margo.RuntimeValidationRequest

ValidationRequest returns the immutable profile request resolved during rendering.

type Slide

type Slide struct {
	// contains filtered or unexported fields
}

func (Slide) Composition added in v0.0.7

func (s Slide) Composition() CompositionSpec

Composition returns a defensive copy of the resolved R1 composition.

func (Slide) Directives added in v0.0.7

func (s Slide) Directives() DirectiveState

Directives returns a defensive copy of the effective slide state.

func (Slide) ID

func (s Slide) ID() string

func (Slide) Layout added in v0.0.7

func (s Slide) Layout() *Layout

Layout returns a defensive copy of the normalized structural layout.

func (Slide) Markdown

func (s Slide) Markdown() []byte

func (Slide) Notes added in v0.0.7

func (s Slide) Notes() []string

Notes returns presenter notes in source order.

func (Slide) Ordinal

func (s Slide) Ordinal() int

type SlideLayoutMetrics added in v0.0.7

type SlideLayoutMetrics struct {
	ID              string     `json:"id"`
	ClientHeight    float64    `json:"clientHeight"`
	ClientWidth     float64    `json:"clientWidth"`
	ContentHeight   float64    `json:"contentHeight"`
	ContentWidth    float64    `json:"contentWidth"`
	DescendantUnion LayoutRect `json:"descendantUnion"`
	ScrollHeight    float64    `json:"scrollHeight"`
	ScrollWidth     float64    `json:"scrollWidth"`
}

type StageMetrics added in v0.0.7

type StageMetrics struct {
	ControlsReserved float64 `json:"controlsReserved"`
	OriginX          float64 `json:"originX"`
	OriginY          float64 `json:"originY"`
	Scale            float64 `json:"scale"`
}

type ThemeCatalogEntry added in v0.0.7

type ThemeCatalogEntry struct {
	Theme       margo.ThemeName
	ColorMode   margo.ColorMode
	Tokens      ThemeTokens
	Typography  ThemeTypography
	PaddingX    float64
	PaddingY    float64
	HeaderZone  float64
	FooterZone  float64
	ContentGap  float64
	CardRadius  float64
	BorderWidth float64
	SlotPadding float64
	CardPadding float64
}

ThemeCatalogEntry freezes one theme/mode's visual contract.

func ThemeCatalog added in v0.0.7

func ThemeCatalog(theme margo.ThemeName, mode margo.ColorMode) (ThemeCatalogEntry, error)

ThemeCatalog returns a defensive copy of the selected frozen row.

type ThemeTokens added in v0.0.7

type ThemeTokens struct {
	Surface      string
	SurfaceAlt   string
	Ink          string
	InkMuted     string
	Accent       string
	AccentStrong string
	Positive     string
	Warning      string
	Negative     string
	Info         string
}

ThemeTokens is the finite semantic color surface exposed to deck CSS.

func (ThemeTokens) Value added in v0.0.7

func (tokens ThemeTokens) Value(name string) (string, bool)

type ThemeTypography added in v0.0.7

type ThemeTypography struct {
	BodyFamily    string
	HeadingFamily string
	CodeFamily    string
	BodySize      float64
	BodyLine      float64
	H1Size        float64
	H1Line        float64
	H2Size        float64
	H2Line        float64
	H3Size        float64
	H3Line        float64
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL