Guide › Templates
On this page
Markdown pages
With @clarusjs/content, any .md file under src/pages is a page. Its Markdown becomes static HTML inside your layout, at build time.
Set up #
// vite.config.ts
import { defineConfig } from 'vite'
import clarusjs from 'clarusjs/vite'
import markdown from '@clarusjs/content'
export default defineConfig({
plugins: [clarusjs({ sources: [markdown({ layout: '/src/layouts/docs.tscl' })] })],
})The package runs only at build time: the Markdown parser never reaches the browser, and clarusjs itself gains no dependency.
A page #
---
title: Getting started
description: Install clarusjs and write your first page.
---
# Getting started
Write **Markdown** as usual.title (or the first # heading) and description go to the layout, with the page's route as path. Set layout: in the frontmatter to use another layout, or layout: false for none.
steps: true (for lessons) wraps each ## heading and what follows it, up to the next one, in a <section class="step" aria-labelledby="…">. The page is still a plain page; a layout can show one step at a time (see Docs theme).
Frontmatter schemas #
Validate frontmatter with any Standard Schema library (Zod, Valibot, ArkType…): one schema for every page, or one per folder under src/pages:
import * as v from 'valibot'
const Post = v.object({ title: v.string(), date: v.pipe(v.string(), v.isoDate()), draft: v.optional(v.boolean(), false) })
markdown({ schema: { 'blog/**': Post } }) // ** any depth, * one folder; the first matching glob winsA page that doesn't match fails the build (and shows in development) with the file and each problem: src/pages/blog/x.md: frontmatter.date: Invalid date. The schema's output, with its defaults and coercions, is what the page gets. Schemas must validate synchronously, as most do. @clarusjs/content depends on no schema library, only the Standard Schema interface; this site's guide pages are checked by a small hand-written one, src/schemas.ts.
Components in Markdown #
Import components at the top, then use them like HTML. Leave blank lines around Markdown inside a component:
@import callout from '@clarusjs/theme-docs/callout.tscl'
<callout [type]="'tip'">
Markdown **inside** a component.
</callout>Headings and text #
- Every heading gets an
idand an anchor link, so#installlinks straight to it. - Markdown is static:
{{ value }}and@ifin your prose are shown as written, never run as template code.
Code #
Fenced code is highlighted at build time with Shiki, in light and dark at once: the page's theme picks the colours with CSS, so no highlighter ships to the browser. tscl blocks are highlighted as templates.
vite.config.ts
tsimport { defineConfig } from 'vite'
import clarusjs from 'clarusjs/vite'
export default defineConfig({ plugins: [clarusjs()] })Mark lines with comments: // [!code ++], // [!code --], // [!code focus], // [!code highlight], // [!code error]. Add :line-numbers after the language for line numbers, and {1,3-5} to highlight lines.
const site = clarusjs()
const site = clarusjs({ sources: [markdown()] }) Group blocks as tabs with ::: code-group; the tabs work without JavaScript:
pnpm add @clarusjs/contentnpm install @clarusjs/contentSnippets and includes #
Show a file, or part of it, with <<<. @ is the project root; regions are marked with #region name and #endregion comments:
<<< @/src/nav.ts#edit [src/nav.ts]src/nav.ts
ts// "Edit this page": the page's source file (:file, e.g. guide/lists.md); pages also give "Last updated".
editLink: 'https://github.com/forinda/clarusjs/edit/main/packages/docs/src/pages/:file',
pages,The code above is this site's real src/nav.ts, read when the site is built. Include shared Markdown with <!-- @include: ./part.md --> (or #region of it); its relative links are rewritten to work from the including page:
<!-- @include: ../../parts/requirements.md -->In development, editing a snippet's file or an included file updates the page.
Head tags #
Frontmatter head adds tags to the page's <head>, and titleTemplate: false uses the title as written instead of the site's template:
---
title: Release notes
titleTemplate: false
head:
- [meta, { name: robots, content: noindex }]
---A page's own social card image goes in image (image: /cards/release.png); with the plugin's site option, every page gets a canonical URL and social cards anyway.
Structured data goes in jsonLd (an object, or a list of them), written as JSON-LD:
---
jsonLd:
"@context": https://schema.org
"@type": HowTo
name: Write a Markdown page
---They become a <cl-head> block, which works in any .tscl page too (see the plugin's head option).
Quizzes #
In a lesson (frontmatter steps: true), ::: quiz asks a question. Its task list is the options, with the right one ticked; whatever follows is the explanation:
::: quiz Where does the page for `/about` live?
- [ ] `src/about.html`
- [x] `src/pages/about.tscl`
A page's path under `src/pages` is its URL.
:::It is static HTML: the options are radio buttons and the answer is in a <details>, so it works without JavaScript. With markdown({ quiz: { tag: 'quiz', from: '@clarusjs/theme-docs/quiz.tscl' } }) it renders through the theme's quiz, whose options are an island: pick one, Check, and the right answer and the explanation show. In a lesson the action bar does the checking (see Docs theme). A quiz needs exactly one right answer; markdown({ quizzes: 'everywhere' }) allows quizzes outside lessons.
Links #
Link to another page by its file: [Setup](./getting-started.tscl) or [Intro](./what-is-clarusjs.md#when-to-use-it) become the page's route, so links survive moving a page and match what your editor shows.
Every build checks links once all pages are written: a link to a page or file that doesn't exist fails the build, and a link to a missing #anchor is a warning, each with the file and line and a "did you mean" suggestion. Set the levels with the plugin's links option.
Containers and alerts #
::: tip, ::: info, ::: warning and ::: danger blocks, with an optional title, and ::: details (a native <details>):
::: warning Before you upgrade
Read the changelog.
:::
::: details Show the long version
Hidden until opened.
:::GitHub alerts work too: > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING] and > [!CAUTION].
By default these are plain HTML (<div class="custom-block tip">). Pass container: { tag, from } to render them through your own component instead, with a custom title in its title slot. This site renders them as its callouts:
markdown({ container: { tag: 'callout', from: '@clarusjs/theme-docs/callout.tscl' } })What does a container compile to?
A <callout> with a type, and the title in its title slot. Containers nest with a longer fence (:::: around :::).