Delete page "Topics-and-Catalog.-"
parent
46fd1262ab
commit
46c3db133b
1 changed files with 0 additions and 174 deletions
|
|
@ -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]].
|
||||
Loading…
Add table
Reference in a new issue