From 46c3db133bbe94521148683a0adda940c52bfa22 Mon Sep 17 00:00:00 2001 From: Virgil Date: Thu, 19 Feb 2026 16:57:06 +0000 Subject: [PATCH] Delete page "Topics-and-Catalog.-" --- Topics-and-Catalog.-.md | 174 ---------------------------------------- 1 file changed, 174 deletions(-) delete mode 100644 Topics-and-Catalog.-.md diff --git a/Topics-and-Catalog.-.md b/Topics-and-Catalog.-.md deleted file mode 100644 index ef75795..0000000 --- a/Topics-and-Catalog.-.md +++ /dev/null @@ -1,174 +0,0 @@ -# Topics and Catalog - -The help system is built around `Topic` structs managed by a `Catalog`. Topics can be created programmatically or parsed from markdown files with YAML frontmatter. - -## Topic Struct - -```go -type Topic struct { - ID string `json:"id"` - Title string `json:"title"` - Path string `json:"path"` - Content string `json:"content"` - Sections []Section `json:"sections"` - Tags []string `json:"tags"` - Related []string `json:"related"` - Order int `json:"order"` -} -``` - -| Field | Description | -|-------|-------------| -| `ID` | URL-safe identifier, auto-generated from title (e.g. `"getting-started"`) | -| `Title` | Human-readable title | -| `Path` | Source file path (set by `ParseTopic`) | -| `Content` | Markdown body (without frontmatter) | -| `Sections` | Headings extracted from the content | -| `Tags` | Searchable tags from frontmatter | -| `Related` | IDs of related topics from frontmatter | -| `Order` | Sort order from frontmatter | - -## Section Struct - -```go -type Section struct { - ID string `json:"id"` - Title string `json:"title"` - Level int `json:"level"` - Line int `json:"line"` - Content string `json:"content"` -} -``` - -| Field | Description | -|-------|-------------| -| `ID` | URL-safe identifier generated from the heading text | -| `Title` | The heading text | -| `Level` | Heading level: 1 for `#`, 2 for `##`, up to 6 for `######` | -| `Line` | 1-indexed line number where the heading appears | -| `Content` | Text between this heading and the next heading (trimmed) | - -## Frontmatter - -Topics parsed from markdown can include YAML frontmatter delimited by `---`: - -```go -type Frontmatter struct { - Title string `yaml:"title"` - Tags []string `yaml:"tags"` - Related []string `yaml:"related"` - Order int `yaml:"order"` -} -``` - -Example markdown file: - -```markdown ---- -title: Quick Start Guide -tags: [intro, quickstart] -order: 5 -related: - - installation - - configuration ---- - -# Quick Start Guide - -Welcome to the guide. - -## First Steps - -Do this first. -``` - -The parser supports both LF and CRLF line endings. Empty frontmatter blocks (`--- ----`) parse successfully with zero values. Invalid YAML in frontmatter is silently ignored and the content is returned as-is. - -## ParseTopic - -```go -func ParseTopic(path string, content []byte) (*Topic, error) -``` - -Parses a markdown file into a `Topic`. Title resolution order: - -1. `title` field from YAML frontmatter -2. First H1 heading in the content -3. No title (ID derived from file path) - -The `ID` is generated from the resolved title using `GenerateID`. If no title is found, the ID is derived from the filename (e.g. `"commands/dev-workflow.md"` becomes `"dev-workflow"`). - -```go -content, _ := os.ReadFile("docs/quick-start.md") -topic, err := help.ParseTopic("docs/quick-start.md", content) -``` - -## GenerateID - -```go -func GenerateID(title string) string -``` - -Converts a title to a URL-safe ID: lowercase, spaces/underscores replaced with hyphens, special characters stripped, trailing hyphens trimmed. Supports unicode letters. - -| Input | Output | -|-------|--------| -| `"Getting Started"` | `"getting-started"` | -| `"What's New? (v2.0)"` | `"whats-new-v20"` | -| `"config_file_reference"` | `"config-file-reference"` | - -## Catalog - -The `Catalog` manages a collection of topics with an integrated search index. - -### DefaultCatalog - -```go -func DefaultCatalog() *Catalog -``` - -Returns a catalog pre-loaded with two built-in topics: -- **getting-started** — Common commands (`core dev`, `core setup`, `core doctor`, `core test`) and next steps. -- **config** — Environment variables (`CORE_DEBUG`, `GITHUB_TOKEN`) and config file location (`~/.core/config.yaml`). - -### Add - -```go -func (c *Catalog) Add(t *Topic) -``` - -Adds a topic to the catalog and indexes it for search. If a topic with the same ID already exists, it is replaced. - -### List - -```go -func (c *Catalog) List() []*Topic -``` - -Returns all topics in the catalog. Order is not guaranteed (map iteration). - -### Get - -```go -func (c *Catalog) Get(id string) (*Topic, error) -``` - -Returns a topic by ID. Returns an error if the topic is not found. - -```go -topic, err := catalog.Get("getting-started") -if err != nil { - fmt.Println(err) // "topic not found: getting-started" -} -``` - -### Search - -```go -func (c *Catalog) Search(query string) []*SearchResult -``` - -Delegates to the search engine. See [[Search-Engine]] for details on scoring and snippets. - -Back to [[Home]].