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
- func CSSPixelsToMicrometers(value float64) (int64, error)
- func CanonicalLayoutValidationEnvelope(envelope LayoutValidationEnvelope) ([]byte, error)
- func Detect(name string, source []byte) (bool, error)
- func FontBundleDigestV1(faces []FontFaceAsset) (string, error)
- func ValidateThemeColorPair(theme margo.ThemeName, mode margo.ColorMode, foreground, background string) error
- type BackgroundState
- type CompositionName
- type CompositionSlot
- type CompositionSpec
- type DeckGeometry
- type DeckUnit
- type DirectiveState
- type Document
- type FontFaceAsset
- type HeadingDivider
- type IDAllocator
- type Layout
- type LayoutRect
- type LayoutSlot
- type LayoutValidationEnvelope
- type LayoutValidationMode
- type LayoutValidator
- type LogicalCanvas
- type Metadata
- type PDFArtifactReport
- type PDFArtifactValidator
- type PDFCompositionIdentity
- type PDFMediaBoxMicrometers
- type PaginationIconConfig
- type PaginationIconPlacement
- type RenderInput
- type RenderOption
- func WithColorMode(mode margo.ColorMode) RenderOption
- func WithConfidentialityBadge(label string) RenderOption
- func WithGeometry(geometry DeckGeometry) RenderOption
- func WithPaginationIcon(config PaginationIconConfig) RenderOption
- func WithRenderIDAllocator(allocator margo.RenderIDAllocator) RenderOption
- func WithTheme(theme margo.ThemeName) RenderOption
- func WithValidationRequest(request margo.RuntimeValidationRequest) RenderOption
- type Result
- func (r *Result) DocumentFingerprint() margo.DocumentFingerprint
- func (r *Result) Geometry() DeckGeometry
- func (r *Result) HTML() []byte
- func (r *Result) Requirements() margo.HTMLRequirements
- func (r *Result) RuntimeDescriptor(instance margo.RenderInstanceID) (margo.RuntimeDescriptor, error)
- func (r *Result) ScreenRuntimeDescriptor(instance margo.RenderInstanceID) (margo.RuntimeDescriptor, error)
- func (r *Result) SlideCount() int
- func (r *Result) ValidationRequest() margo.RuntimeValidationRequest
- type Slide
- type SlideLayoutMetrics
- type StageMetrics
- type ThemeCatalogEntry
- type ThemeTokens
- type ThemeTypography
Constants ¶
const CompositionCatalogVersion = "r1"
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 CanonicalLayoutValidationEnvelope ¶ added in v0.0.7
func CanonicalLayoutValidationEnvelope(envelope LayoutValidationEnvelope) ([]byte, error)
CanonicalLayoutValidationEnvelope serializes quantized logical evidence.
func Detect ¶ added in v0.0.7
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.
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 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
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.
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
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 (*Document) Directives ¶ added in v0.0.7
func (d *Document) Directives() DirectiveState
Directives returns the final deck-wide global directive state.
type FontFaceAsset ¶ added in v0.0.7
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
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
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 LayoutSlot ¶ added in v0.0.7
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 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 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 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) 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 (*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) Layout ¶ added in v0.0.7
Layout returns a defensive copy of the normalized structural layout.
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 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
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
ThemeCatalog returns a defensive copy of the selected frozen row.