Collections API

Collections hold structured content (usually markdown files with YAML frontmatter) under a shared schema. Piko reads them at build time and exposes them through the package-level functions and template attributes documented below. For task recipes see the markdown collections how-to and the querying and filtering how-to.

Directory layout

A collection named blog lives at content/blog/. Piko reads every file matching the provider's pattern (typically *.md) at build time.

content/
  blog/
    hello-world.md
    second-post.md
  docs/
    getting-started.md
    routing.md

Template attributes

When a PK page sets p-collection, Piko generates one route per item in that collection and binds the item's frontmatter to the page's render context.

Attribute	Default	Purpose
`p-collection`	required	Collection name (the directory under `content/`)
`p-provider`	`"markdown"`	Provider backing the collection
`p-param`	`"slug"`	Route parameter used to look up the current item
`p-collection-source`	none	Import alias for a collection defined in an external module

Inside the template, <piko:content /> renders the parsed markdown body as HTML.

Note: <piko:content /> is a meta element. Tags in the piko: namespace render as their post-colon name with Piko behaviour injected; this one disappears from the output, and Piko substitutes the rendered markdown body. See about PK files for the meta-element family.

Data access

`piko.GetData[T](r) T`

Returns the frontmatter for the current item, decoded into T. Signature:

func GetData[T any](r *piko.RequestData) T

If GetData cannot decode the frontmatter into T, it returns the zero value.

`piko.GetAllCollectionItems(name string) ([]map[string]any, error)`

Returns every item's frontmatter (no body content) in the named collection. Use for listing pages and dynamic navigation. Returns an error if the collection does not exist or its provider fails to enumerate.

`piko.GetSections(r *piko.RequestData) []piko.Section`

Returns a flat list of headings extracted from the current item's markdown body, suitable for a table of contents.

`piko.GetSectionsTree(r *piko.RequestData, opts ...piko.SectionTreeOption) []piko.SectionNode`

Returns the same headings as a nested tree. Options:

Option	Default	Effect
`piko.WithMinLevel(n)`	2	Minimum heading level to include (for example 2 = h2).
`piko.WithMaxLevel(n)`	4	Maximum heading level to include.

SectionNode:

type SectionNode struct {
    Title    string
    Slug     string
    Children []SectionNode
    Level    int
}

Slug is the URL-safe anchor ID (for example "getting-started"). Level is the heading level from 2 to 6, where 2 means h2.

Search and filtering

A provider enumerates items from its source. The result passes through a filter pipeline of filter predicate, sort option, and pagination. SQL providers push the filter into a WHERE clause; other providers filter in memory. Call sites either retrieve one item via GetData or a result set via SearchCollection, with typed outputs.

`piko.SearchCollection[T any](r *RequestData, collectionName, query string, opts ...SearchOption) ([]SearchResult[T], error)`

Fuzzy full-text search against the items of a named collection, with field weighting, fuzziness tuning, and relevance scoring. Type parameter T is the shape you want items decoded into.

`piko.QuickSearch[T any](r *RequestData, collectionName, query string) ([]T, error)`

Convenience wrapper around SearchCollection with sensible defaults. Returns items directly without the SearchResult wrapper.

Search options

Passed as variadic SearchOption values to SearchCollection:

Option	Effect
`WithSearchFields(fields...)`	Restrict the search to specific fields.
`WithFuzzyThreshold(threshold)`	Minimum fuzzy-match score (0.0 - 1.0).
`WithSearchLimit(limit)`	Maximum number of results.
`WithSearchOffset(offset)`	Pagination offset.
`WithMinScore(score)`	Minimum relevance score to include.
`WithCaseSensitive(sensitive)`	Toggle case sensitivity.
`WithSearchMode(mode)`	Select a search mode: `"fast"` (default) or `"smart"` (adds stemming and phonetic matching).

Filter API

Function or type	Purpose
`piko.NewFilter(field, operator, value)`	Construct a single filter condition.
`piko.And(filters...)`	Combine filters with AND.
`piko.Or(filters...)`	Combine filters with OR.
`piko.NewSortOption(field, order)`	Construct a sort option.
`piko.NewPaginationOptions(limit, offset)`	Construct pagination options.

Filter operator constants use the FilterOp prefix: piko.FilterOpEquals, piko.FilterOpNotEquals, piko.FilterOpGreaterThan, piko.FilterOpGreaterEqual, piko.FilterOpLessThan, piko.FilterOpLessEqual, piko.FilterOpContains, piko.FilterOpStartsWith, piko.FilterOpEndsWith, piko.FilterOpIn, piko.FilterOpNotIn, piko.FilterOpExists, piko.FilterOpFuzzyMatch. Sort orders are piko.SortAsc and piko.SortDesc.

See the querying and filtering how-to for usage.

Type	Purpose
`NavigationGroups`	Top-level grouping for sidebar and footer structures.
`NavigationTree`	Hierarchical view of groups and their children.
`NavigationNode`	Single node in a navigation tree.
`NavigationConfig`	Options that control how Piko builds trees.

Providers

The default provider is markdown. Piko registers other providers (SQL, JSON, custom) through its internal provider registry instead of a public bootstrap option. See the custom providers how-to guide for the registration mechanism.