docs

Documentation

Overview

Package docs provides types and operations for k6 documentation. It supports per-version documentation bundles with lazy loading, HTTP+cache or embedded FS backends, and content transforms.

Index

• func PrepareTransform(content string, sharedContent map[string]string) string
• func SplitFrontmatter(content string) (yamlBlock, body string, ok bool)
• func Transform(content, version string) string
• func VersionWildcard(version string) string
• type Catalog
  • func NewCatalog(opts ...Option) *Catalog
  • func (c *Catalog) Index(ctx context.Context, version string) (*Index, error)
  • func (c *Catalog) Latest() string
  • func (c *Catalog) Read(ctx context.Context, version, slug string) ([]byte, error)
  • func (c *Catalog) ReadFile(ctx context.Context, version, relPath string) ([]byte, error)
  • func (c *Catalog) Versions() []string
• type FS
• type Index
  • func (idx *Index) ByCategory(category string) []*Section
  • func (idx *Index) Children(slug string) []*Section
  • func (idx *Index) Lookup(slug string) (*Section, bool)
  • func (idx *Index) Search(term string, readContent func(slug string) string) []*Section
  • func (idx *Index) TopLevel() []*Section
  • func (idx *Index) Tree(rootSlug string, depth int) iter.Seq2[int, *Tree]
• type Option
  • func WithBundleURL(url string) Option
  • func WithCacheDir(dir string) Option
  • func WithFS(fsys fs.FS) Option
  • func WithHTTPClient(client *http.Client) Option
  • func WithLocalOnly() Option
  • func WithRefreshTimeout(d time.Duration) Option
• type Section
• type Tree
• type WriteDirFS
• type WriteFileFS

Functions

func PrepareTransform

func PrepareTransform(content string, sharedContent map[string]string) string

PrepareTransform resolves docs/shared shortcodes using the shared content map. This runs at bundle build time because shared content files are not shipped in the bundle.

func SplitFrontmatter

func SplitFrontmatter(content string) (yamlBlock, body string, ok bool)

SplitFrontmatter splits content into the YAML block and the body after the closing delimiter. If no valid frontmatter is found, yaml is empty, body is the original content, and ok is false.

func Transform

func Transform(content, version string) string

Transform applies markdown cleanup to content. It handles all pure text transforms (shortcode stripping, admonition conversion, link stripping, frontmatter removal, whitespace normalization). The pipeline runs in a fixed order:

1. Strip code tags
2. Convert admonitions to blockquotes
3. Strip section tags
4. Strip remaining shortcodes 4a. Strip React/MDX component tags (PascalCase) 4b. Strip <br/> tags
5. Replace <K6_VERSION> with version
6. Convert internal docs links to plain text 6a. Strip remaining markdown image links 6b. Strip remaining markdown links
7. Strip HTML comments
8. Strip YAML frontmatter
9. Normalize whitespace

func VersionWildcard

func VersionWildcard(version string) string

VersionWildcard maps a semantic k6 version to the wildcard directory name used for documentation lookups (for example "v1.5.0" becomes "v1.5.x").

Pre-release suffixes (after "-") and build metadata (after "+") are stripped before the replacement. A "v" prefix is added to the result if missing, since k6-docs uses v-prefixed directory names.

An empty input returns an empty string. If the cleaned input has fewer than two dots, the original input is returned unchanged.

Types

type Catalog

type Catalog struct {
	// contains filtered or unexported fields
}

Catalog provides access to per-version documentation bundles.

By default it uses HTTP+cache: downloads bundles from GitHub and caches them locally. Use WithFS for an embedded or test filesystem backend.

func NewCatalog

func NewCatalog(opts ...Option) *Catalog

NewCatalog returns a Catalog. Without options it uses HTTP+cache (on-demand bundle download). Pass WithFS for an embedded FS backend. Versions are discovered lazily on first access.

func (*Catalog) Index

func (c *Catalog) Index(ctx context.Context, version string) (*Index, error)

Index returns the loaded index for version. An empty version resolves to Catalog.Latest. Indexes are cached per resolved version.

func (*Catalog) Latest

func (c *Catalog) Latest() string

Latest returns the newest discovered version, or an empty string if none were found.

func (*Catalog) Read

func (c *Catalog) Read(ctx context.Context, version, slug string) ([]byte, error)

Read returns the markdown content for slug under version. Aliases declared in the section index are resolved transparently.

func (*Catalog) ReadFile

func (c *Catalog) ReadFile(ctx context.Context, version, relPath string) ([]byte, error)

ReadFile returns the raw content of a file at relPath within the version's markdown directory. Unlike Catalog.Read, it does not go through the section index. Use it for files not listed in sections.json (e.g. best_practices.md).

func (*Catalog) Versions

func (c *Catalog) Versions() []string

Versions returns the discovered version directory names sorted latest-first. In HTTP+cache mode, versions are discovered lazily from GitHub + cache scan. The returned slice is a copy and safe to mutate.

type FS

type FS interface {
	fs.ReadFileFS
	fs.StatFS
	fs.ReadDirFS
	WriteFileFS
	WriteDirFS
}

FS composes read and write filesystem operations.

type Index

type Index struct {
	Version  string    `json:"version"`
	Sections []Section `json:"sections"`
	// contains filtered or unexported fields
}

Index holds all sections for a single documentation version.

func (*Index) ByCategory

func (idx *Index) ByCategory(category string) []*Section

ByCategory returns sections whose Category equals category, preserving the order in idx.Sections.

func (*Index) Children

func (idx *Index) Children(slug string) []*Section

Children returns the direct child sections of slug in their stored order. The prepare tool sorts children by weight at build time. Returns nil if slug is unknown.

func (*Index) Lookup

func (idx *Index) Lookup(slug string) (*Section, bool)

Lookup returns the section identified by slug. The lookup is case-insensitive and alias-aware: a slug match wins over an alias match.

func (*Index) Search

func (idx *Index) Search(term string, readContent func(slug string) string) []*Section

Search returns sections whose title, description, slug, or body (via readContent) contain term. Matching is case-insensitive on title and description, and normalized fuzzy (ignoring spaces, dashes, slashes) on title, description, and slug. If readContent is non-nil, the body returned by readContent(slug) is matched the same two ways. Results preserve the order of idx.Sections and contain no duplicates. Returns nil for an empty term.

func (*Index) TopLevel

func (idx *Index) TopLevel() []*Section

TopLevel returns sections where Category == Slug (top-level indices), sorted by weight.

func (*Index) Tree

func (idx *Index) Tree(rootSlug string, depth int) iter.Seq2[int, *Tree]

Tree iterates the section tree rooted at rootSlug, depth-first. When rootSlug is empty, iteration starts at the top-level sections. Otherwise iteration starts at the children of rootSlug; the root itself is not yielded. Each yielded *Tree has its Children populated only down to the requested depth. If depth < 1 or rootSlug is unknown, nothing is yielded.

type Option

type Option func(*Catalog)

Option configures a Catalog.

func WithBundleURL

func WithBundleURL(url string) Option

WithBundleURL overrides the default GitHub bundle download URL.

func WithCacheDir

func WithCacheDir(dir string) Option

WithCacheDir overrides the default cache base directory (~/.local/share/k6/docs). Only used in HTTP+cache mode.

func WithFS

func WithFS(fsys fs.FS) Option

WithFS sets the filesystem backend. The FS must contain per-version bundle directories (for example "v1.7.x/sections.json").

func WithHTTPClient

func WithHTTPClient(client *http.Client) Option

WithHTTPClient overrides the default http.Client for downloads and version discovery. Only used in HTTP+cache mode.

func WithLocalOnly

func WithLocalOnly() Option

WithLocalOnly restricts the catalog to locally cached bundles only.

func WithRefreshTimeout

func WithRefreshTimeout(d time.Duration) Option

WithRefreshTimeout overrides the default staleness-check timeout.

type Section

type Section struct {
	Slug        string   `json:"slug"`
	RelPath     string   `json:"rel_path"`
	Title       string   `json:"title"`
	Description string   `json:"description"`
	Weight      int      `json:"weight"`
	Category    string   `json:"category"`
	Children    []string `json:"children"`
	IsIndex     bool     `json:"is_index"`
	Aliases     []string `json:"aliases,omitempty"`
}

Section represents a single documentation section.

type Tree

type Tree struct {
	*Section
	Children []*Tree
}

Tree is a depth-limited node in a section tree.

type WriteDirFS

type WriteDirFS interface {
	MkdirAll(path string, perm fs.FileMode) error
	RemoveAll(path string) error
}

WriteDirFS manages directories.

type WriteFileFS

type WriteFileFS interface {
	WriteFile(name string, data []byte, perm fs.FileMode) error
}

WriteFileFS writes files.