markdown

package
v0.22.0 Latest Latest
Warning

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

 Go to latest Published: Jan 28, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Overview

Package markdown provides the concrete implementation of the Markdown ingestion workflows outlined in docs/FEAT_MARKDOWN.md. Phase 1 focuses on parsing and metadata extraction; higher phases add filesystem discovery, CMS import wiring, and command orchestration.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrContentServiceRequired = errors.New("markdown importer: content service is required")
	ErrPageServiceRequired    = errors.New("markdown importer: page service required when CreatePages is enabled")
	ErrSlugMissing            = errors.New("markdown importer: frontmatter slug is required")
	ErrLocaleMissing          = errors.New("markdown importer: locale could not be determined")
	ErrTemplateMissing        = errors.New("markdown importer: template id required when CreatePages is enabled")
)

Functions

func BuildDocument 

func BuildDocument(path string, locale string, source []byte, modified time.Time) (*interfaces.Document, error)

BuildDocument assembles an interfaces.Document from the supplied file path, locale, raw content, and modification time. BodyHTML is intentionally left empty so callers can render lazily.

func ParseFrontMatter 

func ParseFrontMatter(source []byte) (interfaces.FrontMatter, []byte, error)

ParseFrontMatter extracts metadata and Markdown body content from the provided source bytes. It returns the structured frontmatter, the Markdown body without delimiters, and any error encountered.

Types

type Config 

type Config struct {
	BasePath          string
	DefaultLocale     string
	Locales           []string
	LocalePatterns    map[string]string
	Pattern           string
	Recursive         bool
	Parser            interfaces.ParseOptions
	ProcessShortcodes bool
}

Config controls how the Markdown service discovers and parses files.

type DocumentResult 

type DocumentResult struct {
	Document *interfaces.Document
	Source   []byte
}

DocumentResult carries the parsed document along with the raw source.

type GoldmarkParser 

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

GoldmarkParser implements interfaces.MarkdownParser using the goldmark engine. The parser is intentionally stateless so callers can reuse a single instance across requests without additional locking.

func NewGoldmarkParser 

func NewGoldmarkParser(defaults interfaces.ParseOptions) *GoldmarkParser

NewGoldmarkParser constructs a parser with sensible defaults (GFM extensions, hard wraps disabled, unsafe HTML allowed). Callers can override behaviour per invocation through ParseWithOptions to stay aligned with Option 1's flexible configuration goals.

func (*GoldmarkParser) Parse 

func (p *GoldmarkParser) Parse(markdown []byte) ([]byte, error)

Parse satisfies interfaces.MarkdownParser by rendering Markdown into HTML using the parser's default configuration.

func (*GoldmarkParser) ParseWithOptions 

func (p *GoldmarkParser) ParseWithOptions(markdown []byte, opts interfaces.ParseOptions) ([]byte, error)

ParseWithOptions renders Markdown into HTML using the provided options. Future phases may replace the per-call goldmark instantiation with a pool to reduce allocations once performance measurements are available (see TODO).

type Importer 

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

Importer orchestrates conversion of markdown documents into content and pages.

func NewImporter 

func NewImporter(cfg ImporterConfig) *Importer

NewImporter builds an Importer from the supplied configuration.

func (*Importer) ImportDocument 

func (i *Importer) ImportDocument(ctx context.Context, doc *interfaces.Document, opts interfaces.ImportOptions) (*interfaces.ImportResult, error)

ImportDocument imports a single markdown document.

func (*Importer) ImportDocuments 

func (i *Importer) ImportDocuments(ctx context.Context, docs []*interfaces.Document, opts interfaces.ImportOptions) (*interfaces.ImportResult, error)

ImportDocuments imports an arbitrary slice of documents, grouping them by slug.

func (*Importer) SyncDocuments 

func (i *Importer) SyncDocuments(ctx context.Context, docs []*interfaces.Document, opts interfaces.SyncOptions) (*interfaces.SyncResult, error)

SyncDocuments imports all provided documents and optionally deletes orphaned content.

type ImporterConfig 

type ImporterConfig struct {
	Content interfaces.ContentService
	Pages   interfaces.PageService
	Logger  interfaces.Logger
}

ImporterConfig encapsulates dependencies required to persist markdown documents.

type LoadParams 

type LoadParams struct {
	Pattern        string
	LocalePatterns map[string]string
	Recursive      *bool
}

LoadParams provide call-specific overrides for locale detection and pattern matching.

type Loader 

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

Loader turns filesystem paths into Markdown documents with metadata.

func NewLoader 

func NewLoader(filesystem fs.FS, cfg LoaderConfig) *Loader

NewLoader constructs a Loader using the provided filesystem and configuration.

func (*Loader) LoadDirectory 

func (l *Loader) LoadDirectory(ctx context.Context, dir string, opts LoadParams) ([]*DocumentResult, error)

LoadDirectory discovers Markdown files under dir and returns parsed documents.

func (*Loader) LoadFile 

func (l *Loader) LoadFile(ctx context.Context, path string, opts LoadParams) (*DocumentResult, error)

LoadFile reads and parses a single Markdown document.

type LoaderConfig 

type LoaderConfig struct {
	// BasePath is the root directory where Markdown documents live.
	BasePath string
	// DefaultLocale is used when no locale can be inferred from the file path.
	DefaultLocale string
	// Locales enumerates the known locales (e.g. ["en", "es"]) for quick directory matching.
	Locales []string
	// LocalePatterns maps locale identifiers to glob expressions relative to BasePath.
	LocalePatterns map[string]string
	// Pattern limits discovered files to those matching the supplied glob (defaults to "*.md").
	Pattern string
	// Recursive controls whether sub-directories are traversed.
	Recursive bool
}

LoaderConfig configures how Markdown files are discovered within a base directory.

type Service 

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

Service implements interfaces.MarkdownService for filesystem-backed documents.

func NewService 

func NewService(cfg Config, parser interfaces.MarkdownParser, opts ...ServiceOption) (*Service, error)

NewService constructs a Markdown service using an underlying loader. When parser is nil, a Goldmark parser with the provided default options is created.

func (*Service) Import 

func (s *Service) Import(ctx context.Context, doc *interfaces.Document, opts interfaces.ImportOptions) (*interfaces.ImportResult, error)

func (*Service) ImportDirectory 

func (s *Service) ImportDirectory(ctx context.Context, dir string, opts interfaces.ImportOptions) (*interfaces.ImportResult, error)

func (*Service) Load 

func (s *Service) Load(ctx context.Context, path string, opts interfaces.LoadOptions) (*interfaces.Document, error)

Load reads a single Markdown document relative to the configured base path.

func (*Service) LoadDirectory 

func (s *Service) LoadDirectory(ctx context.Context, dir string, opts interfaces.LoadOptions) ([]*interfaces.Document, error)

LoadDirectory reads every Markdown document within the supplied directory.

func (*Service) Render 

func (s *Service) Render(ctx context.Context, markdown []byte, opts interfaces.ParseOptions) ([]byte, error)

Render parses Markdown bytes into HTML using the configured parser.

func (*Service) RenderDocument 

func (s *Service) RenderDocument(ctx context.Context, doc *interfaces.Document, opts interfaces.ParseOptions) ([]byte, error)

RenderDocument converts the document's Markdown body into HTML using the configured parser.

func (*Service) Sync 

func (s *Service) Sync(ctx context.Context, dir string, opts interfaces.SyncOptions) (*interfaces.SyncResult, error)

type ServiceOption 

type ServiceOption func(*Service)

ServiceOption configures optional dependencies for the markdown service.

func WithContentService 

func WithContentService(svc interfaces.ContentService) ServiceOption

WithContentService wires the content service used during import/sync.

func WithLogger 

func WithLogger(logger interfaces.Logger) ServiceOption

WithLogger attaches a logger for importer diagnostics.

func WithPageService 

func WithPageService(svc interfaces.PageService) ServiceOption

WithPageService wires the page service used to create or update pages during import.

func WithShortcodeService added in v0.2.0 

func WithShortcodeService(svc interfaces.ShortcodeService) ServiceOption

WithShortcodeService wires the shortcode renderer used during parsing.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.