b373abf605
Adds descriptions to examples.  They show as a list on the index page, and on individual examples they show in a three-js style sidebar. For now, this is disabled completely on mobile. Examples can still be opened in 'standalone' mode to get rid of the sidebar. Note: the 'view code' link won't work until after these changes are merged. There's a small impact on authoring examples: each one needs to live in a folder with a README.md. At a minimum, the readme needs to look like this: ```md --- title: My Example component: ./MyExample.tsx --- Here is a 1-liner about my example ``` Optionally, you can: - Add `hide: true` to the frontmatter to remove the example from the list (you can skip the description this way) - Add `order: 3` to control the order in which the example appears. They're alphabetical otherwise - Add some more description or links to docs below a `---`. This won't show in the listing, but will be visible on GitHub and on the example page itself. As a follow-up, I'd like to add an 'Open in CodeSandbox' link to each example. These won't work until we've made a release with these examples (as our special examples codesandbox is tied to our release process) but the code is there & ready to go! Have a play, let me know what you think! ### Change Type - [x] `documentation` — Changes to the documentation only[^2] --------- Co-authored-by: Steve Ruiz <steveruizok@gmail.com>
101 lines
3.1 KiB
TypeScript
101 lines
3.1 KiB
TypeScript
import react from '@vitejs/plugin-react'
|
|
import path from 'path'
|
|
import { PluginOption, defineConfig } from 'vite'
|
|
|
|
export default defineConfig({
|
|
plugins: [react(), exampleReadmePlugin()],
|
|
root: path.join(__dirname, 'src'),
|
|
publicDir: path.join(__dirname, 'public'),
|
|
build: {
|
|
outDir: path.join(__dirname, 'dist'),
|
|
assetsInlineLimit: 0,
|
|
},
|
|
server: {
|
|
port: 5420,
|
|
},
|
|
clearScreen: false,
|
|
optimizeDeps: {
|
|
exclude: ['@tldraw/assets'],
|
|
},
|
|
define: {
|
|
'process.env.TLDRAW_ENV': JSON.stringify(process.env.VERCEL_ENV ?? 'development'),
|
|
},
|
|
})
|
|
|
|
function exampleReadmePlugin(): PluginOption {
|
|
return {
|
|
name: 'example-readme',
|
|
async transform(src, id) {
|
|
const match = id.match(/examples\/src\/examples\/(.*)\/README.md$/)
|
|
if (!match) return
|
|
|
|
const remark = (await import('remark')).remark
|
|
const remarkFrontmatter = (await import('remark-frontmatter')).default
|
|
const remarkHtml = (await import('remark-html')).default
|
|
const matter = (await import('vfile-matter')).matter
|
|
|
|
const file = await remark()
|
|
.use(remarkFrontmatter)
|
|
.use(remarkHtml)
|
|
.use(() => (_, file) => matter(file))
|
|
.process(src)
|
|
|
|
const frontmatter = parseFrontMatter(file.data.matter, id)
|
|
|
|
const separator = '\n<hr>\n'
|
|
const parts = String(file).split(separator)
|
|
const description = parts[0]
|
|
const details = parts.slice(1).join(separator)
|
|
const path = `/${match[1]}`
|
|
const codeUrl = `https://github.com/tldraw/tldraw/tree/main/apps/examples/src/examples${path}`
|
|
|
|
const result = [
|
|
`export const title = ${JSON.stringify(frontmatter.title)};`,
|
|
`export const order = ${JSON.stringify(frontmatter.order)};`,
|
|
`export const hide = ${JSON.stringify(frontmatter.hide)};`,
|
|
`export const description = ${JSON.stringify(description)};`,
|
|
`export const details = ${JSON.stringify(details)};`,
|
|
`export const codeUrl = ${JSON.stringify(codeUrl)};`,
|
|
`export const path = ${JSON.stringify(path)};`,
|
|
`export const componentFile = ${JSON.stringify(frontmatter.component)};`,
|
|
`import {lazy} from 'react';`,
|
|
`export const loadComponent = async () => {`,
|
|
` return (await import(${JSON.stringify(frontmatter.component)})).default;`,
|
|
`};`,
|
|
]
|
|
|
|
return result.join('\n')
|
|
},
|
|
}
|
|
}
|
|
|
|
function parseFrontMatter(data: unknown, fileName: string) {
|
|
if (!data || typeof data !== 'object') {
|
|
throw new Error(`Frontmatter missing in ${fileName}`)
|
|
}
|
|
|
|
if (!('title' in data && typeof data.title === 'string')) {
|
|
throw new Error(`Frontmatter key 'title' must be string in ${fileName}`)
|
|
}
|
|
|
|
if (!('component' in data && typeof data.component === 'string')) {
|
|
throw new Error(`Frontmatter key 'component' must be string in ${fileName}`)
|
|
}
|
|
|
|
const order = 'order' in data ? data.order : null
|
|
if (order !== null && typeof order !== 'number') {
|
|
throw new Error(`Frontmatter key 'order' must be number in ${fileName}`)
|
|
}
|
|
|
|
const hide = 'hide' in data ? data.hide : false
|
|
if (hide !== false && hide !== true) {
|
|
throw new Error(`Frontmatter key 'hide' must be boolean in ${fileName}`)
|
|
}
|
|
|
|
return {
|
|
title: data.title,
|
|
component: data.component,
|
|
order,
|
|
hide,
|
|
}
|
|
}
|