Markdown

Long text, such as terms of service, a guide, or an about page, is easier to write in Markdown than in markup. Write it in a .md file in content/, and import it where it goes, like a component. It can use your components too.

A Markdown file#

# Terms of serviceThese terms apply to **everyone** who uses [Mockly](/).<Callout>You can cancel at any time, from your account's settings.</Callout>## Your data- It's yours, and you can export it.- We delete it 30 days after you leave.

A page imports it with its .md, and places it where it goes:

import { Page } from "mockly";import Terms from "../content/terms.md"; export default function TermsPage() {  return (    <Page title="Terms of service">      <article class="prose mx-auto py-12">        <Terms />      </article>    </Page>  );}

export function Callout({ children }: { children?: unknown }) {  return <aside class="rounded-lg border border-amber-300 bg-amber-50 p-4">{children}</aside>;}

Files in content/ and its folders are named with lowercase letters, digits, and dashes. They aren't pages themselves: a page shows them.

What it can say#

Markdown here is CommonMark, with GitHub's additions: tables, task lists, ~~strikethrough~~, and addresses that become links on their own. Fenced code blocks keep their language's name, and footnotes¹ go at the end.

Headings get ids, as on GitHub, so ## Your data can be linked to as /terms#your-data. Links and images are checked as they are in markup: a link to a page the site doesn't have, or an image that isn't in public/, is a warning where it's written, and images get their resized copies, as in pages.

Components#

Markdown can use any component a file in components/ exports, without importing it. On lines of their own, with Markdown inside:

<Callout>Words in **Markdown**.</Callout>

Or in a sentence: Press <Kbd>⌘K</Kbd> to search. Props are strings, or values written out: <Chart values={[3, 5, 8]} />.

As in MDX, < always starts a tag in Markdown. For a less-than sign, write \<. HTML comments and raw HTML aren't Markdown here, and a link is [text](https://…), not <https://…>. Lowercase tags are HTML elements, such as <kbd>. Mockly's built-ins, such as <Show> or <Experiment>, are for TSX files: use them in a component, and the component in your Markdown.

Styles#

Markdown's headings, lists, tables, and code have no classes of their own. Put the class prose on the element that holds it, as in the page above, and they get readable styles, as with Tailwind's typography plugin: prose-lg is bigger, prose-slate a different gray, max-w-none lifts its width, and dark:prose-invert suits a dark page.

Writing it in the studio#

Open a Markdown file from Explorer, under content/. The text has a toolbar: a heading, bold (⌘B), italic (⌘I), a link (⌘K), lists, a quote, and code, and Image and Component put in one of the site's images or components where the cursor is. Source shows the whole file as it's written. Show shows the page that has it in the preview.

Content editors can write Markdown, and make and delete Markdown files, as well as change words on pages. Someone who builds the site publishes.

Rules#