Documentation
¶
Overview ¶
Package md2html renders Markdown as HTML and serves or writes the result.
The package provides three main entry points:
RenderFragment renders a single Markdown string. NewLoader parses Markdown into headings, links, lists, and frontmatter. Run drives the server and static-site modes used by the md2html command.
Rendering uses Goldmark with GFM extensions, syntax highlighting, admonitions, optional table-of-contents generation, and relative-link rewriting for Markdown source trees.
For small in-process rendering, use RenderFragment:
frag := md2html.RenderFragment("# Hello\n", "", md2html.FragmentOptions{})
_ = frag.HTML
For command-style integration, build a Config and call Run:
fs := md2html.NewFlagSet("md2html")
_ = fs.Parse([]string{"-http", ":8080", "README.md"})
cfg := md2html.ConfigFromFlags(fs)
err := md2html.Run(context.Background(), cfg, slog.Default(), os.Stdout, fs.Args())
For navigation and structured parsing, use ParseSummary and Loader.
Index ¶
- func FragmentStyles() template.CSS
- func NewFlagSet(name string) *flag.FlagSet
- func Run(ctx context.Context, cfg Config, logger *slog.Logger, out io.Writer, ...) error
- type Config
- type DocumentData
- type Fragment
- type FragmentOptions
- type GitVersion
- type GitVersionManager
- func (gvm *GitVersionManager) CheckoutVersion(version string) error
- func (gvm *GitVersionManager) GetCurrentVersion() (string, error)
- func (gvm *GitVersionManager) GetFileContent(version, filePath string) ([]byte, error)
- func (gvm *GitVersionManager) IsGitRepo() bool
- func (gvm *GitVersionManager) ListFiles(version, pattern string) ([]string, error)
- func (gvm *GitVersionManager) ListVersions(includeBranches bool, tagPattern string) ([]GitVersion, error)
- type Heading
- type Link
- type ListItem
- type Loader
- func (l *Loader) Load(path string) (interface{}, error)
- func (l *Loader) LoadJSON(path string) (interface{}, error)
- func (l *Loader) LoadMD(path string) (*MarkdownDoc, error)
- func (l *Loader) LoadSummary(path string) (*Navigation, error)
- func (l *Loader) LoadYAML(path string) (interface{}, error)
- func (l *Loader) ParseMD(content string) (*MarkdownDoc, error)
- func (l *Loader) TemplateFuncs() template.FuncMap
- type MarkdownDoc
- type NavContext
- type NavItem
- type Navigation
- type RenderOptions
- type SearchDocument
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FragmentStyles ¶
FragmentStyles returns shared CSS for rendered markdown fragments.
func NewFlagSet ¶
NewFlagSet returns a FlagSet configured for the md2html CLI.
Types ¶
type Config ¶
type Config struct {
Source string // file, directory, or "-" for stdin
HTTP string
HTML string
Open bool
Verbose bool
Title string
CSS string
Depth int
TOC bool
AllowUnsafe bool
TemplateDir string
DataJSON string
RenderFrontmatter bool
Index string
HTMLExt string
Versions bool
VersionPattern string
VersionBranches bool
VersionDefault string
Search bool
}
func ConfigFromFlags ¶
ConfigFromFlags creates a Config from an initialized FlagSet.
type DocumentData ¶
type Fragment ¶
type Fragment struct {
HTML template.HTML
ChromaCSS template.CSS
HasMath bool
HasMermaid bool
MermaidTheme string
MermaidDarkTheme string
MermaidAutoTheme bool
}
Fragment contains rendered markdown plus enhancement metadata for clients.
func RenderFragment ¶
func RenderFragment(markdown, filePath string, opts FragmentOptions) Fragment
RenderFragment renders markdown using the md2html pipeline and returns client enhancement metadata for MathJax and Mermaid.
type FragmentOptions ¶
type FragmentOptions struct {
AllowUnsafe bool
TOC bool
HTMLExt string
Frontmatter map[string]interface{}
}
FragmentOptions configures fragment rendering.
type GitVersion ¶
type GitVersion struct {
Name string // Tag or branch name
Ref string // Full git reference (e.g., refs/tags/v1.0.0)
IsTag bool // true if this is a tag, false if branch
Commit string // Short commit hash
}
GitVersion represents a git tag or branch that can be used for versioned docs
type GitVersionManager ¶
type GitVersionManager struct {
// contains filtered or unexported fields
}
GitVersionManager handles git operations for versioned documentation
func NewGitVersionManager ¶
func NewGitVersionManager(repoPath string) *GitVersionManager
NewGitVersionManager creates a new git version manager for the given repository
func (*GitVersionManager) CheckoutVersion ¶
func (gvm *GitVersionManager) CheckoutVersion(version string) error
CheckoutVersion checks out a specific version (for local development)
func (*GitVersionManager) GetCurrentVersion ¶
func (gvm *GitVersionManager) GetCurrentVersion() (string, error)
GetCurrentVersion returns the current version (tag or branch)
func (*GitVersionManager) GetFileContent ¶
func (gvm *GitVersionManager) GetFileContent(version, filePath string) ([]byte, error)
GetFileContent returns the content of a file at a specific version
func (*GitVersionManager) IsGitRepo ¶
func (gvm *GitVersionManager) IsGitRepo() bool
IsGitRepo checks if the given path is inside a git repository
func (*GitVersionManager) ListFiles ¶
func (gvm *GitVersionManager) ListFiles(version, pattern string) ([]string, error)
ListFiles returns all files at a specific version matching a pattern
func (*GitVersionManager) ListVersions ¶
func (gvm *GitVersionManager) ListVersions(includeBranches bool, tagPattern string) ([]GitVersion, error)
ListVersions returns all available versions (tags and optionally branches)
type Link ¶
type Link struct {
Text string // Link text
URL string // Link URL
Line int // Source line number
Indent int // Indentation level (for list items)
}
Link represents a link in the document.
type ListItem ¶
type ListItem struct {
Text string // Item text (without link)
Link *Link // Link if item contains one
Indent int // Nesting level (0 = top level)
Children []ListItem // Nested list items
}
ListItem represents an item in a list, potentially with nested children.
type Loader ¶
type Loader struct {
// contains filtered or unexported fields
}
Loader loads and parses data files (JSON, YAML, Markdown).
func (*Loader) LoadMD ¶
func (l *Loader) LoadMD(path string) (*MarkdownDoc, error)
LoadMD loads and parses a markdown file into structured data.
func (*Loader) LoadSummary ¶
func (l *Loader) LoadSummary(path string) (*Navigation, error)
LoadSummary loads and parses SUMMARY.md from a directory.
func (*Loader) ParseMD ¶
func (l *Loader) ParseMD(content string) (*MarkdownDoc, error)
ParseMD parses markdown content into a MarkdownDoc.
func (*Loader) TemplateFuncs ¶
TemplateFuncs returns template functions for data loading.
type MarkdownDoc ¶
type MarkdownDoc struct {
Frontmatter map[string]interface{} // YAML frontmatter
Content string // Raw markdown content
HTML template.HTML // Rendered HTML
Title string // First H1 or frontmatter title
Headings []Heading // All headings
Links []Link // All links with context
Lists []ListItem // Top-level list items (with nesting)
}
MarkdownDoc represents a parsed markdown file with extracted structure.
type NavContext ¶
type NavContext struct {
}
NavContext provides navigation state for a specific page.
type NavItem ¶
type NavItem struct {
}
NavItem represents a single navigation entry from SUMMARY.md.
type Navigation ¶
type Navigation struct {
}
Navigation represents the full navigation tree parsed from SUMMARY.md.
func LoadNavigationFromDir ¶
func LoadNavigationFromDir(dir, htmlExt string) *Navigation
LoadNavigationFromDir loads SUMMARY.md from a directory if it exists.
func ParseSummary ¶
func ParseSummary(content, htmlExt string) (*Navigation, error)
ParseSummary parses SUMMARY.md content into a Navigation structure.
func (*Navigation) ForPage ¶
func (n *Navigation) ForPage(currentPath string) *NavContext
ForPage returns navigation context for a specific page path.
type RenderOptions ¶
type RenderOptions struct {
SiteTitle string
Data interface{} // from -data-json
}
RenderOptions contains optional parameters for rendering.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
md2html
command
Command md2html renders Markdown as HTML.
|
Command md2html renders Markdown as HTML. |
|
internal
|
|
|
scripttestutil
Package scripttestutil helps with script-based testing.
|
Package scripttestutil helps with script-based testing. |