[docs] Separate some pages out of the Docs section (#1626)

This PR changes the structure of the docs site's sidebar.


![image](https://github.com/tldraw/tldraw/assets/15892272/ffe1e152-c921-43f0-9ba2-d084bda5e1e3)

I think this signposts more clearly what the different pages are for.
And it also paves the way for some work I want to do on
expanding+refining the Editor docs.

This PR also simplifies URL for all sidebar links.
It's a bit scrappy, but I think it feels simple enough to work with, and
easy-enough to change in the future.
> But hey! I've been doing this a couple times recently. Maybe we should
refactor? Or maybe we should keep going with what we've got and focus on
getting these docs *done*.

### Change Type

- [x] `documentation` — Changes to the documentation only[^2]

[^1]: publishes a `patch` release, for devDependencies use `internal`
[^2]: will not publish a new version

### Test Plan

1. Check that all the sidebar links go to where you expect.
2. Check that old URLs redirect to the right pages, eg: `/docs/usage`
should go to the usage page.


### Release Notes

- Documentation: Restructured the sidebar for clarity.
This commit is contained in:
Lu Wilson 2023-06-23 10:53:22 +01:00 committed by GitHub
parent d2c51ae3ba
commit c5fe399842
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
9 changed files with 119 additions and 36 deletions

View file

@ -0,0 +1,29 @@
---
title: Installation
status: published
author: steveruizok
date: 3/22/2023
order: 1
---
At the moment the `@tldraw/tldraw` package is in alpha. We also ship a canary version which is always up to date with the main branch of tldraw [repository](https://github.com/tldraw/tldraw).
## Alpha
First, install the `@tldraw/tldraw` package using `@alpha` for the latest.
```bash
yarn add @tldraw/tldraw@alpha
# or
npm install @tldraw/tldraw@alpha
```
## Canary
To get the very latest version, use the [latest canary release](https://www.npmjs.com/package/@tldraw/tldraw?activeTab=versions). Docs for the very latest version are also available at [canary.tldraw.dev](https://canary.tldraw.dev).
```bash
yarn add @tldraw/tldraw@canary
# or
npm install @tldraw/tldraw@canary
```

View file

@ -0,0 +1,50 @@
---
title: Introduction
status: published
author: steveruizok
date: 3/22/2023
order: 0
---
Welcome to the tldraw developer docs.
Here at tldraw, we make two things: a very good multiplayer whiteboard (at [tldraw.com](https://tldraw.com)), and the [open source library](https://github.com/tldraw/tldraw) that powers it. This page provides documentation and reference for that open source library.
```tsx
import { Tldraw } from '@tldraw/tldraw'
import '@tldraw/tldraw/tldraw.css'
export default function () {
return (
<div style={{ position: 'fixed', inset: 0 }}>
<Tldraw />
</div>
)
}
```
You can use the `<Tldraw>` React component to build on top of the default tldraw experience. It's easy to use and easy to extend with your own [custom shapes](/docs/shapes), [custom tools](/docs/tools), and [user interface](/docs/user-interface) overrides.
You can also use the [Editor API](/docs/editor) to create, update, and delete shapes, control the camera, or do just about anything else.
If you want to go even deeper, you can use the `<TldrawEditor>` component as a more minimal engine without the default tldraw shapes or user interface.
Best of all, you can easily plug tldraw into the [collaboration backend](/docs/collaboration) of your choice.
- Want to explore the code? Visit the [GitHub repo](https://github.com/tldraw/tldraw).
- Want to try it out? Visit the [examples sandbox](https://stackblitz.com/github/tldraw/tldraw/tree/examples?file=src%2F1-basic%2FBasicExample.tsx).
Otherwise, continue on to the [installation](/docs/installation) and [usage](/docs/usage) guides.
## Community
Found a bug or want to request a feature? Create an issue [here](https://github.com/tldraw/tldraw/issues). To connect with the team and other users, join us on our [Discord](https://discord.gg/JMbeb96jsh).
If you spot an issue with these docs, please use the links at the bottom of each page to suggest a change.
## License
Our open source libraries are licensed and distributed under Apache-2.0.
Our plan is to keep these libraries permissively licensed while we develop a commercial offering for teams who want more from tldraw. If you're planning to use use tldraw in a commercial product, please reach out at [hello@tldraw.com](mailto://hello@tldraw.com).

View file

@ -0,0 +1,48 @@
---
title: Usage
status: published
author: steveruizok
date: 3/22/2023
order: 2
---
The `<Tldraw>` component is the easiest way to get started. To use it, create a file like this one:
```tsx
import { Tldraw } from '@tldraw/tldraw'
import '@tldraw/tldraw/tldraw.css'
export default function () {
return (
<div style={{ position: 'fixed', inset: 0 }} >
<Tldraw />
</div>
)
}
```
### CSS
In order to use the `<Tldraw>` component, you should also import the `tldraw.css` file from the `@tldraw/tldraw` package. You can alternatively import this file inside of another CSS file using the `@import` syntax.
You can overwrite these files with other CSS or copy the contents into a different file and import that instead.
### HTML
If you're using the `<Tldraw>` component in a full-screen app, you probably also want to update your `index.html`'s meta viewport element as shown below.
```html
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
```
This may not be critical to `<Tldraw>` performing correctly, however some features (such as safe area positioning) will only work correctly if these viewport options are set.
## Using in Next.js, Create React App, Vite, etc.
Check the [examples repository](https://github.com/tldraw/examples) to see examples of tldraw being used in various frameworks.
By the way, the `<Tldraw>` component can't be server-rendered. If you're using the component in a server-rendered framework (such as Next.js) then you need to import it dynamically.
## Going deeper
The `<Tldraw>` component combines two lower-level components: `<TldrawEditor>` and `<TldrawUi>`. If you want to have more granular control, you can use those lower-level components directly. See [this example](https://github.com/tldraw/tldraw/blob/main/apps/examples/src/5-exploded/ExplodedExample.tsx) for reference.