# Bx Sites Content Blocks > BxSites Content Blocks - Skill: `ortus-boxlang/bx-sites-content-blocks` (Agent Skill) - Install (CLI): `npx skillmds@latest add ortus-boxlang/bx-sites-content-blocks` - Raw SKILL.md: https://api.skillmd.com/api/skills/ortus-boxlang/bx-sites-content-blocks/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: ortus-boxlang (https://skillmd.com/u/ortus-boxlang) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/ortus-boxlang/bx-sites-content-blocks --- # BxSites Content Blocks GitBook-style content blocks, on top of everything in the `bx-sites-markdown` skill. Every block uses the same `::: name ... :::` container syntax - a bare `:::` on its own line closes whichever block is currently open. Blocks can nest (an expandable containing a card grid, for instance). No `bxsites.yaml` config needed unless noted. Each maps to a GitBook block of the same name, which is why `bxSites migrate --from=gitbook` (see `bx-sites-getting-started`) can convert them directly. ## Expandable Plain collapsible section - no callout icon/color (for that, use a collapsible admonition `???`, see `bx-sites-markdown`). ```markdown ::: expandable "Is this different from a collapsible admonition?" Yes - this has no type/icon/color, just a plain expand/collapse section. Add `open="true"` to start it expanded. ::: ``` ## Cards A grid of link cards. `title`, `icon`, `image`, `href` are all optional (no `href` renders a non-clickable card). `icon` resolves the same way frontmatter `icon` does (see `bx-sites-markdown`). ```markdown ::: cards ::: card title="Getting Started" icon="phosphor-duotone:rocket-launch" href="../getting-started.md" Install, scaffold and build your first site. ::: ::: card title="Themes" icon="phosphor-duotone:palette" href="themes.md" Customize a built-in theme or write your own. ::: ::: ``` ## Columns Side-by-side layout. `::: column` accepts an optional `width` (CSS length/percentage, e.g. `"40%"`); columns with no explicit width share the row equally. ```markdown ::: columns ::: column width="60%" The wider column. ::: ::: column The narrower one. ::: ::: ``` ## Stepper Numbered, connected sequence of steps. Optional `color` on a step (`success`, `warning`, `danger`, or omit for default) flags its marker independent of position: ```markdown ::: stepper ::: step "Back up your data" color="success" Routine, safe to run any time. ::: ::: step "Optional: enable telemetry" color="warning" Skip this one if you're not sure. ::: ::: step "Delete the old install" color="danger" Irreversible - make sure the backup above finished first. ::: ::: ``` Marker/line/palette colors are themeable via CSS custom properties (see the `bx-sites-themes` skill). ## File A download card for a PDF, video, or any other asset. `src` resolves relative to `docs/assets/`. ```markdown ::: file src="assets/spec.pdf" title="API Specification" ::: ``` ## Page break Forces a page break for print/PDF export (e.g. browser "Print to PDF"). No attributes; renders as a subtle divider on screen, only forces a real break in print output. ```markdown ::: pagebreak ::: ``` ## Buttons GitBook-style call-to-action button - `::: button` alone, or several in a row inside `::: buttons`. Only `"Label"` and `href` are required for most buttons: ```markdown ::: buttons ::: button "Read the docs" href="../getting-started.md" icon="phosphor-duotone:book-open" size="large" ::: ::: button "Star on GitHub" href="https://github.com/org/repo" style="secondary" target="_blank" ::: ::: button "Coming soon" disabled="true" ::: ::: ``` Optional attributes: - `style="primary"` (solid accent) or `"secondary"` (default, outline) - `size="small"`, `"medium"` (default), `"large"` - `icon="..."` - same resolution as a card's icon - `target="_blank"` - opens in a new tab (`rel="noopener noreferrer"` added automatically) - `disabled="true"` - inert, unclickable, no `href` needed ## Embed Responsive iframe for a recognized provider: YouTube, Vimeo, CodePen, Spotify, Loom, Figma. Anything else falls back to a plain "visit ↗" link card instead of a broken iframe. ```markdown ::: embed url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" title="A demo" ::: ``` ## Page link Rich preview card linking to another page in this site - `href` follows the same file-relative convention as an ordinary page link. Title/icon/summary are pulled automatically from the target page's own frontmatter (stays in sync if that page is renamed). ```markdown ::: page-link href="../getting-started.md" ::: ``` ## Link preview Same card shape as page-link, but for an *external* URL - no page to pull metadata from, so every field is an explicit attribute. Only `url` is required; `title` falls back to the bare URL; `description`/`image` are optional. No build-time fetch of the target (keeps builds fast/reliable). ```markdown ::: link-preview url="https://boxlang.io" title="BoxLang" description="A dynamic, multi-paradigm JVM language." image="https://boxlang.io/og.png" ::: ``` ## Prompt A styled, copyable container for a reusable AI prompt (bx-sites' equivalent of GitBook's Prompt block). The block body *is* the prompt text (full Markdown - headings/lists/code all format normally); gets a "Copy" button that copies the exact source text. ```markdown ::: prompt description="Summarizes a pull request for a changelog entry" icon="phosphor-duotone:git-pull-request" Summarize the following pull request diff as a single changelog entry, written for an end user rather than a developer. ::: ``` `description` (one-line summary) and `icon` (defaults to a sparkle glyph) are optional. `expanded="preview"` clamps a long prompt to a fade-out preview until clicked; `expanded="hidden"` starts fully collapsed; omit (or `"full"`) to always show it in full. There is no "Open in AI providers" menu - bx-sites never talks to a third-party AI provider. ## Updates (changelog) Dated, taggable changelog list. `::: update` accepts `date="YYYY-MM-DD"` and an optional comma-separated `tags`. ```markdown ::: updates ::: update date="2026-01-15" tags="feature,fix" Added dark mode and fixed a footer alignment bug. ::: ::: update date="2026-01-01" Initial release. ::: ::: ``` A page containing `::: updates` also gets its own `feed.xml` once `bxsites.yaml`'s `baseURL` is a full URL (same requirement as `sitemap.xml` - see `bx-sites-configuration`). ## Reusable content (includes) `::: include src="..."` splices another file's raw Markdown in at that point - becomes real page content (its own headings/paragraphs/nested blocks), not a wrapped widget. Put partials under `docs/includes/` (a reserved folder, like `assets/`/`versions/`/`i18n/`/`blog/`) - files there are never built as their own page and never appear in nav/search/sitemap/tags. - A **bare** `src` (no leading `./`/`../`) always resolves against the current tree's own `docs/includes/`, regardless of how deep the including page is nested - `::: include src="beta-notice.md"` or `::: include src="legal/terms.md"` for a subfolder. - A `./`/`../`-prefixed `src` resolves file-relative to the *including* page's own directory instead, the same convention as an ordinary page link. - A version/locale tree gets its own `includes/` the same way - `docs/versions/2.0/includes/`, `docs/i18n/es/includes/` - not shared with the main tree's `docs/includes/`. - An included file can itself include another; a circular chain throws `BxSites.CircularInclude` at build time. ## Conditional content Shows one of several variants of a block based on the *reader's own choice* (remembered in their browser's `localStorage`) - there's no server-side identity in a static site. ```markdown ::: audience-switcher key="plan" options="free:Free,pro:Pro" ::: ::: conditional key="plan" value="free" The Free plan includes basic search. ::: ::: conditional key="plan" value="pro" The Pro plan adds AI-assisted search and unlimited team seats. ::: ``` - `::: conditional key="..." value="..."` marks one variant. `key` is whatever preference you're switching on (`"plan"`, `"os"`, `"language"`, anything); `value` is the setting this variant shows for. **Every variant always renders in the HTML** (hidden client-side, never omitted), so a reader with JS disabled or a search crawler still sees every variant. - `::: audience-switcher key="..." options="value:Label,value:Label,..."` is an optional ready-made control - one button per option, switching every `::: conditional` block sharing that `key` anywhere on the page. Not required: a link ending `?plan=pro` sets the same preference on load, and `window.bxSitesSetPreference( key, value )` can drive it from custom UI. ## OpenAPI Interactive Swagger UI widget for an OpenAPI/Swagger spec (JSON or YAML), GitBook's OpenAPI block equivalent. Requires `bxsites.yaml`'s `openapi: true` (see `bx-sites-configuration`; unset, the placeholder renders but stays inert and ships no extra JS/CSS). `src` resolves relative to `docs/assets/`, same as `::: file`. ```markdown ::: openapi src="assets/openapi/example.yaml" title="Bookshelf API" ::: ``` Add `operation="METHOD /path"` to drop just one endpoint inline instead of the full reference (method is case-insensitive; path must match the spec exactly, `{param}` placeholders included): ```markdown ::: openapi src="assets/openapi/example.yaml" operation="GET /books" ::: ``` Everything (schemas, "Try it out") renders client-side straight from the spec - "Try it out" calls the spec's own `servers[0].url` directly from the visitor's browser, so that server must allow CORS from wherever the docs are hosted. No manual, spec-less version exists - if there's no spec yet, either write just enough spec to cover one endpoint, or describe it as ordinary content (a parameters table, fenced `http`/`json` request/response pairs, optionally walked through with a `::: stepper`).