29044867dd
This PR adds the docs app back into the tldraw monorepo. ## Deploying We'll want to update our deploy script to update the SOURCE_SHA to the newest release sha... and then deploy the docs pulling api.json files from that release. We _could_ update the docs on every push to main, but we don't have to unless something has changed. Right now there's no automated deployments from this repo. ## Side effects To make this one work, I needed to update the lock file. This might be ok (new year new lock file), and everything builds as expected, though we may want to spend some time with our scripts to be sure that things are all good. I also updated our prettier installation, which decided to add trailing commas to every generic type. Which is, I suppose, [correct behavior](https://github.com/prettier/prettier-vscode/issues/955)? But that caused diffs in every file, which is unfortunate. ### Change Type - [x] `internal` — Any other changes that don't affect the published package[^2]
150 lines
5.5 KiB
Markdown
150 lines
5.5 KiB
Markdown
# tldraw-docs
|
|
|
|
<div alt style="text-align: center; transform: scale(.5);">
|
|
<picture>
|
|
<img alt="tldraw" src="https://github.com/tldraw/tldraw-lite/raw/main/docs/public/card_repo.png" />
|
|
</picture>
|
|
</div>
|
|
|
|
Welcome to the source for the [tldraw docs site](https://tldraw.dev).
|
|
|
|
This site is a [Next.js](https://nextjs.org/) app that uses [MDX](https://mdxjs.com/) 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-all` 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-api-content` to refresh just the 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](https://tsdoc.org/) and [API extractor](https://api-extractor.com/).
|
|
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```md
|
|
---
|
|
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:
|
|
|
|
```json
|
|
"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](https://tsdoc.org/) and [API extractor](https://api-extractor.com/). 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](https://github.com/tldraw/tldraw/blob/main/CONTRIBUTING.md). Found a bug? Please [submit an issue](https://github.com/tldraw/tldraw/issues/new).
|
|
|
|
## License
|
|
|
|
The tldraw source code and its distributions are provided under the [tldraw license](https://github.com/tldraw/tldraw/blob/master/LICENSE.md). This license does not permit commercial use.
|
|
|
|
If you wish to use this project in commercial product, you need to purchase a commercial license. matPlease contact us at [hello@tldraw.com](mailto:hello@tldraw.com) for more inforion about obtaining a commercial license.
|
|
|
|
## Trademarks
|
|
|
|
Copyright (c) 2023-present tldraw Inc. The tldraw name and logo are trademarks of tldraw. Please see our [trademark guidelines](https://github.com/tldraw/tldraw/blob/main/TRANDEMARKS.md) for info on acceptable usage.
|
|
|
|
## Contact
|
|
|
|
Find us on Twitter at [@tldraw](https://twitter.com/tldraw) or email [hello@tldraw.com](mailto://hello@tldraw.com). You can also [join our discord](https://discord.gg/rhsyWMUJxd) for quick help and support.
|