Documentation

[ChristopherBiscardi]

There are no public docs at the moment. There are a few example sites around but we could make them more usable, discoverable, etc. Great documentation is a requirement before going GA. It is ok for the beta because we can help people in Discord, etc.

This issue needs to be broken down into more issues

[maxcell]

Things that would be worth documenting in one location:

• Any important folder structuring or files worth noting? (src/pages/* + toast.js)
• APIs (setDataForSlug)
• Setting up a project with a starter
• Troubleshooting (?)
  • This might not be necessary given that you've done work to embed how to get help within the errors themselves

Edit:

• yarn create toast as a quickstart

[maxcell]

I think similar to https://mdxjs.org, it would be nifty to have a set of guides around the extra tooling you provide/patterns that emerge from the ecosystem.

If you wanted more folks to contribute to the rust side of toast I think there may be something separate you'd want (docs.rs for example) but also it could be some Architectural document potentially.

[maxcell]

If you wanted a set of sections written out, where would you be interested in having them? Maybe just a Markdown file as a PR to start and maybe another PR towards a more formal page in the www site?

[ChristopherBiscardi]

I've been thinking about this a bit lately.

The path forward is probably going to be put them in a root docs/ directory in toastdotdev/toast.

Then www.toast.dev will pull in the main branch and the latest release to render. This gives us documentation for every version (bread is released on merge), and also the releases (toast is released on changeset merge).

so the URLs on the toast site will be something like

toast.dev/docs/<version>/<files-in-docs>
toast.dev/docs/bread/files-in-docs

where version is either semver or a redirect from latest to the most recent release.

[ChristopherBiscardi]

Seems like we end up with something like this for now

.
├── api
│   └── toastfile.mdx
├── api.mdx
├── getting-started
├── getting-started.mdx
├── guides
│   ├── beef.mdx
│   └── setting-up-mdx.mdx
├── guides.mdx
└── troubleshooting.mdx

[ChristopherBiscardi]

Guides: Adding client-side only functionality

• dealing with authentication-restricted content
• dynamically loading Preact components on the client (as seen in the mdx example)