pmndrs.docs

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:

---
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
  • 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)

MDX Support in Frontmatter

Frontmatter values like title and description support Markdown formatting. You can use inline elements like bold, italic, code, and links:

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

The compiled MDX will render with proper formatting in the page header.

Tip

When using special characters like backticks () in frontmatter values, wrap the entire value in quotes: title: 'Intro'ortitle: "Intro". For plain text without special characters, quotes are optional: title: My Title`.

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 react-mcu colors, eg: text-on-surface-variant above

Plus:

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

docs/authoring/introduction.mdx

Edit this page