# tldraw-docs
tldraw
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.