model

Documentation

Index

• type Article
• type BuildConfig
• type BuildManifest
• type ChangeSet
• type Config
• type DependencyGraph
• type DevServer
• type FileWatcher
• type FrontMatter
• type I18nConfig
• type LocaleRef
• type Node
• type NodeType
• type OGPConfig
• type OutputFile
• type Pagination
• type ProcessedArticle
• type Site
• type SiteConfig
• type SyntaxHighlightConfig
• type Taxonomy
• type TaxonomyRegistry
• type ThemeConfig
• type VirtualPage

Types

type Article

type Article struct {
	FrontMatter  FrontMatter
	RawContent   string
	FilePath     string
	LastModified time.Time
}

Article is the raw data parsed from a Markdown file.

type BuildConfig

type BuildConfig struct {
	ContentDir   string   `yaml:"content_dir"`
	OutputDir    string   `yaml:"output_dir"`
	AssetsDir    string   `yaml:"assets_dir"`
	StaticDir    string   `yaml:"static_dir"`
	ExcludeFiles []string `yaml:"exclude_files"`
	Parallelism  int      `yaml:"parallelism"`
	PerPage      int      `yaml:"per_page"`
}

BuildConfig holds build-time directory and parallelism settings.

type BuildManifest

type BuildManifest struct {
	Version      string              `json:"version"`
	BuildTime    time.Time           `json:"build_time"`
	LastCommit   string              `json:"last_commit"`
	FileHashes   map[string]string   `json:"file_hashes"`
	Dependencies map[string][]string `json:"dependencies"`
	OutputFiles  []OutputFile        `json:"output_files"`
}

BuildManifest is the build history persisted to .gohan/cache/manifest.json.

type ChangeSet

type ChangeSet struct {
	ModifiedFiles []string
	AddedFiles    []string
	DeletedFiles  []string
}

ChangeSet holds the result of diff detection between two builds.

type Config

type Config struct {
	Site            SiteConfig             `yaml:"site"`
	Build           BuildConfig            `yaml:"build"`
	Theme           ThemeConfig            `yaml:"theme"`
	SyntaxHighlight SyntaxHighlightConfig  `yaml:"syntax_highlight"`
	OGP             OGPConfig              `yaml:"ogp"`
	Plugins         map[string]interface{} `yaml:"plugins"`
	I18n            I18nConfig             `yaml:"i18n"`
}

Config is the top-level structure of config.yaml.

type DependencyGraph

type DependencyGraph struct {
	Nodes map[string]*Node
	Edges map[string][]string
}

DependencyGraph is a directed graph of content dependencies.

type DevServer

type DevServer struct {
	Host    string
	Port    int
	OutDir  string
	Watcher FileWatcher
}

DevServer is the local HTTP development server configuration.

type FileWatcher

type FileWatcher interface {
	Add(path string) error
	Events() <-chan string
	Close() error
}

FileWatcher is the interface for watching file system changes.

type FrontMatter

type FrontMatter struct {
	Title       string    `yaml:"title"`
	Date        time.Time `yaml:"date"`
	LastMod     time.Time `yaml:"lastmod"`
	Draft       bool      `yaml:"draft"`
	Tags        []string  `yaml:"tags"`
	Categories  []string  `yaml:"categories"`
	Description string    `yaml:"description"`
	Author      string    `yaml:"author"`
	Slug        string    `yaml:"slug"`
	Template    string    `yaml:"template"`
	// TranslationKey links this article to its translations in other locales.
	// Articles sharing the same key are treated as translations of each other,
	// enabling language-switcher links via ProcessedArticle.Translations.
	TranslationKey string `yaml:"translation_key"`
	// Extra captures any front-matter keys not listed above.
	// Plugins read their configuration from this field.
	Extra map[string]interface{} `yaml:",inline"`
}

FrontMatter holds the YAML metadata from the top of a Markdown file.

type I18nConfig

type I18nConfig struct {
	// Locales is the ordered list of locale codes present under the content
	// directory (e.g. ["en", "ja"]). When empty, i18n is disabled and gohan
	// behaves as a single-language site with no URL changes.
	Locales []string `yaml:"locales"`
	// DefaultLocale is the locale code served at the root URL (without a
	// language prefix). Defaults to Site.Language when Locales is non-empty.
	// Example: if DefaultLocale is "en", /posts/hello/ is English and
	// /ja/posts/hello/ is Japanese.
	DefaultLocale string `yaml:"default_locale"`
}

I18nConfig holds multi-language content configuration.

type LocaleRef

type LocaleRef struct {
	Locale string
	URL    string
}

LocaleRef holds a locale code and the canonical URL for a translated variant of an article. Used to generate language-switcher links in templates.

type Node

type Node struct {
	Path         string
	Type         NodeType
	Dependencies []string
	Dependents   []string
	LastModified time.Time
}

Node is a vertex in the dependency graph.

type NodeType

type NodeType int

NodeType classifies a node in the dependency graph.

const (
	NodeTypeArticle NodeType = iota
	NodeTypeTag
	NodeTypeCategory
	NodeTypeArchive
	NodeTypePage
)

type OGPConfig

type OGPConfig struct {
	Enabled  bool   `yaml:"enabled"`
	LogoFile string `yaml:"logo_file"` // empty means no logo
	Width    int    `yaml:"width"`
	Height   int    `yaml:"height"`
}

OGPConfig holds settings for build-time OGP image generation.

type OutputFile

type OutputFile struct {
	Path         string    `json:"path"`
	Hash         string    `json:"hash"`
	Size         int64     `json:"size"`
	LastModified time.Time `json:"last_modified"`
	ContentType  string    `json:"content_type"`
}

OutputFile records metadata for a single generated file.

type Pagination

type Pagination struct {
	CurrentPage int
	TotalPages  int
	PerPage     int
	TotalItems  int
	PrevURL     string // empty string if no previous page
	NextURL     string // empty string if no next page
	BaseURL     string // URL path prefix used to construct PrevURL/NextURL (e.g. "/tags/go")
}

Pagination holds computed paging metadata for listing pages.

type ProcessedArticle

type ProcessedArticle struct {
	Article
	HTMLContent template.HTML
	Summary     string
	OutputPath  string
	// ContentPath is the content-dir-relative path to the source Markdown file
	// (e.g. "posts/hello-world.md"). Used to generate GitHub edit/view links.
	ContentPath string
	// Locale is the locale code detected from the content path (e.g. "en", "ja").
	// Empty when i18n is not configured.
	Locale string
	// URL is the canonical URL path for this article (e.g. "/posts/hello/" or
	// "/ja/posts/hello/"). Empty when i18n is not configured.
	URL string
	// Translations lists translated variants of this article, keyed by locale.
	// Populated by BuildTranslationMap after article processing.
	Translations []LocaleRef
	// PluginData holds per-article data injected by enabled plugins.
	// Access in templates: {{index .PluginData "amazon_books"}}
	PluginData map[string]interface{}
}

ProcessedArticle holds derived data generated by the renderer.

type Site

type Site struct {
	Config                Config
	Articles              []*ProcessedArticle
	Tags                  []Taxonomy
	Categories            []Taxonomy
	ArchiveYears          []int               // unique years that have articles, sorted newest-first
	Pagination            *Pagination         // nil when pagination is disabled or not a listing page
	CurrentLocale         string              // locale for the current page; empty when i18n is not configured
	RelatedArticles       []*ProcessedArticle // articles sharing at least one category with the current article (article pages only)
	CurrentTaxonomy       *Taxonomy           // set on tag and category listing pages; nil elsewhere
	CurrentArchivePath    string              // set on archive pages; locale-aware path e.g. "/archives/2024/01/" or "/ja/archives/2024/01/"
	CurrentArchiveIsMonth bool                // true for month archives (/archives/2024/01/), false for year archives (/archives/2024/)
	// VirtualPages is the list of pages generated by SitePlugins.
	// Populated by plugin.Registry.EnrichVirtual; consumed by the HTML generator.
	// Not included in the Atom feed or index article listing.
	VirtualPages []*VirtualPage
	// VirtualPageData holds per-page data injected by a SitePlugin for the
	// current virtual page being rendered.  Nil for all non-virtual pages.
	// Access in templates: {{.VirtualPageData}}
	VirtualPageData map[string]interface{}
}

Site holds the full rendering context passed to templates.

type SiteConfig

type SiteConfig struct {
	Title       string `yaml:"title"`
	Description string `yaml:"description"`
	BaseURL     string `yaml:"base_url"`
	Language    string `yaml:"language"`
	// GitHubRepo is the base URL of the GitHub repository that holds the site
	// source (e.g. "https://github.com/owner/repo"). When set, templates can
	// render an "Edit this page" link using .ContentPath.
	GitHubRepo string `yaml:"github_repo"`
	// GitHubBranch is the branch used to build the edit URL. Defaults to "main".
	GitHubBranch string `yaml:"github_branch"`
}

SiteConfig holds site-wide metadata.

type SyntaxHighlightConfig

type SyntaxHighlightConfig struct {
	// Theme is a chroma style name (e.g. "github", "monokai", "dracula").
	Theme string `yaml:"theme"`
	// LineNumbers enables line number display when true.
	LineNumbers bool `yaml:"line_numbers"`
}

SyntaxHighlightConfig holds settings for code-block syntax highlighting.

type Taxonomy

type Taxonomy struct {
	Name        string `yaml:"name"`
	Description string `yaml:"description"`
	URL         string `yaml:"-"` // set at render time; locale-aware canonical URL
}

Taxonomy represents a single tag or category entry.

type TaxonomyRegistry

type TaxonomyRegistry struct {
	Tags       []Taxonomy `yaml:"tags"`
	Categories []Taxonomy `yaml:"categories"`
}

TaxonomyRegistry holds the master lists loaded from taxonomy YAML files.

type ThemeConfig

type ThemeConfig struct {
	Name   string            `yaml:"name"`
	Dir    string            `yaml:"dir"`
	Params map[string]string `yaml:"params"`
}

ThemeConfig holds theme name, directory, and custom parameters.

type VirtualPage

type VirtualPage struct {
	// OutputPath is the file path to write relative to the output directory.
	// e.g. "bookshelf/index.html" (default locale) or "ja/bookshelf/index.html"
	OutputPath string

	// URL is the canonical URL path for this page, including trailing slash.
	// e.g. "/bookshelf/" or "/ja/bookshelf/"
	URL string

	// Template is the theme template filename used to render this page.
	// e.g. "bookshelf.html"
	Template string

	// Locale is the locale code for this page (e.g. "en", "ja").
	// Empty when i18n is not configured.
	Locale string

	// Data holds arbitrary page-specific data injected by the SitePlugin.
	// Accessible in templates via .VirtualPageData.
	Data map[string]interface{}
}

VirtualPage represents a generated page that does not correspond to a Markdown source file. It is produced by SitePlugins during the build pipeline and rendered by the HTML generator using a named template.

Example: the bookshelf plugin emits one VirtualPage per locale containing all book entries aggregated from every article's front-matter.