Collapsible Sections

Collapsible sections reduce the visual footprint of long code blocks. Kazari supports two collapse mechanisms: threshold-based (auto-collapse when a block exceeds a line count) and range-based (collapse specific line ranges).

Enabling collapsible sections

Range-based collapse works on any engine: a collapse={N-M} meta token renders a native <details> section, and the collapse stylesheet is always part of CSS(). WithCollapsible enables threshold-based auto-collapse, its JavaScript module, and the threshold defaults.

1
engine := kazari.New(
2
    kazari.WithHighlighter(hl),
3
    kazari.WithThemes("github-light", "github-dark"),
4
    kazari.WithCollapsible(kazari.CollapsibleConfig{
5
        LineThreshold: 15,
6
        PreviewLines:  8,
7
    }),
8
)

Or in the config file:

1
collapsible:
2
  lineThreshold: 15
3
  previewLines: 8
4
  defaultCollapsed: true

Setting WithCollapsible(CollapsibleConfig{}) with zero values enables the feature with internal fallback defaults (LineThreshold: 15, PreviewLines: 8).

CollapsibleConfig fields:

Threshold-based collapse

When a code block exceeds LineThreshold lines, it auto-collapses to a preview of the first PreviewLines lines. A gradient overlay fades the bottom, and an expand button reveals the full code.

1
```go title="server.go" collapseThreshold=20
2
func main() {
3
    cfg := loadConfig()
4
    db := connectDB(cfg)
5
    defer db.Close()
6
7
    router := chi.NewRouter()
8
    router.Use(middleware.Logger)
9
    router.Use(middleware.Recoverer)
10
11
    router.Get("/health", healthHandler)
12
    router.Get("/api/users", usersHandler(db))
13
    router.Post("/api/users", createUserHandler(db))
14
    router.Get("/api/users/{id}", getUserHandler(db))
15
    router.Put("/api/users/{id}", updateUserHandler(db))
16
    router.Delete("/api/users/{id}", deleteUserHandler(db))
17
18
    router.Get("/api/posts", postsHandler(db))
19
    router.Post("/api/posts", createPostHandler(db))
20
    router.Get("/api/posts/{id}", getPostHandler(db))
21
22
    log.Printf("Starting server on :8080")
23
    http.ListenAndServe(":8080", router)
24
}
25
```

1
func main() {
2
    cfg := loadConfig()
3
    db := connectDB(cfg)
4
    defer db.Close()
5
6
    router := chi.NewRouter()
7
    router.Use(middleware.Logger)
8
    router.Use(middleware.Recoverer)
9
10
    router.Get("/health", healthHandler)
11
    router.Get("/api/users", usersHandler(db))
12
    router.Post("/api/users", createUserHandler(db))
13
    router.Get("/api/users/{id}", getUserHandler(db))
14
    router.Put("/api/users/{id}", updateUserHandler(db))
15
    router.Delete("/api/users/{id}", deleteUserHandler(db))
16
17
    router.Get("/api/posts", postsHandler(db))
18
    router.Post("/api/posts", createPostHandler(db))
19
    router.Get("/api/posts/{id}", getPostHandler(db))
20
21
    log.Printf("Starting server on :8080")
22
    http.ListenAndServe(":8080", router)
23
}

→ The block auto-collapses because it exceeds 20 lines. A gradient overlay and expand button appear at the bottom.

Per-block threshold

collapseThreshold=N overrides the engine LineThreshold for a single block. The block auto-collapses only when its line count exceeds N.

Force and suppress

Use collapse to force threshold collapse regardless of line count. Use nocollapse to suppress threshold collapse for a specific block.

Priority order: nocollapse > collapse > collapseThreshold=N > engine LineThreshold.

The toolbar also shows a chevron toggle button on threshold-collapsed blocks. Both the bottom bar button and the toolbar chevron stay in sync; clicking either one toggles the same collapsed state. See Toolbar for details.

Labeled markers suppress auto-collapse

See Line Markers for labeled marker syntax.

Marker-aware preview

When a threshold-collapsed block has marked or focused lines beyond the normal preview region, the preview extends to include them. The extension follows these rules:

• Within 2x cap: marked or focused lines within 2 * PreviewLines are shown as additional segments with one line of context on each side. Non-contiguous segments are separated by ⋮ gap indicators.
• Beyond 2x cap: marked lines too far away are not shown. Instead, the expand button displays a count: "Show more (+3 highlighted)".

This happens automatically when threshold-based collapse and line markers or focus lines are combined on the same block:

1
```go {10-11} collapse
2
// 28-line block with markers on lines 10-11
3
```

The preview shows the first few lines, then a gap indicator, then the marked lines with surrounding context. The expand button reveals the full block. If marked lines fall beyond the 2x cap, the button displays a badge like "Show more (+3 highlighted)" instead.

Range-based collapse

Collapse specific line ranges with collapse={N-M}. The collapsed range renders as a summary row showing the hidden line count:

1
```go title="calc.go" showLineNumbers collapse={3-8}
2
func Calculate(expr string) (float64, error) {
3
    tokens := tokenize(expr)
4
    ast, err := parse(tokens)
5
    if err != nil {
6
        return 0, fmt.Errorf("parse: %w", err)
7
    }
8
    result := evaluate(ast)
9
    validate(result)
10
    return result, nil
11
}
12
```

1
func Calculate(expr string) (float64, error) {
2
    tokens := tokenize(expr)
6 collapsed lines
3
    ast, err := parse(tokens)
4
    if err != nil {
5
        return 0, fmt.Errorf("parse: %w", err)
6
    }
7
    result := evaluate(ast)
8
    validate(result)
9
    return result, nil
10
}

→ Lines 3-8 are hidden behind a summary row showing the collapsed line count. Click to expand.

Multiple ranges

Collapse multiple ranges with comma-separated values. Each range renders its own summary row:

1
```go title="api.go" showLineNumbers collapse={3-7,9-13}
2
package api
3
4
import (
5
    "encoding/json"
6
    "net/http"
7
    "log"
8
)
9
10
type Response struct {
11
    Status  int
12
    Message string
13
    Data    interface{}
14
}
15
16
func handleGet(w http.ResponseWriter, r *http.Request) {
17
    data := fetchData(r.URL.Query())
18
    json.NewEncoder(w).Encode(Response{Status: 200, Message: "OK", Data: data})
19
}
20
```

1
package api
2
5 collapsed lines
3
import (
4
    "encoding/json"
5
    "net/http"
6
    "log"
7
)
8
5 collapsed lines
9
type Response struct {
10
    Status  int
11
    Message string
12
    Data    interface{}
13
}
14
15
func handleGet(w http.ResponseWriter, r *http.Request) {
16
    data := fetchData(r.URL.Query())
17
    json.NewEncoder(w).Encode(Response{Status: 200, Message: "OK", Data: data})
18
}

→ The imports (lines 3-7) and type definition (lines 9-13) each collapse independently. Click either summary row to expand that section.

When PreserveIndent is true (default), the summary text is indented to match the minimum indentation of the collapsed lines. A --kz-indent CSS variable is set on the summary, measured in ch units.

When line numbers are enabled, the summary row renders an empty gutter placeholder to maintain alignment with surrounding code lines.

Collapse styles

Set the collapse style per block with collapseStyle= or globally via CollapsibleConfig.Style. Four styles are available:

The GitHub style uses native <details> toggling. Once expanded, the summary row is hidden via CSS and there is no UI to re-collapse the section.

The Start and End styles also use <details> but keep the summary visible as a toggle. Clicking the summary expands or collapses the content. The End style achieves "summary below content" through CSS flex-direction: column-reverse, not DOM reordering.

The Auto style resolves per range. In a block with multiple ranges, one range at the end of the block gets the End style while other ranges get the Start style.

collapsible-start

The summary appears above the collapsed content. Clicking it toggles the section open and closed:

1
```go title="calc.go" showLineNumbers collapse={3-8} collapseStyle="collapsible-start"
2
func Calculate(expr string) (float64, error) {
3
    tokens := tokenize(expr)
4
    ast, err := parse(tokens)
5
    if err != nil {
6
        return 0, fmt.Errorf("parse: %w", err)
7
    }
8
    result := evaluate(ast)
9
    validate(result)
10
    return result, nil
11
}
12
```

1
func Calculate(expr string) (float64, error) {
2
    tokens := tokenize(expr)
6 collapsed lines
3
    ast, err := parse(tokens)
4
    if err != nil {
5
        return 0, fmt.Errorf("parse: %w", err)
6
    }
7
    result := evaluate(ast)
8
    validate(result)
9
    return result, nil
10
}

→ The summary row stays visible after expanding, allowing the section to be collapsed again.

collapsible-end

The summary appears below the collapsed content:

1
```go title="calc.go" showLineNumbers collapse={3-8} collapseStyle="collapsible-end"
2
func Calculate(expr string) (float64, error) {
3
    tokens := tokenize(expr)
4
    ast, err := parse(tokens)
5
    if err != nil {
6
        return 0, fmt.Errorf("parse: %w", err)
7
    }
8
    result := evaluate(ast)
9
    validate(result)
10
    return result, nil
11
}
12
```

1
func Calculate(expr string) (float64, error) {
2
    tokens := tokenize(expr)
6 collapsed lines
3
    ast, err := parse(tokens)
4
    if err != nil {
5
        return 0, fmt.Errorf("parse: %w", err)
6
    }
7
    result := evaluate(ast)
8
    validate(result)
9
    return result, nil
10
}

→ The toggle appears below the hidden lines. Achieved via CSS flex-direction: column-reverse, not DOM reordering.

collapsible-auto

Automatically picks Start or End based on range position. A range that reaches the last line gets End style; other ranges get Start:

1
```go title="calc.go" showLineNumbers collapse={3-8} collapseStyle="collapsible-auto"
2
func Calculate(expr string) (float64, error) {
3
    tokens := tokenize(expr)
4
    ast, err := parse(tokens)
5
    if err != nil {
6
        return 0, fmt.Errorf("parse: %w", err)
7
    }
8
    result := evaluate(ast)
9
    validate(result)
10
    return result, nil
11
}
12
```

1
func Calculate(expr string) (float64, error) {
2
    tokens := tokenize(expr)
6 collapsed lines
3
    ast, err := parse(tokens)
4
    if err != nil {
5
        return 0, fmt.Errorf("parse: %w", err)
6
    }
7
    result := evaluate(ast)
8
    validate(result)
9
    return result, nil
10
}

→ Since the range does not reach the last line, Auto resolves to Start style here.

Style cascade: per-block meta collapseStyle= > engine config Style > CollapseGithub default.

Go API

Control collapse per-block via Options.Collapse:

1
threshold := 30
2
html, err := engine.Render(code, kazari.Options{
3
    Lang: "go",
4
    Collapse: &kazari.CollapseOptions{
5
        Ranges:    []kazari.Range{{Start: 3, End: 8}},
6
        Threshold: &threshold,
7
    },
8
})

CollapseOptions fields:

Or via meta string:

1
html, err := engine.RenderWithMeta(code, `go collapse={3-8,15-20} collapseStyle="collapsible-start"`)

See Configuration Layers for the full cascade and override rules.

Configuration

Meta string options:

Config file:

1
collapsible:
2
  lineThreshold: 15
3
  previewLines: 8
4
  defaultCollapsed: true
5
  preserveIndent: true
6
  style: "collapsibleStart"
7
  expandButtonText: "Show more"
8
  collapseButtonText: "Show less"

Config file style names use camelCase (collapsibleStart, collapsibleEnd, collapsibleAuto, github). Meta string uses kebab-case (collapsible-start, collapsible-end, collapsible-auto).

Range validation

Invalid or conflicting ranges are handled silently:

Ranges are sorted by start line before processing. First valid range wins on overlap.

CSS variables

Range-based sections

Threshold-based

These variables are always part of CSS(). See the CSS Variables reference for the complete list.

Interaction with other features

• Line numbers: summary and gap rows get empty gutter placeholders for alignment. Collapsed lines retain their numbers and resume correctly when expanded.
• Markers: marker classes are preserved in hidden DOM elements. When expanded, marked lines display normally with their highlight, insertion, or deletion styles. For threshold mode, marked lines extend the preview as described in Marker-aware preview.
• Focus lines: included in preview extension, same behavior as markers.
• Word wrap: independent. The collapse summary row has its own --kz-indent (from the minimum indentation of collapsed lines), separate from wrap's per-line --kz-indent.
• Print: threshold mode forces all content visible (gradient and button hidden). Range mode shows content and hides summary headers.

Accessibility

Range-based sections use native <details>/<summary> elements. Keyboard navigation works out of the box: Tab to focus the summary, Enter or Space to toggle. Screen readers announce the summary text (e.g., "5 collapsed lines"). Expand and collapse icons are decorative CSS pseudo-elements, not announced.

Threshold-based collapse uses aria-expanded on both the bottom bar button and the toolbar chevron. An aria-live="polite" region announces state changes to screen readers. Custom announcement text is configurable via ExpandedAnnouncement and CollapsedAnnouncement in CollapsibleConfig.

Edge cases

• WithCollapsible must be set for threshold-based collapse. Without it, the bare collapse meta token has no effect, while range-based collapse={N-M} still renders a collapsed section.
• Both modes can coexist: a block can have threshold collapse and range-based collapse simultaneously. Range-based sections take precedence in the render loop for lines that fall within a collapse range.
• nocollapse only suppresses threshold-based collapse. Range-based collapse (collapse={N-M}) still works on a nocollapse block.
• Config file style names use camelCase (collapsibleStart), meta string uses kebab-case (collapsible-start).
• Unrecognized collapseStyle values in meta silently default to github. Invalid values in the config file produce a validation error.
• Range-based collapse uses native <details>/<summary> toggling and requires no JavaScript. Only threshold-based collapse needs the collapsible JS module.