Skip to the content

Add a page to your site

Write a page for your design system website in markdown, with a live example of your own component, and see it in pd dev beside the workbench.

The project has had a site since the first step: the pages pd init wrote, built from components in your style guide. This step adds a page of your own, about the badge, with a live example of it.

Open the site

With pd dev running, open http://live.localhost:4000/. That is the site, from the same pd dev as the workbench at http://pd.localhost:4000/. Its home page is pages/index.md, and every page in the navigation is a file in pages/.

The Configuration page of this site: the header with its sections, the page title, a highlighted code block with its Copy button, and On this page on the right.
A page of this site, the Pattern Dump docs, built with its style guide's layouts/doc. In dark mode, the picture is dark too.

The starter's pages look different, with the starter's layouts, but they are made the same way.

Write a page

Every .md file in pages/ is a page, and its path is its address: pages/about.md is /about/, pages/articles/hello.md is /articles/hello/, and index.md is the folder's own page. A file or folder name is lowercase letters, digits and hyphens. There is no key in the frontmatter that changes the address.

Create pages/badges.md:

---
title: Badges
order: 5
description: A short label for something new, or a warning about something old.
---

The badge marks something new. Its warning variant marks something on its way out.

```pattern atoms/badge~warning
```

Open http://live.localhost:4000/badges/. The page is there, and in the navigation too: adding the file is all it takes. order: 5 puts it after the starter's pages, which carry 1 to 4; without it, a page counts as 0 and comes before them.

The block between the --- lines is the frontmatter, the page's data. The page names no layout, so it takes layouts/page, the default. title and description are keys that layout declares; a key it doesn't declare stops the page, with the file and the line:

"subtitle" is not declared by layout "page"

Sites explains why: a page is data for its layout, and the layout's schema says what that data may be.

A live example

The pattern block shows a component from your style guide on the page: the component's preview from the workbench, in a frame of its own, so the badge looks exactly as it does on the Stage. Under it, the example lists the component's variants, default first, and its caption links to the component in the workbench.

An id that names no component stops the page. In pd dev, the page then says that it cannot be built and lists why:

badges.md: pattern atoms/bagde~warning: there is no such component

pd build stops on the same problem and writes nothing. A typo in a live example can't reach a published page.

Place a component with your values

A live example shows the component with its own data. To use it with values of your own, place it with a pd- tag, its handle after pd-. Add to the page:

<pd-atoms-badge label="Beta" tone="info" />

The attributes are checked against the badge's schema, as the page's frontmatter is checked against its layout's: an attribute the schema doesn't declare, a required one left out, or a value of the wrong type stops the page, with the file, line and column. A component can only be placed when it has a schema. A tag goes on a line of its own: in the middle of a sentence, it stays text.

A link to a component's page in the workbench is a markdown link with pattern: and its id:

The badge's documentation is in [the workbench](pattern:atoms/badge).

Your site

The site has a page of your own, with the badge on it, live from the style guide. The pages pd init wrote show more of what a page can hold, such as the articles in pages/articles/ and a table of contents in pages/guide.md.