book

Documentation

Overview

Package book assembles Markdown manuscripts into book-shaped websites using the Runvil web framework. A manuscript is a directory of ordered Markdown files and subdirectories; the builder renders it into pages and assets that can be exported to disk or served over HTTP.

Index

• func Assets() map[string]string
• func Build(cfg Config) ([]string, error)
• func Serve(b *Book, addr string) error
• type Book
  • func Load(input, title, author string) (*Book, error)
  • func LoadWithBase(input, title, author, base string) (*Book, error)
  • func (b *Book) Handler() (*web.Router, error)
  • func (b *Book) Pages() ([]web.Page, error)
  • func (b *Book) WithChrome(nav []Link, footer string) *Book
  • func (b *Book) WithTheme(t *ui.Theme) *Book
• type Chapter
  • func (c Chapter) Label() string
  • func (c Chapter) Path() string
• type Config
• type Link

Functions

func Assets

func Assets() map[string]string

Assets returns the site's shipped assets: name to file body. The theme-mode variables and toggle button styles come from the ui framework and are appended to the reader stylesheet so consumers never hardcode them.

func Build

func Build(cfg Config) ([]string, error)

Build renders the manuscript in cfg.Input into a static website in cfg.Output and returns the list of created paths, sorted for determinism.

func Serve

func Serve(b *Book, addr string) error

Serve serves the book over HTTP on addr, blocking until the server stops.

Types

type Book

type Book struct {
	// Title is the book title.
	Title string
	// Author is the book author.
	Author string
	// Chapters holds the top-level chapters in reading order.
	Chapters []Chapter
	// contains filtered or unexported fields
}

Book is a manuscript, loaded into an ordered set of chapters.

func Load

func Load(input, title, author string) (*Book, error)

Load reads a manuscript directory into a Book in reading order, served from the site root.

func LoadWithBase

func LoadWithBase(input, title, author, base string) (*Book, error)

LoadWithBase reads a manuscript directory into a Book in reading order. Top level Markdown files become chapters; a directory becomes a chapter whose subchapters are the Markdown files inside it, ordered by numeric prefix. An index.md or _index.md inside a directory becomes the chapter page body; without one, the chapter page lists its subchapters automatically. The base is the URL prefix the site will be served under, e.g. "/guide/".

func (*Book) Handler

func (b *Book) Handler() (*web.Router, error)

Handler returns an http.Handler that serves the book's pages and assets through the web router.

func (*Book) Pages

func (b *Book) Pages() ([]web.Page, error)

Pages builds the site's web.Page tree: the root landing page and one page per chapter. Exported page paths are always root-relative; only the links emitted into the rendered HTML carry the book's base path.

func (*Book) WithChrome

func (b *Book) WithChrome(nav []Link, footer string) *Book

WithChrome sets the book's navigation chrome: optional navbar links and footer text. Returns the Book for chaining.

func (*Book) WithTheme

func (b *Book) WithTheme(t *ui.Theme) *Book

WithTheme enables the light/dark theme switcher. Returns the Book for chaining.

type Chapter

type Chapter struct {
	// Number is the 1-based reading order index of the top-level chapter.
	Number int
	// Sub is the 1-based subchapter index within the parent chapter, or 0 for
	// a top-level chapter.
	Sub int
	// Slug is the URL-safe identifier derived from the filename.
	Slug string
	// Title is the chapter title derived from the first H1 heading or slug.
	Title string
	// Body is the rendered HTML body.
	Body template.HTML
	// Prev and Next point to adjacent pages in reading order.
	Prev *Chapter
	Next *Chapter
	// Subs holds the chapter's subchapters in reading order; empty for a
	// plain chapter.
	Subs []*Chapter
	// Parent points to the containing chapter, or nil for top-level chapters.
	Parent *Chapter
}

Chapter is one manuscript unit, named by its slug and rendered from Markdown. A chapter with subchapters mirrors a part of a physical book: the chapter page leads, and its Subs follow as "N.M" subchapters.

func (Chapter) Label

func (c Chapter) Label() string

Label returns the numeric label shown in the table of contents: "7" for a top-level chapter and "7.1" for a subchapter.

func (Chapter) Path

func (c Chapter) Path() string

Path returns the chapter page URL: /chapters/{slug}/ for top-level chapters, /chapters/{parent}/{slug}/ for subchapters.

type Config

type Config struct {
	// Title is the book title.
	Title string
	// Author is the book author.
	Author string
	// Input is the manuscript directory.
	Input string
	// Output is the destination directory for the exported site.
	Output string
	// BasePath is the URL base the site will be served under, e.g. "/guide/".
	// Generated links and asset references are prefixed accordingly. Defaults
	// to "/".
	BasePath string
	// NavLinks are optional extra links rendered in the navbar.
	NavLinks []Link
	// FooterText is optional text shown in the footer; when empty the footer
	// shows the author copyright instead.
	FooterText string
	// Theme, when non-nil, enables the light/dark theme switcher on every page.
	Theme *ui.Theme
}

Config configures a build.

type Link

type Link struct {
	Text string
	URL  string
}

Link is a named navigation target shown in the navbar.