Skip to main content

Documentation

This page documents how we use Docusaurus, modifications we've made,

Code playgrounds

Markdown code blocks can be automatically turned into editable "playgrounds" with a live rendering of the HTML above the editor. (We've customized the Docusaurus component to look and act a bit differently, but the underlying implementation is the same.)

Loading...
Code editor

Just add the live keyword after the html or jsx language code in the code block header after the three backticks:

```html live
```jsx live

For longer code samples you may choose to collapse the code editor by adding the closed keyword:

```html live closed
Loading...
Code editor

All of the globals available in MDX, including our documentation components, are available in the playground JSX scope.

Globals

All of the named exports in website/src/components are available in both the global MDX scope and in code playgrounds.

The tokens global also allows you to access design tokens defined by the system in packages/sfgov-design-system/src/tokens.

Documentation components

All of these components are available in the global MDX scope.

DoDont

Use the <DoDont>, <Do>, and <Dont> components to display side-by-side examples. The "do" example should come first (left), and the "don't" second (right).

Loading...
Code editor

InlineSwatch

Use the <InlineSwatch> component to display color values within text. Please use color tokens (tokens.color...) instead of literal values. The label can be passed either as a string via the label prop or as children.

Loading...
Code editor

Markdown

Markdown components are styled by Docusaurus out of the box, but can be overridden in website/src/theme/MDXComponents.jsx. You can see how some common "prose" elements are rendered below.

  • Unordered list item
  • Unordered list item
  1. Ordered list item
  2. Ordered list item

A paragraph with some strong text (i.e. bold) and emphasized text (which should not be italicized), and a link for good measure.

This is a block quote.

This is the second paragraph in the block quote.

This is a preformatted block without a language identifier.

These
words
should
appear
on
separate
lines.
<!-- HTML -->
<p class="m-0">This is a paragraph.</p>
/** CSS */
html {
font-size: 100px;
}

* {
box-sizing: border-box;
}
// JavaScript
for (let i = 1; i <= 100; i++) {
console.log(`Hello, world #${i}!`)
}
/* JSX is cool, too */
<SomeAwesomeComponent>
{({ renderProp }) => JSON.stringify(renderProp)}
</SomeAwesomeComponent>

Admonitions

Admonitions are Markdown directives, which are written like so:

:::{type}
Your content here, including **Markdown**, [links](https://example.com), etc.
:::

...where {type} is one of note, tip, info, caution, or danger (warning also works). See the Docusaurus docs for more info about the built-in component.

Admonition types

note

This is a note block with a link in it.

tip

This is a tip directive with a link in it.

info

This is an info directive with a link in it.

caution

This is a caution with a link in it.

danger

This is a warning block with a link in it.

danger

This is a danger block with a link in it.