mdhtml

package
v0.4.1 Latest Latest
Warning

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

Go to latest
Published: Aug 10, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Overview

Package mdhtml exports `.md` → `.html` for ipmt-rich docs.

This file implements the syntax-highlighting half: given an ipmt block's source text and the LSP semantic tokens for it, emit the same `<span class="ipm-…">` HTML markup the VS Code markdown preview emits via previewHighlight.ts:renderFromLspTokens.

Cross-language parity is enforced by:

  • The (tokenType, modifierBit) → cssClassSuffix table comes from the palette source of truth (pkg/ipmtokens/palette.json, via ipmtokens.ClassSuffix); drift between languages at the data layer is structurally impossible.
  • A shared golden-fixture corpus (testdata/highlight-cases/*.json) that BOTH this Go highlighter and the TS renderFromLspTokens are asserted byte-equal against. Algorithmic drift is detected by test, not by inspection.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func HighlightTokens

func HighlightTokens(src string, tokens []ipmtokens.Token) string

HighlightTokens converts (source text, LSP tokens) into the `<pre><code class="language-ipmt">…</code></pre>` HTML body the markdown preview emits. Overlap resolution is LAST-WINS PER CHARACTER, matching previewHighlight.ts. Class names come from ipmtokens.ClassSuffix (pkg/ipmtokens/palette.json) — the same source that produces the preview's CSS.

func SortedTokensCopy

func SortedTokensCopy(tokens []ipmtokens.Token) []ipmtokens.Token

SortedTokensCopy returns a copy of `tokens` sorted by (line, col) with stable ordering for equal positions. Useful for deterministic output and for tests that need to compare token streams across languages. Not used by HighlightTokens itself — last-wins doesn't require sorted input — but exported for callers that produce tokens in arbitrary order.

Types

type Config

type Config struct {
	// OutDir is the output root. File-level `out` paths are resolved
	// against it.
	OutDir string `json:"out_dir"`

	// ExtraCSS is an optional global stylesheet — linked into every page
	// in addition to the bundled palette.
	ExtraCSS string `json:"extra_css,omitempty"`

	// TitleTemplate, if set, replaces `{{title}}` with the page's first
	// H1 (or basename if there is no H1) and `{{path}}` with the
	// source-relative path. Default: just the title.
	TitleTemplate string `json:"title_template,omitempty"`

	// Header is the top site bar (brand → main site + menu).
	Header HeaderConfig `json:"header"`

	// Footer is the bottom bar (tagline + per-page "view source").
	Footer FooterConfig `json:"footer"`

	// NoTOC disables the auto-generated table of contents. Default is
	// false → TOC is rendered after the H1 of every page that has at
	// least one H2.
	NoTOC bool `json:"no_toc,omitempty"`

	// Files lists explicit src → out mappings. Source paths are
	// resolved relative to the config file's directory.
	Files []FileMapping `json:"file,omitempty"`

	// Globs lists glob patterns; output paths mirror the source tree
	// under OutDir with .md → .html.
	Globs []GlobMapping `json:"glob,omitempty"`
}

Config drives the md-html exporter. Loaded from a JSON file with the shape documented below. JSON (vs the TOML the analysis sketched) keeps v1 stdlib-only — easy to migrate later.

func LoadConfig

func LoadConfig(path string) (*Config, error)

LoadConfig reads + parses the config at the given path and applies defaults (Branch, SourceLabel, OutDir).

type FileMapping

type FileMapping struct {
	Src string `json:"src"`
	Out string `json:"out"`
}

type FooterConfig

type FooterConfig struct {
	Text        string `json:"text,omitempty"`         // tagline / copyright (left)
	Repo        string `json:"repo,omitempty"`         // blank → no source link
	Branch      string `json:"branch,omitempty"`       // default "main"
	SourceLabel string `json:"source_label,omitempty"` // default "GitHub"
}

FooterConfig is the bottom bar: a tagline plus a per-page "view source" link (to the page's own markdown source on GitHub).

type GlobMapping

type GlobMapping struct {
	Src string `json:"src"`
}

type HeaderConfig

type HeaderConfig struct {
	HomeURL string `json:"home_url"` // the brand links here (default https://infinite.pm/)
	Brand   string `json:"brand"`    // brand text, dot-split into coloured spans (default "infinite.pm")
	// Logo, when set, replaces that text with the real logo — which is the only
	// thing that gets the name's colours right. Splitting on dots can only give
	// the last SEGMENT one colour, so "pm" comes out all blue where the logo has
	// an orange p and a blue m. Given relative to the output root, and adjusted
	// per page depth, so pages nested in subdirectories still find it.
	LogoAlt string     `json:"logo_alt"`       // defaults to the brand text
	Menu    []MenuLink `json:"menu,omitempty"` // nav links on the right
}

HeaderConfig is the top site bar: a brand that links to the main site, plus a menu.

type MenuLink struct {
	Label string `json:"label"`
	URL   string `json:"url"`
}

MenuLink is one header nav entry.

type RenderResult

type RenderResult struct {
	SrcAbs     string
	OutAbs     string
	Title      string
	IpmtBlocks int
	SVGEmbeds  int
}

RenderResult is the per-file outcome of a render run.

func RenderPage

func RenderPage(cfg *Config, srcAbs, outAbs, srcRel string) (*RenderResult, error)

RenderPage produces the full HTML page for one markdown source. `srcRel` is the source path relative to the config root, used in the header's "View source on GitHub" link.

type ResolvedMapping

type ResolvedMapping struct {
	SrcAbs string
	OutAbs string
	SrcRel string
}

ResolvedMapping is one (source .md, output .html) pair after globs have been expanded. SrcRel is the source path relative to the config root (= directory containing the config file) — used for the "View source on GitHub" link.

func ResolveMappings

func ResolveMappings(cfg *Config, configDir string) ([]ResolvedMapping, error)

ResolveMappings expands Files + Globs into concrete file pairs. `configDir` is the directory containing the config (used as the root for relative source paths). Returns mappings sorted by SrcRel for deterministic output ordering.

Jump to

Keyboard shortcuts

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