Poimandres Full documentation content. URL: /getting-started/introduction Description: Documentation generator for `pmndrs/*` projects. <Intro> A static MDX documentation generator, with a GitHub [reusable workflow](./github-actions.mdx). It is primarily used for some `pmndrs/*` projects, but will work for anyone. </Intro> ![Gutenberg lithography](gutenberg.jpg) [Those projects](https://github.com/search?q=%22uses%3A+pmndrs%2Fdocs%2F.github%2Fworkflows%2Fbuild.yml%22+language%3AYAML&type=code&l=YAML) are known to be using this generator. ## INSTALL Pre-requisites: - Install [nvm](https://github.com/nvm-sh/nvm), then: ```sh $ nvm install $ nvm use $ node -v # make sure your version satisfies package.json#engines.node ``` nb: if you want this node version to be your default nvm's one: `nvm alias default node` ```sh $ git clone https://github.com/pmndrs/docs.git $ cd docs $ pnpm install ``` ## Configuration > [!IMPORTANT] > > Default value is always: `""` (think *empty*). | var | description | example | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | | `MDX`\* | Path to `*.mdx` folder<br/>NB: can be relative or absolute | `docs` or `~/code/myproject/documentation` | | `NEXT_PUBLIC_LIBNAME`\* | Library name | `React Three Fiber` | | `NEXT_PUBLIC_LIBNAME_SHORT` | Library short name | `r3f` | | `NEXT_PUBLIC_LIBNAME_DOTSUFFIX_LABEL` | Text for the ".docs" suffix link inside the header | `docs` | | `NEXT_PUBLIC_LIBNAME_DOTSUFFIX_HREF` | Href for the ".docs" suffix link inside the header | `https://docs.pmnd.rs` | | `BASE_PATH` | Base path for the final URL | `/react-three-fiber` | | `DIST_DIR` | Path to the output folder ([within project](https://nextjs.org/docs/app/api-reference/next-config-js/distDir#:~:text=should%20not%20leave%20your%20project%20directory)) | `out` or `docs/out/react-three-fiber` | | `OUTPUT` | Set to `export` for static output | `export` | | `HOME_REDIRECT` | Where the home should redirect | `/getting-started/introduction` | | `MDX_BASEURL` | Base URL for inlining relative images | `http://localhost:60141`or `https://github.com/pmndrs/react-three-fiber/raw/master/docs` | | `SOURCECODE_BASEURL` | Base URL for `sourcecode:` code path | `https://github.com/pmndrs/react-three-fiber/tree/main` | | `EDIT_BASEURL` | Base URL for displaying "Edit this page" URLs | `https://github.com/pmndrs/react-three-fiber/edit/master/docs` | | `NEXT_PUBLIC_URL` | Final URL of the published website | `https://pmndrs.github.io/react-three-fiber` | | `ICON` | Emoji or image to use as (fav)icon (path local to `MDX`) | `🇨🇭` or `/icon.png` or `/favicon.ico` | | `LOGO` | Logo src/path (either FQURL or local to `MDX` path) | `/logo.png` or `https://worldvectorlogo.com/r3f.png` | | `GITHUB` | Github URL | `https://github.com/pmndrs/react-three-fiber` | | `DISCORD` | Discord URL | `https://discord.com/channels/740090768164651008/740093168770613279` | | `THEME_PRIMARY` | Primary accent color | `#323e48` | | `THEME_SCHEME` | Theme scheme | `content` or `expressive` or `fidelity` or `monochrome` or `neutral` or `tonalSpot` or `vibrant` | | `THEME_CONTRAST` | Theme contrast -- value between -1 and 1 | `0` or `-1` or `1` or `-.6` | | `THEME_NOTE` | "note" color | `#1f6feb` | | `THEME_TIP` | "tip" color | `#238636` | | `THEME_IMPORTANT` | "important" color | `#8957e5` | | `THEME_WARNING` | "warning" color | `#d29922` | | `THEME_CAUTION` | "caution" color | `#da3633` | | `CONTRIBUTORS_PAT` | GitHub token for contributors API (see: https://docs.github.com/en/rest/collaborators/collaborators?apiVersion=2022-11-28#list-repository-collaborators) | `ghp_1234567890` | \* Required <details> <summary>`MDX_BASEURL`</summary> Given a `advanced/introduction.mdx` file in the `MDX` folder: ```md ![](dog.png) ``` becomes (for a `MDX_BASEURL=http://localhost:60141` value): ```md ![](http://localhost:60141/advanced/dog.png) ``` `http://localhost:60141` being the `MDX` folder served. > [!TIP] > When deployed on GitHub Pages, `MDX_BASEURL` will typically value something like `https://github.com/pmndrs/uikit/raw/main/docs`, thanks to [`build.yml`](.github/workflows/build.yml) rule. </details> <details> <summary>`THEME_*`</summary> We implement [m3 design system](https://m3.material.io/styles/color/system/overview), using [react-mcu](https://github.com/abernier/react-mcu). [![color scheme](color-scheme.png)](https://github.com/abernier/react-mcu) > [!NOTE] > - [Material Color](https://www.youtube.com/playlist?list=PLsoLz-E4Os4WWkrvRuQ7BJuVF-WfOyfWT) for more information > - We currently don't have secondary/tertiary colors (maybe some day). </details> ## Usage ### dev ```sh $ ( trap 'kill -9 0' SIGINT export _PORT=60141 export MDX=docs export NEXT_PUBLIC_LIBNAME="Poimandres" export NEXT_PUBLIC_LIBNAME_SHORT="pmndrs" export NEXT_PUBLIC_LIBNAME_DOTSUFFIX_LABEL="docs" export NEXT_PUBLIC_LIBNAME_DOTSUFFIX_HREF="https://docs.pmnd.rs" export BASE_PATH= export DIST_DIR= export OUTPUT= export HOME_REDIRECT= export MDX_BASEURL=http://localhost:$_PORT export SOURCECODE_BASEURL="vscode://file$(pwd)" export EDIT_BASEURL="vscode://file$(pwd)/docs" export NEXT_PUBLIC_URL= export ICON= export LOGO=gutenberg.jpg export GITHUB=https://github.com/pmndrs/docs export DISCORD=https://discord.com/channels/740090768164651008/1264328004172255393 export THEME_PRIMARY="#323e48" export THEME_SCHEME="tonalSpot" export THEME_CONTRAST="0" export THEME_NOTE="#1f6feb" export THEME_TIP="#238636" export THEME_IMPORTANT="#8957e5" export THEME_WARNING="#d29922" export THEME_CAUTION="#da3633" export CONTRIBUTORS_PAT= kill $(lsof -ti:"$_PORT") npx serve $MDX -p $_PORT --no-port-switching --no-clipboard & pnpm run dev & wait ) ``` Then go to: http://localhost:3000 > [!TIP] > If `HOME_REDIRECT=` empty, `/` will not redirect, and instead displays an index of libraries. ### build ```sh $ ( trap 'kill -9 0' SIGINT rm -rf out export _PORT=60141 export MDX=docs export NEXT_PUBLIC_LIBNAME="Poimandres" export NEXT_PUBLIC_LIBNAME_SHORT="pmndrs" export NEXT_PUBLIC_LIBNAME_DOTSUFFIX_LABEL="docs" export NEXT_PUBLIC_LIBNAME_DOTSUFFIX_HREF="https://docs.pmnd.rs" export BASE_PATH= export DIST_DIR= export OUTPUT=export export HOME_REDIRECT=/getting-started/introduction export MDX_BASEURL=http://localhost:$_PORT export SOURCECODE_BASEURL= export EDIT_BASEURL= export NEXT_PUBLIC_URL= export ICON= export LOGO=gutenberg.jpg export GITHUB=https://github.com/pmndrs/docs export DISCORD=https://discord.com/channels/740090768164651008/1264328004172255393 export THEME_PRIMARY="#323e48" export THEME_SCHEME="tonalSpot" export THEME_CONTRAST="0" export THEME_NOTE="#1f6feb" export THEME_TIP="#238636" export THEME_IMPORTANT="#8957e5" export THEME_WARNING="#d29922" export THEME_CAUTION="#da3633" export CONTRIBUTORS_PAT= pnpm run build kill $(lsof -ti:"$_PORT") npx serve $MDX -p $_PORT --no-port-switching --no-clipboard & npx serve out & wait ) ``` http://localhost:3000 ### Docker ```sh $ docker build -t pmndrs-docs . ``` ```sh $ cd ~/code/pmndrs/react-three-fiber $ ( trap 'kill -9 0' SIGINT export _PORT=60141 export MDX=docs export NEXT_PUBLIC_LIBNAME="React Three Fiber" export NEXT_PUBLIC_LIBNAME_SHORT="r3f" export NEXT_PUBLIC_LIBNAME_DOTSUFFIX_LABEL="docs" export NEXT_PUBLIC_LIBNAME_DOTSUFFIX_HREF="https://docs.pmnd.rs" export BASE_PATH=/toto export DIST_DIR="$MDX/out$BASE_PATH" export OUTPUT=export export HOME_REDIRECT=/getting-started/introduction export MDX_BASEURL=http://localhost:$_PORT export SOURCECODE_BASEURL= export EDIT_BASEURL= export NEXT_PUBLIC_URL= export ICON=🇨🇭 export LOGO=/logo.png export GITHUB=https://github.com/pmndrs/react-three-fiber export DISCORD=https://discord.com/channels/740090768164651008/740093168770613279 export THEME_PRIMARY="#323e48" export THEME_SCHEME="tonalSpot" export THEME_CONTRAST="0" export THEME_NOTE="#1f6feb" export THEME_TIP="#238636" export THEME_IMPORTANT="#8957e5" export THEME_WARNING="#d29922" export THEME_CAUTION="#da3633" export CONTRIBUTORS_PAT= rm -rf "$MDX/out" docker run --rm --init -it \ -v "./$MDX":/app/docs \ -e MDX \ -e NEXT_PUBLIC_LIBNAME \ -e NEXT_PUBLIC_LIBNAME_SHORT \ -e NEXT_PUBLIC_LIBNAME_DOTSUFFIX_LABEL \ -e NEXT_PUBLIC_LIBNAME_DOTSUFFIX_HREF \ -e BASE_PATH \ -e DIST_DIR \ -e OUTPUT \ -e HOME_REDIRECT \ -e MDX_BASEURL \ -e SOURCECODE_BASEURL \ -e EDIT_BASEURL \ -e NEXT_PUBLIC_URL \ -e ICON \ -e LOGO \ -e GITHUB \ -e DISCORD \ -e THEME_PRIMARY \ -e THEME_SCHEME \ -e THEME_CONTRAST \ -e THEME_NOTE \ -e THEME_TIP \ -e THEME_IMPORTANT \ -e THEME_WARNING \ -e THEME_CAUTION \ -e CONTRIBUTORS_PAT \ pmndrs-docs pnpm run build kill $(lsof -ti:"$_PORT") npx serve $MDX -p $_PORT --no-port-switching --no-clipboard & npx -y serve "$MDX/out" & wait ) ``` Then go to: http://localhost:3000 ## Agents As alternate content, we provide you [llms.txt](/llms.txt) and [llms-full.txt](/llms-full.txt). These URLs are linked in the HTML header as: ```html <link rel="alternate" type="text/plain" href="/llms.txt" /> <link rel="alternate" type="text/plain" href="/llms-full.txt" /> ``` ## MCP Server ```sh $ npx -y @modelcontextprotocol/inspector ``` URL: /authoring/introduction Description: How to write documentation <Intro> This is a guide on how to write documentation. We support all [GFM](https://github.github.com/gfm/) syntax, plus some custom components that are described here. </Intro> <Keypoints> <KeypointsItem>[Front matter](#frontmatter) metadatas</KeypointsItem> <KeypointsItem>Custom [markdown](#markdown) components</KeypointsItem> </Keypoints> In your `MDX` folder, create any `path/to/my-document.mdx`: ```md --- 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) > [!TIP] > > `title` and `description` support markdown: > > ```yaml > --- > 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](https://tailwindcss.com) support: ```md <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: <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> > [!TIP] > > We use [react-mcu](https://github.com/abernier/react-mcu) colors, eg: `text-on-surface-variant` above Plus: - any [GitHub Flavored Markdown](https://github.github.com/gfm/) syntax. - all exported [`components/mdx/index.tsx`](components/mdx/index.tsx) MDX components. See the following pages for detailed documentation on each custom component. URL: /authoring/intro Description: Introduction component for **documentation** pages with `code` and [links](#test) <Intro> Prominent introduction with rich markdown support. </Intro> Use at the top of the document, just after the frontmatter. ```md <Intro> This is an intro. Here you can write a long description of the article, longer than the frontmatter `description`, eventually with [links](#), lists, etc. Multiple paragraphs are also possible, or anything. </Intro> ``` result: <Intro> This is an intro. Here you can write a long description of the article, longer than the frontmatter `description`, eventually with [links](#), lists, etc. Multiple paragraphs are also possible, or anything. </Intro> URL: /authoring/keypoints Description: Keypoints component for highlighting main article topics <Intro> Highlights key takeaways as a visually distinct bulleted list. </Intro> Can be used after `Intro`, to list main points the article covers: one bullet per `KeypointsItem`. ```md <Keypoints title="What you'll learn"> <KeypointsItem>First item</KeypointsItem> <KeypointsItem>Second **item**</KeypointsItem> </Keypoints> ``` result: <Keypoints title="What you'll learn"> <KeypointsItem>First item</KeypointsItem> <KeypointsItem>Second **item**</KeypointsItem> </Keypoints> URL: /authoring/img Description: Using images in documentation <Intro> Display images using markdown or HTML syntax with automatic dimensions and relative path support. </Intro> Relative images are supported. Eg, inside your [`MDX`](introduction#configuration:~:text=MDX) folder: ```text {2} |-- authoring | |-- img.mdx <= relative to this article | `-- gutenberg.jpg ``` ```md --- title: Authoring --- ![](gutenberg.jpg) ``` result: ![](gutenberg.jpg) > [!TIP] > You are encouraged to use relative images, since dimensions are automatically added as `img[width][height]` attributes. > > For others, think about adding them to **prevent layout shift**. --- It is also possible to specify only one dimension (other is inferred from intrinsic ratio), eg: ```md <img src="gutenberg.jpg" height="200" /> ``` result: <img src="gutenberg.jpg" height="200" /> --- Although it is probably better to use CSS for this: ```md <img src="gutenberg.jpg" style={{width: 'auto', height: '10rem'}} /> ``` result: <img src="gutenberg.jpg" style={{width: 'auto', height: '10rem'}} /> > [!NOTE] > See [`MDX_BASEURL`](/getting-started/introduction#configuration:~:text=MDX_BASEURL) to understand how it is converted to a full URL. URL: /authoring/code Description: Code blocks with syntax highlighting and line numbers <Intro> Code blocks with syntax highlighting. </Intro> Line numbers/highlights are supported: ````md ```tsx {1,4-6} showLineNumbers type Props = {who: string} function Hi({who}: Props) { return ( <p>Hello, {who}!</p> ) } ``` ```` result: ```tsx {1,4-6} showLineNumbers type Props = {who: string} function Hi({who}: Props) { return ( <p>Hello, {who}!</p> ) } ``` --- You can start at a specific `X` line number `showLineNumbers=X`: ````md ```tsx {1,4-6} showLineNumbers=150 type Props = {who: string} function Hi({who}: Props) { return ( <p>Hello, {who}!</p> ) } ``` ```` result: ```tsx {1,4-6} showLineNumbers=150 type Props = {who: string} function Hi({who}: Props) { return ( <p>Hello, {who}!</p> ) } ``` --- `diff` format is supported: ````md ```diff diff --git a/example.txt b/example.txt index 8c3317a..47ea956 100644 --- a/example.txt +++ b/example.txt @@ -1,4 +1,4 @@ -Hello, World! +Hello, GitHub World! Here are some changes: -This line will be modified. +This line has been modified. This line will stay the same. ``` ```` result: ```diff diff --git a/example.txt b/example.txt index 8c3317a..47ea956 100644 --- a/example.txt +++ b/example.txt @@ -1,4 +1,4 @@ -Hello, World! +Hello, GitHub World! Here are some changes: -This line will be modified. +This line has been modified. This line will stay the same. ``` URL: /authoring/mermaid Description: Creating diagrams with Mermaid <Intro> [Mermaid](https://mermaid.js.org/) text-based diagrams. Automatically adapt to light/dark theme. </Intro> ````md ```mermaid graph TD A[Start] --> B{Is it working?} B -->|Yes| C[Great!] B -->|No| D[Debug] D --> B C --> E[End] ``` ```` result: ```mermaid graph TD A[Start] --> B{Is it working?} B -->|Yes| C[Great!] B -->|No| D[Debug] D --> B C --> E[End] ``` --- ````md ```mermaid sequenceDiagram participant User participant Browser User->>Browser: Click button Browser-->>User: Display result ``` ```` result: ```mermaid sequenceDiagram participant User participant Browser User->>Browser: Click button Browser-->>User: Display result ``` --- [KaTeX support](https://github.com/mermaid-js/mermaid/pull/2885): ````md ```mermaid graph LR A["$$f(\relax{x}) = \int_{-\infty}^\infty \hat{f}(\xi)\,e^{2 \pi i \xi x}\,d\xi$$"] -->|"$$\Bigg(\bigg(\Big(\big((\frac{-b\pm\sqrt{b^2-4ac}}{2a})\big)\Big)\bigg)\Bigg)$$"| B("$$1+\frac{e^{-2\pi}} {1+\frac{e^{-4\pi}} {1+\frac{e^{-6\pi}} {1+\frac{e^{-8\pi}} {1+\cdots}}}}$$") A -->|"$$\overbrace{a+b+c}^{\text{note}}$$"| C("$$\phase{-78^\circ}$$") B --> D("$$x = \begin{cases} a &\text{if } b \\ c &\text{if } d \end{cases}$$") C --> E("$$x(t)=c_1\begin{bmatrix}-\cos{t}+\sin{t}\\ 2\cos{t} \end{bmatrix}e^{2t}$$") ``` ```` result: ```mermaid graph LR A["$$f(\relax{x}) = \int_{-\infty}^\infty \hat{f}(\xi)\,e^{2 \pi i \xi x}\,d\xi$$"] -->|"$$\Bigg(\bigg(\Big(\big((\frac{-b\pm\sqrt{b^2-4ac}}{2a})\big)\Big)\bigg)\Bigg)$$"| B("$$1+\frac{e^{-2\pi}} {1+\frac{e^{-4\pi}} {1+\frac{e^{-6\pi}} {1+\frac{e^{-8\pi}} {1+\cdots}}}}$$") A -->|"$$\overbrace{a+b+c}^{\text{note}}$$"| C("$$\phase{-78^\circ}$$") B --> D("$$x = \begin{cases} a &\text{if } b \\ c &\text{if } d \end{cases}$$") C --> E("$$x(t)=c_1\begin{bmatrix}-\cos{t}+\sin{t}\\ 2\cos{t} \end{bmatrix}e^{2t}$$") ``` URL: /authoring/grid Description: Responsive grid layout component > [!CAUTION] > > Deprecated, use [tailwind `grid-cols-*`](https://tailwindcss.com/docs/grid-template-columns) instead. <Intro> Responsive grid layout. </Intro> ```md <Grid cols={2}> <li>A</li> <li>B</li> <li>C</li> <li>D</li> <li>E</li> <li>F</li> <li>G</li> </Grid> ``` result: <Grid cols={2}> <li>A</li> <li>B</li> <li>C</li> <li>D</li> <li>E</li> <li>F</li> <li>G</li> </Grid> URL: /authoring/sandpack Description: Inline sandboxes for interactive code examples <Intro> Interactive code sandboxes powered by CodeSandbox. </Intro> > [!NOTE] > See Sandpack [official documentation](https://sandpack.codesandbox.io/docs/getting-started/usage) for full usage. ```tsx <Sandpack template="react-ts" customSetup={{ dependencies: { 'three': 'latest', '@react-three/fiber': 'latest', '@react-three/drei': 'latest' }, }} files={{ '/styles.css': `html,body,#root {height:100%;margin:unset;}`, '/App.tsx': `import { Canvas } from '@react-three/fiber' import { Cloud, CameraControls } from '@react-three/drei' export default function App() { return ( <Canvas camera={{position: [0,-13,0]}}> <Cloud speed={.4} growth={6} /> <ambientLight intensity={Math.PI} /> <CameraControls /> </Canvas> ) }`, }} /> ``` result: <Sandpack template="react-ts" customSetup={{ dependencies: { 'three': 'latest', '@react-three/fiber': 'latest', '@react-three/drei': 'latest' }, }} files={{ '/styles.css': `html,body,#root {height:100%;margin:unset;}`, '/App.tsx': `import { Canvas } from '@react-three/fiber' import { Cloud, CameraControls } from '@react-three/drei' export default function App() { return ( <Canvas camera={{position: [0,-13,0]}}> <Cloud speed={.4} growth={6} /> <ambientLight intensity={Math.PI} /> <CameraControls /> </Canvas> ) }`, }} /> > [!TIP] > Sandpack UI SSR-rendering[^1] is also supported (out of the box). [^1]: https://sandpack.codesandbox.io/docs/guides/ssr#nextjs-app-dir #### `Sandpack[folder]` Instead of `files`, a `folder` prop allows you to pass a folder containing all the files: ```tsx <Sandpack template="react-ts" folder="authoring-sandpack-cloud" /> ``` `folder` path is relative to the `.mdx` file: ```text |-- getting-started | |-- authoring.mdx <= relative to this article | `-- authoring-sandpack-cloud <= the folder ``` > [!TIP] > It will simply: > - build the `files` prop for you (including all `.{js|ts|jsx|tsx|css}` it finds) > - build `customSetup.dependencies` from `package.json` if it exists result: <Sandpack template="react-ts" folder="authoring-sandpack-cloud" /> --- It is also possible to pass some individual [file format](https://sandpack.codesandbox.io/docs/getting-started/usage#file-format) configuration: ```tsx <Sandpack template="react-ts" folder="authoring-sandpack-cloud" files={{ '/App.tsx': { readOnly: true, active: true, }, '/styles.css': { hidden: true } }} /> ``` result: <Sandpack template="react-ts" folder="authoring-sandpack-cloud" files={{ '/App.tsx': { readOnly: true, active: true, }, '/styles.css': { hidden: true } }} /> #### `Sandpack[fileExplorer]` ```tsx <Sandpack template="react-ts" folder="authoring-sandpack-cloud" fileExplorer /> ``` result: <Sandpack template="react-ts" folder="authoring-sandpack-cloud" fileExplorer /> > [!TIP] > Conveniently, enabling `fileExplorer` will by default `[codeEditor={showTabs: false}]`. > You can override it with [`[codeEditor]` options](#sandpack[codeeditor]) --- You can also pass [any `fileExplorer={options: ComponentProps<SandpackFileExplorer>}`](https://sandpack.codesandbox.io/docs/advanced-usage/components#file-explorer:~:text=Preview-,Options,-If%20you%27re%20looking). #### `Sandpack[codeEditor]` You can pass [any `codeEditor={options: ComponentProps<SandpackCodeEditor>}`](https://sandpack.codesandbox.io/docs/advanced-usage/components#code-editor:~:text=Preview-,Options,-Extensions). #### `Sandpack[codeViewer]` It will render the [`SandpackCodeViewer`](https://sandpack.codesandbox.io/docs/advanced-usage/components#code-viewer) instead of the default [`SandpackCodeEditor`](https://sandpack.codesandbox.io/docs/advanced-usage/components#code-editor). ```tsx <Sandpack template="react-ts" folder="authoring-sandpack-cloud" codeViewer /> ``` result: <Sandpack template="react-ts" folder="authoring-sandpack-cloud" codeViewer /> You can also pass [any `codeViewer={options: ComponentProps<SandpackCodeViewer>}`](https://sandpack.codesandbox.io/docs/advanced-usage/components#code-viewer:~:text=Preview-,Options,-CodeMirror%20decorations). ##### `Sandpack[codeViewer][filesDecorators]` You can define per-file [decorators](https://sandpack.codesandbox.io/docs/advanced-usage/components#codemirror-decorations) through `filesDecorators` prop: ```tsx <Sandpack template="react-ts" folder="authoring-sandpack-cloud" codeViewer={{ filesDecorators: { '/App.tsx': [ { className: "highlight", line: 1 }, { className: "highlight", line: 7 }, { className: "widget", elementAttributes: { "data-id": "1" }, line: 7, startColumn: 13, endColumn: 24, }, { className: "widget", elementAttributes: { "data-id": "2" }, line: 7, startColumn: 25, endColumn: 35, }, ], '/styles.css': [ { className: "highlight", line: 4 }, ] } }} /> ``` result: <Sandpack template="react-ts" folder="authoring-sandpack-cloud" codeViewer={{ filesDecorators: { '/App.tsx': [ { className: "highlight", line: 1 }, { className: "highlight", line: 7 }, { className: "widget", elementAttributes: { "data-id": "1" }, line: 7, startColumn: 13, endColumn: 24, }, { className: "widget", elementAttributes: { "data-id": "2" }, line: 7, startColumn: 25, endColumn: 35, }, ], '/styles.css': [ { className: "highlight", line: 4 }, ] } }} /> #### `Sandpack[preview]` You can pass [any `preview={options: ComponentProps<SandpackPreview>}`](https://sandpack.codesandbox.io/docs/advanced-usage/components#preview:~:text=Preview-,Options,-Additional%20buttons). URL: /authoring/codesandbox Description: Embed Codesandbox examples <Intro> Embed live CodeSandbox examples. </Intro> ```md <Codesandbox id="3rjsl" title="Cell fracture" /> ``` result: <Codesandbox id="3rjsl" title="Cell fracture" /> URL: /authoring/gha Description: GitHub-style alerts and callouts <Intro> GitHub-style alerts with multiple severity levels. </Intro> Aka. ["GitHub alerts"](https://github.com/orgs/community/discussions/16925) ```md <Gha keyword="NOTE">Highlights information that users should take into account, even when skimming.</Gha> ``` or better: ```md > [!NOTE] > Highlights information that users should take into account, even when skimming. ``` result: > [!NOTE] > Highlights information that users should take into account, even when skimming. --- We also support: `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, `[!CAUTION]` result: > [!TIP] > Optional information to help a user be more successful. > [!IMPORTANT] > Crucial information necessary for users to succeed. > [!WARNING] > Critical content demanding immediate user attention due to potential risks. > [!CAUTION] > Negative potential consequences of an action. URL: /authoring/hint Description: Deprecated hint component > [!CAUTION] > Deprecated, use [`Gha[keyword="NOTE"]`](gha) instead. ```md <Hint> I'm a deprecated hint. Use `Gha` instead. </Hint> ``` result: <Hint>I'm a deprecated hint. Use `Gha` instead.</Hint> URL: /authoring/contributors Description: Display repository contributors <Intro> Display GitHub repository contributors. </Intro> ```md <Contributors owner="pmndrs" repo="docs" /> ``` > [!WARNING] > [`CONTRIBUTORS_PAT`](introduction#configuration:~:text=CONTRIBUTORS_PAT) needs to be set. Otherwise, it will display John Doe. result: <Contributors owner="pmndrs" repo="docs" /> URL: /authoring/backers Description: Display project backers <Intro> Display Open Collective backers. </Intro> ```md <Backers repo="react-three-fiber" /> ``` result: <Backers repo="react-three-fiber" /> URL: /authoring/entries Description: Display a grouped directory listing of documentation pages <Intro> Displays all documentation entries in a multi-column layout, grouped by category. </Intro> The `Entries` component automatically generates a directory listing of all documentation pages in the site, organized by their top-level category (first segment of the slug). ```md <Entries /> ``` result: <Entries /> > [!TIP] > When a page includes a `<CodeSandbox>` component, the Entries listing will automatically display its thumb next to that page's link. URL: /github-actions/introduction Description: Call from your CI <Intro> This project provides a [`build.yml` reusable workflow](https://docs.github.com/en/actions/sharing-automations/reusing-workflows#calling-a-reusable-workflow) you can easily call from your own project workflow. </Intro> In your `.github/workflows` folder, create a eg. `docs.yml` file: ```yml uses: pmndrs/docs/.github/workflows/build.yml@v2 with: mdx: 'docs' libname: 'React Three Fiber' libname_short: 'r3f' libname_dotsuffix_label: "docs" libname_dotsuffix_href: "https://docs.pmnd.rs" home_redirect: '/getting-started/introduction' icon: '🇨🇭' logo: '/logo.png' github: 'https://github.com/pmndrs/react-three-fiber' discord: 'https://discord.com/channels/740090768164651008/740093168770613279' theme_primary: '#323e48' theme_scheme: 'tonalSpot' theme_contrast: '0' theme_note: '#1f6feb' theme_tip: '#238636' theme_important: '#8957e5' theme_warning: '#d29922' theme_caution: '#da3633' ``` See [`pmndrs/react-three-fiber/.github/workflows/docs.yml`](https://github.com/pmndrs/react-three-fiber/blob/master/.github/workflows/docs.yml) for an example implementation.