section

Documentation

Overview

Package section builds topic indexes and section pages for journal site navigation.

Index

• func BuildKeyFileIndex(entries []entity.JournalEntry) []entity.KeyFileData
• func BuildTopicIndex(entries []entity.JournalEntry) []entity.TopicData
• func BuildTypeIndex(entries []entity.JournalEntry) []entity.TypeData
• func ContinuesMultipart(filename string) bool
• func GenerateGroupedPage(heading, stats string, entries []entity.JournalEntry) string
• func GenerateKeyFilePage(kf entity.KeyFileData) string
• func GenerateKeyFilesIndex(keyFiles []entity.KeyFileData) string
• func GenerateTopicPage(topic entity.TopicData) string
• func GenerateTopicsIndex(topics []entity.TopicData) string
• func GenerateTypePage(st entity.TypeData) string
• func GenerateTypesIndex(sessionTypes []entity.TypeData) string
• func WriteFormattedSection[T any](sb *strings.Builder, headingKey string, items []T, formatFn func(T) string)
• func WriteMonthSections(sb *strings.Builder, months map[string][]entity.JournalEntry, ...)
• func WritePopularAndLongtail(sb *strings.Builder, popCount int, popHeading string, ...)
• func WriteSection(docsDir, subdir, indexContent string, writePages func(dir string)) error

Functions

func BuildKeyFileIndex

func BuildKeyFileIndex(entries []entity.JournalEntry) []entity.KeyFileData

BuildKeyFileIndex aggregates entries by key file path.

Files with 2+ sessions are marked popular. Sorted by count desc, then path.

Parameters:

• entries: All journal entries to aggregate

Returns:

• []KeyFileData: Key files sorted by session count descending, then path

func BuildTopicIndex

func BuildTopicIndex(entries []entity.JournalEntry) []entity.TopicData

BuildTopicIndex aggregates entries by topic and returns sorted topic data.

Topics with 2+ sessions are marked popular. Sorted by count desc, then alpha.

Parameters:

• entries: All journal entries to aggregate

Returns:

• []TopicData: Topics sorted by session count descending, then name

func BuildTypeIndex

func BuildTypeIndex(entries []entity.JournalEntry) []entity.TypeData

BuildTypeIndex aggregates entries by session type.

Sorted by count descending, then name alphabetically.

Parameters:

• entries: All journal entries to aggregate

Returns:

• []TypeData: Session types sorted by count descending, then name

func ContinuesMultipart

func ContinuesMultipart(filename string) bool

ContinuesMultipart reports whether the filename is a continuation part (p2, p3, etc.) of a multipart session.

Parameters:

• filename: Journal entry filename to check

Returns:

• bool: True if the filename matches the multipart continuation pattern

func GenerateGroupedPage

func GenerateGroupedPage(heading, stats string, entries []entity.JournalEntry) string

GenerateGroupedPage builds a detail page with a heading, stats line, and month-grouped session links. Used by topic, key file, and type pages.

Parameters:

• heading: Pre-formatted Markdown heading (e.g., "# refactoring")
• stats: Pre-formatted stats line (e.g., "**5 sessions** with this topic.")
• entries: Journal entries to group by month

Returns:

• string: Complete Markdown page content

func GenerateKeyFilePage

func GenerateKeyFilePage(kf entity.KeyFileData) string

GenerateKeyFilePage creates an individual key file page with sessions grouped by month.

Parameters:

• kf: Key file data including the path and entries

Returns:

• string: Markdown content for the key file page

func GenerateKeyFilesIndex

func GenerateKeyFilesIndex(keyFiles []entity.KeyFileData) string

GenerateKeyFilesIndex creates the files/index.md page.

Frequently touched files link to dedicated pages; single-session files list entries inline.

Parameters:

• keyFiles: Sorted key file data from BuildKeyFileIndex

Returns:

• string: Markdown content for files/index.md

func GenerateTopicPage

func GenerateTopicPage(topic entity.TopicData) string

GenerateTopicPage creates an individual topic page with sessions grouped by month.

Parameters:

• topic: Topic data including name and entries

Returns:

• string: Markdown content for the topic page

func GenerateTopicsIndex

func GenerateTopicsIndex(topics []entity.TopicData) string

GenerateTopicsIndex creates the topics/index.md page.

Popular topics link to dedicated pages; long-tail topics list entries inline.

Parameters:

• topics: Sorted topic data from BuildTopicIndex

Returns:

• string: Markdown content for topics/index.md

func GenerateTypePage

func GenerateTypePage(st entity.TypeData) string

GenerateTypePage creates an individual session type page with sessions grouped by month.

Parameters:

• st: Type data including name and entries

Returns:

• string: Markdown content for the session type page

func GenerateTypesIndex

func GenerateTypesIndex(sessionTypes []entity.TypeData) string

GenerateTypesIndex creates the types/index.md page.

Parameters:

• sessionTypes: Sorted type data from BuildTypeIndex

Returns:

• string: Markdown content for types/index.md

func WriteFormattedSection

func WriteFormattedSection[T any](sb *strings.Builder, headingKey string, items []T, formatFn func(T) string)

WriteFormattedSection writes a headed list section to sb if items is non-empty.

Parameters:

• sb: String builder to write to
• headingKey: YAML DescKey for the section heading
• items: Slice of items to render
• formatFn: Function that renders one item as a string

func WriteMonthSections

func WriteMonthSections(
	sb *strings.Builder,
	months map[string][]entity.JournalEntry,
	monthOrder []string, linkPrefix string,
)

WriteMonthSections writes month-grouped entry links to a string builder.

Parameters:

• sb: String builder to write to
• months: Entries keyed by month string (YYYY-MM)
• monthOrder: Month strings in display order
• linkPrefix: Path prefix for links (e.g., config.LinkPrefixParent for subpages, "" for index)

func WritePopularAndLongtail

func WritePopularAndLongtail(
	sb *strings.Builder,
	popCount int, popHeading string,
	popItem func(int) (string, string, int),
	ltCount int, ltHeading, ltTpl string,
	ltItem func(int) (string, entity.JournalEntry),
)

WritePopularAndLongtail writes the popular and longtail sections of an index page. Popular items link to dedicated pages; longtail items show inline links to the first matching session.

Parameters:

• sb: String builder to write to
• popCount: Number of popular items
• popHeading: Section heading for popular items
• popItem: Returns label, slug, and entry count for popular item at index i
• ltCount: Number of longtail items
• ltHeading: Section heading for longtail items
• ltTpl: Format template for longtail entries
• ltItem: Returns label and first entry for longtail item at index i

func WriteSection

func WriteSection(
	docsDir, subdir, indexContent string,
	writePages func(dir string),
) error

WriteSection creates a subdirectory, writes its index page, and calls writePages to emit individual pages. All three index sections (topics, files, types) follow this identical structure.

Parameters:

• docsDir: Parent docs directory
• subdir: Subdirectory name (e.g., config.JournalDirTopics)
• indexContent: Generated Markdown for the index page
• writePages: Callback that writes individual pages into the subdirectory

Returns:

• error: Non-nil if directory creation or index write fails