Code

Readable examples, on their own or alongside the story.

Try the presentation

Language Code position Code tone Line numbers Wrap long lines

Explain the idea beside the code.

A code example can stand on its own or share a row with a description. The same content grid handles both layouts.

Resize the window: the blocks stack when there is not enough room. Change the language to compare syntax colors.

svelte

1<script>
2  import { CodeBlock } from '@page-sections/svelte';
3</script>
4
5<CodeBlock code="Hello, world!" />

The composition below uses the current settings. Add precomputed tokens with highlighted for syntax colors.

Example.svelte

svelte

<script>
  import { CodeBlock, ContentGrid, ContentBlock } from '@page-sections/svelte';
</script>

<ContentGrid>
  <ContentBlock span={{ xs: 4, s: 3, m: 4, l: 6 }}>
    <p>Explain the idea beside the code.</p>
  </ContentBlock>
  <ContentBlock span={{ xs: 4, s: 3, m: 4, l: 6 }}>
    <CodeBlock
      code={"<script>\n  import { CodeBlock } from '@page-sections/svelte';\n</script>\n\n<CodeBlock code=\"Hello, world!\" />"}
      language="svelte"
      tone="muted"
      lineNumbers={true}
      wrap={false}
      highlightLines={[2]}
    />
  </ContentBlock>
</ContentGrid>

A complete section

CodeSection adds the usual section heading, spacing, background and navigation registration around a CodeBlock. Source code is always text, never executable HTML.

svelte

<script lang="ts">
  import { CodeSection } from '@page-sections/svelte';
</script>

<CodeSection
  section={{
    id: 'install',
    title: 'Installation',
    headline: 'Add the package',
    code: 'npm install @page-sections/svelte',
    language: 'bash',
    filename: 'Terminal',
    tone: 'muted'
  }}
/>

Highlight at build or server time

Plain code works without a highlighting dependency. For syntax colors, install the optional shiki peer and import highlightCode from the separate entry point. This supports Shiki's bundled languages and aliases; unknown languages fall back to plain text.

bash

npm install shiki

import { highlightCode } from '@page-sections/svelte/highlight';

// Run during prerendering or in your server load function.
const code = 'const answer = 42;';
const highlighted = await highlightCode(code, 'typescript');
// Pass both code and highlighted to CodeBlock or CodeSection.

Pass the result as highlighted. The source and language must match; stale or incomplete tokens fall back to the original text. Colors for light and dark themes are included. The engine stays out of browser bundles when this function is called only from server code.

For data-driven rendering, pass a codeHighlights object to Sections, keyed by each code section's ID. The same map is forwarded into nested grids. Keep original source in content storage; derive highlighting when rendering.

Compose with the existing grid

Place a rich-text section and a code section in a grid. Reorder its blocks to put the code first. Small containers stack the blocks in reading order; larger containers display them side by side.

svelte

<script lang="ts">
  import { Sections, type SectionData } from '@page-sections/svelte';
  const sections: SectionData[] = [
    {
      type: 'grid',
      id: 'explanation',
      title: 'An idea and its code',
      blocks: [
        {
          id: 'text',
          span: { xs: 4, s: 3, m: 4, l: 6 },
          sections: [
            {
              type: 'richText',
              id: 'story',
              title: 'The idea',
              blocks: [{ type: 'paragraph', text: 'Explain the idea beside the code.' }]
            }
          ]
        },
        {
          id: 'code',
          span: { xs: 4, s: 3, m: 4, l: 6 },
          sections: [
            {
              type: 'code',
              id: 'example',
              title: 'The code',
              code: 'const answer = 42;',
              language: 'typescript',
              lineNumbers: true
            }
          ]
        }
      ]
    }
  ];
</script>

<Sections {sections} />

CodeBlock and CodeData

Option	Default	Meaning
`code: string`	Required	Original source. Copy preserves it exactly.
`language: string`	text	Visible language label and highlighting language.
`filename: string`	Unset	Optional file or terminal label.
`tone: SurfaceTone`	muted	standard or muted theme surface.
`lineNumbers: boolean`	false	Visual line numbers, excluded from speech and copied source.
`highlightLines: number[]`	[]	One-based line markers. Invalid and out-of-range numbers have no effect.
`wrap: boolean`	false	Wrap long lines instead of horizontal scrolling.

Additional component props: highlighted?: HighlightedCode, copy (true), label (“Code example”), copyLabel (“Copy code”), copiedLabel (“Copied”), and copyErrorLabel. Set these labels when localizing the host.

CodeSection accepts section: Omit<CodeSectionData, 'type'> and optional highlighted. CodeSectionData extends SectionDefinition and CodeData with type: 'code'. CodeToken describes token text, light/dark colors and font style; HighlightedCode contains source, language and token lines. These models are JSON-compatible and live in core.

Useful before JavaScript

Source, syntax colors supplied by the server and line markers render in initial HTML. The code region is keyboard-focusable for scrolling. The copy button is disabled until the Clipboard API is available; failures are announced without removing the source. Highlighting never uses raw HTML injection.

Language and copy tools

The language and an accessible copy icon sit in the top-right corner of the code surface. There is no separate header row. Source scrolls independently without being covered by the tools; a single line stays compact. An optional filename remains an accessible figure caption and a tooltip on the tools. Copy feedback is announced through a live status region.