go-help

forge.lthn.ai/core/go-help -- Help catalogue with YAML topics and full-text search.

Provides a display-agnostic help system for CLI applications. Topics are defined as Markdown files with optional YAML frontmatter. The built-in search engine supports word tokenisation, prefix matching, title boosting, and snippet extraction with highlighting.

Installation

go get forge.lthn.ai/core/go-help@latest

Dependencies: gopkg.in/yaml.v3

Core Types

// Topic represents a help topic/page.
type Topic struct {
    ID       string    // URL-safe slug ("getting-started")
    Title    string    // Display title ("Getting Started")
    Path     string    // Source file path
    Content  string    // Markdown body (without frontmatter)
    Sections []Section // Parsed headings
    Tags     []string  // Searchable tags
    Related  []string  // Related topic IDs
    Order    int       // Sort order
}

// Section represents a heading within a topic.
type Section struct {
    ID      string // URL-safe slug
    Title   string // Heading text
    Level   int    // 1-6
    Line    int    // Start line (1-indexed)
    Content string // Text under the heading
}

Quick Start

package main

import (
    "fmt"
    "log"

    "forge.lthn.ai/core/go-help"
)

func main() {
    // Use the built-in catalogue
    cat := help.DefaultCatalog()

    // Add a custom topic
    cat.Add(&help.Topic{
        ID:      "deployment",
        Title:   "Deployment",
        Content: "# Deployment\n\nHow to deploy the application...",
        Tags:    []string{"ops", "docker"},
    })

    // List all topics
    for _, t := range cat.List() {
        fmt.Printf("  %s -- %s\n", t.ID, t.Title)
    }

    // Search
    results := cat.Search("deploy docker")
    for _, r := range results {
        fmt.Printf("  [%.1f] %s: %s\n", r.Score, r.Topic.Title, r.Snippet)
    }
}

API Summary

Function / Method	Description
`DefaultCatalog()`	Create a catalogue with built-in topics
`Catalog.Add(topic)`	Add a topic to the catalogue and search index
`Catalog.Get(id)`	Retrieve a topic by ID
`Catalog.List()`	List all topics
`Catalog.Search(query)`	Full-text search across all topics
`ParseTopic(path, content)`	Parse a Markdown file into a `*Topic`
`ExtractFrontmatter(content)`	Extract YAML frontmatter from Markdown
`ExtractSections(content)`	Parse headings into `[]Section`
`GenerateID(title)`	Convert a title to a URL-safe slug

Licence

EUPL-1.2