Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[docs] Tighten up wording & structure of Usage page #1624

Merged
merged 5 commits into from
Jun 20, 2023
Merged

[docs] Tighten up wording & structure of Usage page #1624

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
8fcaa26
make Usage example the same as Introduction example
TodePond Jun 20, 2023
fe512b7
wording pass on Usage docs
TodePond Jun 20, 2023
25fb515
restructure Usage docs page
TodePond Jun 20, 2023
7fe0a8f
change double negative to positive
TodePond Jun 20, 2023
4fa9ae5
Update usage.mdx
steveruizok Jun 20, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
22 changes: 9 additions & 13 deletions apps/docs/content/docs/usage.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,13 @@ date: 3/22/2023
order: 2
---

The `<Tldraw/>` component is the easiest way to get started with tldraw. It combines several lower-level libraries: the `TldrawEditor` component from `@tldraw/editor` and the `TldrawUi` component from `@tldraw/ui`.

To use the `<Tldraw/>` component, create a file like this one:
The `<Tldraw>` component is the easiest way to get started. To use it, create a file like this one:
Copy link
Collaborator Author

@TodePond TodePond Jun 20, 2023 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a bigger edit. I think it's good to get straight to the action here, rather than distract/confuse with info about why it's the best. (We mention it again lower on this page, instead)

Happy to be overuled on this one though


```tsx
import { Tldraw } from '@tldraw/tldraw'
import '@tldraw/tldraw/tldraw.css'

export default function TldrawExample() {
export default function () {
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed this so it's the same as the one on the Introduction page. If it's different, people might think that it's different for a specific reason. If we want to keep the function name, we should add one to the Introduction page too, so that it's consistent.

return (
<div style={{ position: 'fixed', inset: 0 }} >
<Tldraw />
Expand All @@ -25,28 +23,26 @@ export default function TldrawExample() {

### CSS

In order to use the `<Tldraw/>` component, you should also import the `tldraw.css` file from the `@tldraw/tldraw` library. You can alternatively import this file inside of another CSS file using the `@import` syntax.
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.
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed library to package to match some recent changes that I've done elsewhere. I think there is one tldraw library, which contains multiple packages. It's one very good product, with multiple parts. Not lots of little products.

Also, throughout this file, I'm changing components from
<Tldraw/> to <Tldraw>

I think it's more readable, and it's consistent with the Introduction page.
I do think it's good to write in as a component though! It reminds people that it's just a React component.


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 updte your `index.html`'s meta viewport element as shown below.
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.
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minor typo


```html
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
```

This change may not be critical to `<Tldraw/>` performing correctly, however some features (such as safe area positioning) will not work correctly if these viewport options are not set.

## Server rendering

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 will need to import it dynamically. Check the [examples repository](https://github.com/tldraw/examples) to see examples.
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.
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed a double-negative to a positive.
Still a bit wordy though! any ideas?


## Using in Next.js, Create React App, Vite, etc.

Check the [examples repository](https://github.com/tldraw/examples) to see examples of the tldraw component being used in various frameworks.
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.
Comment on lines 40 to +44
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I combined some repeated info together for clarity and conciseness.


## Going deeper

If you wanted to have more granular control, you could also 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.
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.