Documentation
¶
Overview ¶
bookjson.go provides GitBook book.json compatibility for mdPress. It parses a GitBook-style book.json file and converts it to a BookConfig.
Package config loads and validates mdpress configuration. It reads book metadata, chapter definitions, style settings, and output options from book.yaml.
discover.go implements zero-config project discovery. When neither book.yaml nor SUMMARY.md exists, mdpress scans .md files, sorts them, and derives chapter metadata automatically.
summary.go parses chapter structure from SUMMARY.md. SUMMARY.md uses Markdown link lists to define chapter order in a GitBook-compatible format.
Format example:
# Summary * [Preface](preface.md) * [Chapter 1](chapter01/README.md) * [Section 1.1](chapter01/section01.md) * [Chapter 2](chapter02/README.md)
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsValidPageSize ¶ added in v0.7.0
IsValidPageSize reports whether s is a recognized page size name (case-insensitive).
Types ¶
type BookConfig ¶
type BookConfig struct {
Book BookMeta `yaml:"book"`
Chapters []ChapterDef `yaml:"chapters"`
Style StyleConfig `yaml:"style"`
Output OutputConfig `yaml:"output"`
// Plugins lists the plugins to run during the build, in declaration order.
Plugins []PluginConfig `yaml:"plugins"`
// These fields are auto-detected by Load instead of being set directly in YAML.
GlossaryFile string `yaml:"-"` // Path to GLOSSARY.md, if present.
LangsFile string `yaml:"-"` // Path to LANGS.md, if present.
// contains filtered or unexported fields
}
BookConfig is the top-level configuration for a book.
func DefaultConfig ¶
func DefaultConfig() *BookConfig
DefaultConfig returns a config populated with reasonable defaults.
func Discover ¶
func Discover(ctx context.Context, dir string) (*BookConfig, error)
Discover auto-discovers project configuration in a directory. Priority: book.yaml > book.json (GitBook compat) > SUMMARY.md > Markdown file scanning. The context is used for potentially long-running operations like git commands.
func Load ¶
func Load(path string) (*BookConfig, error)
Load reads a config file from disk. If chapters are empty, it attempts to load them from SUMMARY.md in the same directory. It also auto-detects GLOSSARY.md and LANGS.md.
func LoadBookJSON ¶ added in v0.3.1
func LoadBookJSON(ctx context.Context, path string) (*BookConfig, error)
LoadBookJSON reads a GitBook book.json file and returns an equivalent BookConfig.
Metadata fields (title, author, description, language, plugins) are loaded from book.json. Chapter definitions are NOT loaded here; instead, Discover() handles chapters via SUMMARY.md or auto-discovery, which allows proper priority orchestration of configuration sources. The context is used for potentially long-running operations like git commands.
func (*BookConfig) BaseDir ¶
func (c *BookConfig) BaseDir() string
BaseDir returns the directory containing the config file.
func (*BookConfig) ResolvePath ¶
func (c *BookConfig) ResolvePath(p string) string
ResolvePath resolves a path relative to the config directory.
func (*BookConfig) SetBaseDir ¶
func (c *BookConfig) SetBaseDir(dir string)
SetBaseDir overrides the base directory used to resolve relative paths. It is primarily useful for tests and for constructing configs in memory.
func (*BookConfig) Validate ¶
func (c *BookConfig) Validate() error
Validate checks the configuration for completeness and validity.
type BookMeta ¶
type BookMeta struct {
Title string `yaml:"title"`
Subtitle string `yaml:"subtitle"`
Author string `yaml:"author"`
Version string `yaml:"version"`
Language string `yaml:"language"`
Description string `yaml:"description"`
Cover CoverMeta `yaml:"cover"`
}
BookMeta contains book metadata.
type ChapterDef ¶
type ChapterDef struct {
Title string `yaml:"title"`
File string `yaml:"file"`
Sections []ChapterDef `yaml:"sections"`
}
ChapterDef defines a chapter and its nested sections.
func FlattenChapters ¶
func FlattenChapters(chapters []ChapterDef) []ChapterDef
FlattenChapters expands nested chapter definitions into a flat list. This is the canonical implementation; callers should use this instead of maintaining their own flattening logic.
func ParseSummary ¶
func ParseSummary(path string) ([]ChapterDef, error)
ParseSummary parses chapter definitions from SUMMARY.md. Nesting is expressed with indentation: two spaces or one tab per level.
type CoverMeta ¶
type CoverMeta struct {
Image string `yaml:"image"`
Background string `yaml:"background"` // Background color, for example "#1a1a2e".
}
CoverMeta stores cover configuration.
type DiscoverError ¶
DiscoverError describes auto-discovery failures.
func (*DiscoverError) Error ¶
func (e *DiscoverError) Error() string
type HeaderFooterStyle ¶
type HeaderFooterStyle struct {
}
HeaderFooterStyle stores header and footer text templates.
type MarginConfig ¶
type MarginConfig struct {
Top float64 `yaml:"top"`
Bottom float64 `yaml:"bottom"`
Left float64 `yaml:"left"`
Right float64 `yaml:"right"`
}
MarginConfig stores page margins in millimeters.
type OutputConfig ¶
type OutputConfig struct {
Filename string `yaml:"filename"`
TOC bool `yaml:"toc"`
TOCMaxDepth int `yaml:"toc_max_depth"` // Maximum heading level to include in TOC (1-6, default 2). Level 1 = h1 only, 2 = h1+h2, etc.
Cover bool `yaml:"cover"`
Header bool `yaml:"header"`
Formats []string `yaml:"formats"` // Output formats: pdf, html, epub, site (default ["pdf"]).
PDFTimeout int `yaml:"pdf_timeout"` // PDF generation timeout in seconds (default 120).
Watermark string `yaml:"watermark"` // Watermark text (e.g., "DRAFT", "CONFIDENTIAL")
WatermarkOpacity float64 `yaml:"watermark_opacity"` // Opacity 0.0-1.0 (default 0.1)
MarginTop string `yaml:"margin_top"` // e.g., "20mm" (default "15mm")
MarginBottom string `yaml:"margin_bottom"` // e.g., "20mm" (default "15mm")
MarginLeft string `yaml:"margin_left"` // e.g., "25mm" (default "20mm")
MarginRight string `yaml:"margin_right"` // e.g., "25mm" (default "20mm")
GenerateBookmarks bool `yaml:"generate_bookmarks"` // Generate PDF bookmarks from headings (default true)
}
OutputConfig stores output-related settings.
type PluginConfig ¶ added in v0.3.0
type PluginConfig struct {
// Name is the unique plugin identifier (lowercase, hyphen-separated).
Name string `yaml:"name"`
// Path is the path to the plugin executable, relative to book.yaml.
Path string `yaml:"path"`
// Config contains arbitrary key-value pairs passed to the plugin.
Config map[string]any `yaml:"config"`
}
PluginConfig describes a single plugin entry in book.yaml.
Example:
plugins:
- name: word-count
path: ./plugins/word-count
config:
warn_threshold: 500
type ReadmeMetadata ¶ added in v0.3.1
type ReadmeMetadata struct {
Title string // Book title (may differ from H1 heading).
Version string // e.g. "1.6.5"
Author string // Detected author name or GitHub username.
Language string // e.g. "zh-CN", "en-US"
}
ReadmeMetadata holds metadata extracted from a project README.md.
func ExtractReadmeMetadata ¶ added in v0.3.1
func ExtractReadmeMetadata(ctx context.Context, path string) ReadmeMetadata
ExtractReadmeMetadata reads a README.md and extracts book metadata. It tries to find a meaningful title (beyond just the H1), version, language, and author. Exported so that cmd/init_cmd.go can also use it. The context is used for potentially long-running operations like git commands.
type StyleConfig ¶
type StyleConfig struct {
Theme string `yaml:"theme"`
PageSize string `yaml:"page_size"`
FontFamily string `yaml:"font_family"`
FontSize string `yaml:"font_size"`
CodeTheme string `yaml:"code_theme"`
LineHeight float64 `yaml:"line_height"`
Margin MarginConfig `yaml:"margin"`
Header HeaderFooterStyle `yaml:"header"`
CustomCSS string `yaml:"custom_css"`
}
StyleConfig stores style-related settings.
Source Files