Wiki Server

The wikiserver package is a standalone documentation server that renders the project's Markdown wiki files as a browsable web interface. It was extracted from the main codebase into its own package in April 2026 (commits 8dc4d516, 632d79d3, 6f46b279) and has since received enhanced features including search, TOC, theme toggle, share links, version history, 404 handling, and a loading skeleton (commit f187e7b8), plus critical bug fixes for navigation tree traversal, version history sorting, and XSS escaping (commit cfc7384f).

Recent Bug Fixes (April 25, 2026)

Critical Bugs Fixed (commit 40a31627)

• 404 Panic: Added nil checks to prevent panics when handling non-existent pages
• Nil Pointer: Fixed nil pointer dereference in navigation cache initialization
• Nav Caching: Implemented proper caching with invalidation on file changes
• .md Link Handling: Fixed relative path handling for internal wiki links

Navigation Fixes (commit 7d96b693)

• Fixed index-based range bug in addToTree() that prevented proper nested directory structure
• Restored proper sidebar navigation for nested wiki directories

Static Asset Path (commit 5ef270fa)

• Resolved static asset path mismatch causing missing CSS/JS files

TOC ReferenceError & Favicon (commit 740fb2c6)

• Fixed JavaScript ReferenceError in Table of Contents generation
• Added favicon for wiki branding

Architecture

graph TD
    A[StartWikiServer] --> B[WikiServer struct]
    B --> C[MarkdownRenderer]
    B --> D[NavigationGenerator]
    B --> E[Static File Server]

    C --> C1[goldmark engine]
    C1 --> C2[GFM extension]
    C1 --> C3[Footnote / Table / Strikethrough / Linkify]
    C1 --> C4[monokai syntax highlighting]

    D --> D1[filepath.Walk]
    D1 --> D2[NavigationNode tree]
    D2 --> D3[JSON API /api/navigation]

    E --> E1[/static/wiki/css/]
    E --> E2[/static/wiki/js/]

Port

Key Components

WikiServer Struct

The central struct holding all dependencies:

type WikiServer struct {
    renderer   *MarkdownRenderer
    nav        *NavigationGenerator
    wikiPath   string
    staticPath string
}

• wikiPath: Root directory containing .md files (defaults to wiki/ relative to working directory)
• staticPath: CSS/JS assets served from wikiserver/static/

MarkdownRenderer

Renders .md files to HTML using the goldmark library with a rich extension set:

NavigationGenerator

Builds a tree of NavigationNode structs from the wiki directory structure, served as JSON at /api/navigation for the sidebar JavaScript to consume.

type NavigationNode struct {
    Title    string            `json:"title"`
    Path     string            `json:"path"`
    Children []NavigationNode  `json:"children,omitempty"`
    IsIndex  bool              `json:"is_index"`
}

Navigation tree building (addToTree): Splits the relative file path into directory parts, then walks the tree level-by-level. Uses index-based range addressing (&current.Children[childIdx]) to navigate the actual tree nodes rather than value copies — a critical fix in commit cfc7384f that restored proper nested directory structure in the sidebar.

HTTP Routes

Security

XSS Escaping (commit cfc7384f)

All user-controlled strings injected into HTML templates are escaped via the esc() helper:

func esc(s string) string {
    return template.HTMLEscapeString(s)
}

This covers:

• Page titles
• Breadcrumbs
• File paths in 404 pages
• Version history entries
• Modification dates

Version History

The index page displays the 5 most recently modified wiki files. Entries are sorted by modTime descending (most recent first) using sort.Slice — fixed in commit cfc7384f where previously entries were alphabetically ordered, making the "Recent Updates" section misleading.

type VersionEntry struct {
    Title  string
    Date   string
    modTime time.Time
}

sort.Slice(entries, func(i, j int) bool {
    return entries[i].modTime.After(entries[j].modTime)
})

Key Files

Cross-References

• Web Servers & Port Registry
• Architecture
• Build, Run & Deployment