tldraw/apps/docs
alex 6cb797a074
Better generated docs for react components (#3930)
Before:
![Screenshot 2024-06-12 at 12 57
26](https://github.com/tldraw/tldraw/assets/1489520/2a9f6098-ef2a-4f52-88f5-d6e4311c067d)

After:
![Screenshot 2024-06-12 at 12 59
16](https://github.com/tldraw/tldraw/assets/1489520/51733c2a-a2b4-4084-a89a-85bce5b47672)

React components in docs now list their props, and appear under a new
"Component" section instead of randomly under either `Function` or
`Variable`. In order to have our docs generate this, a few criteria need
to be met:
1. They need to be tagged with the `@react` tsdoc tag
2. Their props need to be a simple type alias, typically to an
interface.

Both of these rules are enforced with a new lint rule - any component
tagged as `@public` will have these rules enforced.

### Change Type

- [x] `docs` — Changes to the documentation, examples, or templates.
- [x] `improvement` — Improving existing features
2024-06-13 13:09:27 +00:00
..
app Better generated docs for react components (#3930) 2024-06-13 13:09:27 +00:00
components security: enforce use of our fetch function and its default referrerpolicy (#3884) 2024-06-11 13:59:25 +00:00
content Better generated docs for react components (#3930) 2024-06-13 13:09:27 +00:00
public [docs] design shuffle (#2951) 2024-02-29 16:28:45 +00:00
scripts Better generated docs for react components (#3930) 2024-06-13 13:09:27 +00:00
styles Add editor notes to the docs (#3832) 2024-06-04 12:01:10 +00:00
types Better generated docs for react components (#3930) 2024-06-13 13:09:27 +00:00
utils Better generated docs for react components (#3930) 2024-06-13 13:09:27 +00:00
.gitignore docs: rework docs site to have different sections (#2686) 2024-01-30 14:19:25 +00:00
.prettierignore docs: rework docs site to have different sections (#2686) 2024-01-30 14:19:25 +00:00
CHANGELOG.md Add docs (#2470) 2024-01-15 12:33:15 +00:00
content.d.ts Add docs (#2470) 2024-01-15 12:33:15 +00:00
LICENSE.md Add docs (#2470) 2024-01-15 12:33:15 +00:00
next-env.d.ts Add docs (#2470) 2024-01-15 12:33:15 +00:00
next.config.js docs: rework search UI (#2723) 2024-02-05 14:32:50 +00:00
package.json Add editor notes to the docs (#3832) 2024-06-04 12:01:10 +00:00
README.md Update READMEs, add form link (#3741) 2024-05-12 20:48:07 +00:00
tsconfig.content.json Add docs (#2470) 2024-01-15 12:33:15 +00:00
tsconfig.json use native structuredClone on node, cloudflare workers, and in tests (#3166) 2024-03-18 17:16:09 +00:00
watcher.ts [docs] Fix missing Persistence page (#2828) 2024-02-13 16:19:17 +00:00

tldraw-docs

tldraw

Welcome to the source for the tldraw docs site.

This site is a Next.js app that uses MDX for content. It contains human-written docs in the content folder as well as generated docs in the api folder.

We have several scripts that build these files into a SQLite database that is used to generate the site's pages.

To pull the most recent docs from the tldraw repo, create an .env file with a GitHub personal access token and the SHA of the commit or branch that you'd like to pull from.

ACCESS_TOKEN=your_github_access_token
SOURCE_SHA=main

The files are also provided in this repo.

Building the content

You can build the markdown and API content using the following scripts:

  • yarn refresh-everything to reset the database, generate the markdown from the API docs, and populate the database with articles from both the regular content and the generated API content
  • yarn refresh-content to generate just the regular content

Content

The docs has two types of content: regular content that is written by the team and auto-generated content that is created using tsdoc and API extractor.

The content folder contains all content in the form of MDX files. All articles belong to a "section" and a "category". The sections.json defines each section and any categories belonging to that section.

A section looks like this:

{
	"id": "community",
	"title": "Community",
	"description": "Guides for contributing to tldraw's open source project.",
	"categories": []
}

The content is organized into folders for each section. The gen folder contains auto-generated content.

Regular Content

The content folder contains all "regular" content in the form of MDX files.All articles belong to a "section" and a "category". The content is organized into folders for each "section".

An article's frontmatter looks like this:

---
title: User Interface
description: How to customize the tldraw user interface using overrides.
status: published
author: steveruizok
date: 3/22/2023
order: 8
keywords:
  - ui
  - interface
  - tools
  - shapes
  - custom
  - button
  - toolbar
  - styles
---

Title

The title is displayed in the article's header, in the page title, in the search bar, and in search results. It is used to find an article through the site's search feature.

Description

The description is hidden in the article's frontmatter, but is used to populate the article's meta description tag. It is also used to find an article through the site's search feature.

Hero

The hero is used for the article's social media image. It is not displayed in the article. It should refer to a page in the public/images folder.

Category

An article may declare its category in its frontmatter. Any article that does not declare a category will be placed into the "ucg" category for "uncategorized" articles.

Order

The order property defines the article's order in its category. Uncategorized articles are placed at the end of the list of categories sorted by its order. For a section without categories, the order keyword effectively defines the order that the article will appear in the section list.

Author

The author must refer to an author named in the content/authors.json file.

An author looks like this:

"steveruizok": {
	"name": "Steve Ruiz",
	"email": "steve@tldraw.com",
	"twitter": "steveruizok",
	"image": "steve_ruiz.jpg"
}

The image should refer to an image in public/avatars.

Date

The date is formatted as DD/MM/YYYY.

Status

An article's status may be either draft or published. A draft article is hidden in production.

Keywords

The keywords are used to find an article through the site's search feature.

Auto-generated content

The auto-generated docs content is created using tsdoc and API extractor. The source is the API documentation created by yarn build or yarn build-api. The output is placed in the gen folder.

Developing the docs

When developing the docs, any change to the content folder will cause the page to refresh. This is a little shitty but it mostly works.

Contribution

Please see our contributing guide. Found a bug? Please submit an issue.

License

The tldraw source code and its distributions are provided under the tldraw license. This license does not permit commercial use. To purchase a commercial license or learn more, please fill out this form.

Trademarks

Copyright (c) 2023-present tldraw Inc. The tldraw name and logo are trademarks of tldraw. Please see our trademark guidelines for info on acceptable usage.

Contact

Find us on Twitter/X at @tldraw.

Community

Have questions, comments or feedback? Join our discord or start a discussion. For the latest news and release notes, check out our Substack.