You're viewing the dependabot/github_actions/pnpm/action-setup-6 deployment.
View on main →

Authoring

How to write documentation

Summary

This is a guide on how to write documentation. We support all GFM syntax, plus some custom components that are described here.

Keypoints

In your MDX folder, create any path/to/my-document.mdx:

path/to/my-document.mdx
---
title: My Document
description: Lorem ipsum...
nav: 0
image: dog.png
sourcecode: to/my-document.mdx
---

MARKDOWN

Frontmatter

Any key is optional.

  • title: if not provided, last part of the path is used: my document
  • description
  • sourcecode: relative path to the source-code file
  • edit: absolute URL of the "Edit this page" link, instead of the file's path under EDIT_BASEURL -- for a page generated from a source elsewhere, eg: https://github.com/me/mylib/edit/main/README.md
  • image:
    • relative (to the md file) or absolute path, eg: dog.png, ./dog.png, ../../dog.png, /dog.png or https://animals.com/dog.png
    • will be used as metadata image if provided
  • nav: order in the navigation (on the same level)
Tip

title and description support markdown:

---
title: "`Intro` component"
description: Introduction component for **documentation** pages with `code` and [links](#test)
---

⚠️ If starting with backtick, eg title: "`Intro` component" wrap in quotes!

MARKDOWN

Worth mentioning, you can use standard HTML, with tailwind support:

<div>
  <iframe src="https://drei.pmnd.rs/iframe.html?globals=&args=&id=staging-accumulativeshadows--accumulative-shadow-st&viewMode=story" 
    className="w-full h-60 rounded-lg"
  />
  <p className="mt-1 text-xs text-on-surface-variant">This is an embed iframe of [Drei's `<AccumulativeShadows>` story](https://drei.pmnd.rs/?path=/docs/staging-accumulativeshadows--docs).</p>
</div>

result:

This is an embed iframe of Drei's <AccumulativeShadows> story.

Tip

We use material-theme-builder colors, eg: text-on-surface-variant above

Plus:

A relative link to a file of the repository out of the MDX folder, like the one above, links to that file on GitHub, on the branch deployed, under SOURCECODE_BASEURL. Its path starts from the repository root: the nearest folder with a .git, else (built without .git) the nearest with a package.json, which in a monorepo may be a workspace package. It works on GitHub as is. A link staying in the MDX folder, to another page or an asset, is left as is.

See the following pages for detailed documentation on each custom component.

To register your own React components and shared data for MDX pages, see Custom components and data.

docs/authoring/introduction.mdx

Edit this page