Frames & Titles

Frames wrap a code block in editor or terminal chrome, adding a title bar with a language badge and toolbar buttons. Four frame types are available: code (editor), terminal (shell window), none (bare block), and auto (detect from language, the default).

Frame types

Editor frame

The default frame for most languages. It renders a title bar with an optional file tab, a language badge, and toolbar buttons.

Set an explicit title with title=:

1
```go title="main.go"
2
func main() {
3
    fmt.Println("Hello, world!")
4
}
5
```

1
func main() {
2
    fmt.Println("Hello, world!")
3
}

→ An editor frame with a main.go file tab, language badge, and toolbar buttons.

Terminal frame

Use a shell language to trigger terminal auto-detection:

1
```bash
2
curl -s https://api.example.com/status | jq '.health'
3
```

curl -s https://api.example.com/status | jq '.health'

→ A terminal frame with macOS-style colored dots and toolbar buttons.

Add an explicit title to a terminal frame:

1
```powershell title="PowerShell"
2
Get-Process | Where-Object { $_.CPU -gt 100 }
3
```

Get-Process | Where-Object { $_.CPU -gt 100 }

→ A terminal frame with "PowerShell" centered in the title bar.

The following 19 languages trigger terminal auto-detection:

ansi bash bat batch cmd console fish nu nushell powershell ps ps1 psd1 psm1 sh shell shellscript shellsession zsh

Matching is case-insensitive.

No frame

Remove the frame entirely with frame="none". No title bar, no toolbar. Only the copy button remains, floating in the top-right corner on hover.

1
```go frame="none"
2
fmt.Println("no frame")
3
```

1
fmt.Println("no frame")

→ A bare code block with no title bar or toolbar.

Forcing a frame type

An explicit frame= in the meta string always wins, even if it contradicts the language.

1
```go frame=terminal title="Go in a terminal"
2
fmt.Println("terminal frame on a Go block")
3
```

1
fmt.Println("terminal frame on a Go block")

→ A Go block rendered with terminal chrome because frame=terminal overrides auto-detection.

Title bar

Explicit title

Set a title with title= in the meta string. The title appears as a file tab in editor frames and as centered text in terminal frames.

1
```typescript title="server.ts"
2
const app = express()
3
app.listen(3000)
4
```

1
const app = express()
2
app.listen(3000)

→ An editor frame with a server.ts file tab in the title bar.

File name extraction

Place a file path comment on the first line of a block with no title= set:

1
````
2
```javascript
3
// src/greet.js
4
export function greet(name) {
5
    return `Hello, ${name}!`
6
}
7
```
8
````

1
export function greet(name) {
2
    return `Hello, ${name}!`
3
}

→ An editor frame with src/greet.js as the title. The comment line is removed from the rendered output.

Kazari scans the first 4 lines for a comment containing a file path. Recognized comment styles:

Shebangs (#!/bin/bash) are not treated as filename comments. Optional label prefixes (file name:, filename:, example:) are stripped automatically.

A comment is accepted as a filename when it has a recognized file extension (~70 supported), matches a special basename (makefile, dockerfile, rakefile, gemfile, procfile), or is a dotfile (.env, .gitignore). Comments containing :// (URLs) or spaces (sentences) are rejected.

An explicit title= in the meta string always takes precedence. File name extraction only runs when no title is set.

Disable this behavior with kazari.WithFileNameExtraction(false) or fileNameExtraction: false in the config file.

Shebang override

A #! shebang in the first 4 lines forces the frame to editor mode, even for terminal languages:

1
```bash
2
#!/bin/bash
3
set -euo pipefail
4
echo "script file, not a terminal session"
5
```

#!/bin/bash
set -euo pipefail
echo "script file, not a terminal session"

→ Despite being bash, this block gets an editor frame because the shebang indicates a script file, not a terminal session.

Pipeline order

File name extraction runs before frame auto-detection. A bash block with a filename comment (like # deploy.sh) first gets its title extracted, then the file indicator check assigns an editor frame instead of a terminal frame.

Terminal dot styles

Two dot styles are available for terminal frames, set at the engine level with kazari.WithTerminalDotStyle():

There is no meta string option for dot style. It applies to all terminal frames in the engine.

1
terminalDotStyle: "minimal"

Both CSS rule sets are always included in the generated stylesheet regardless of which style is configured. Only the rendered HTML markup differs.

Configuration

Set frames per language via WithLanguageDefaults or the config file:

1
engine := kazari.New(
2
    kazari.WithHighlighter(hl),
3
    kazari.WithLanguageDefaults(map[string]kazari.BlockDefaults{
4
        "bash,sh,zsh": {Frame: kazari.FrameTerminal},
5
        "go":          {Frame: kazari.FrameCode},
6
    }),
7
)

1
frameDetection: true
2
fileNameExtraction: true
3
4
languageDefaults:
5
  "bash,sh,zsh":
6
    frame: "terminal"

CSS variables

See the CSS Variables reference for the complete list with default values.

Edge cases

• An explicit frame= in the meta string always wins, even if it contradicts the language.
• The ansi language auto-detects as a terminal frame.
• Mermaid blocks (lang="mermaid") bypass framing entirely and render as a bare <pre class="mermaid">.
• Terminal frames never show file icons, even when WithFileIcons(true) is enabled and a title is set.
• Terminal comment stripping only applies to terminal frames and only affects the copy-button payload, not the displayed code. See Terminal Comment Stripping for details.
• When WithFrameDetection(false), all FrameAuto blocks default to FrameCode. Explicit frame=terminal still works.