Suggested v2 docs reorganization #3591
Description
There are some suggestions here for how the docs could be reorganized but they are a bit stream-of-consciousness and also contain mentions of some unexpected behaviour that should probably be fixed rather than documented.
After comparing the v2 docs to the v1 docs, I think the overarching problem is that the Concepts section gets too hung up on certain internals, rather than showing users how to build an app. There are now multiple ways of doing things (App.get vs define.page) and the docs tend to go off on tangents. For example, why are Middleware and Context mentioned before Routing and Islands? Which is more likely to be useful to more people?
I would suggest reorganizing as follows:
Basics
- Pages: using filesystem-based routing, leave all the discussion of route matching details and route groups for an advanced topic. Should explicitly mention that the JSX flavour is preact
- Handlers: (1) returning JSON with a file-based handler, and (2) combining Handlers and Pages to create dynamic html responses
- Islands: again, be explicit that this is Preact. Explicitly state that useEffect won't be executed serverside, illustrate the benefits of this. Current Islands page is pretty good, but the very first example introducing signals is confusing. For better or for worse
useStatewill be more familiar to the majority of readers. - Static files: should be explicit about the difference between files and assets, maybe show examples for CSS, fonts, and images
- Building and deployment (choose ONE method of deployment, the others can be discussed later)
Advanced
- The App object (go into route matching in detail). Talk about how fsRoutes and what it's for.
- Error handling
- Wrappers and Layouts
- Modifying the
<head> - Middleware
- Provided middleware (cors, csrf, etc)
- Context API
- Define API
- Testing
- Partials
- Vite plugin options
- Legacy Builder options
- Other deployment options
How do I...
- Request JSON from an island
- Share state between islands
- Modify HTTP headers
- Add a custom font
- Add a form: (1) server submission, (2) AJAX/progressive enhancement example
- Use React instead of Preact (actually not sure this is possible, but it seems to be a common request)
- Use CSS modules (is this possible? Seems like adding vite should unlock some of these options?)
- Anything else that is necessary, but I personally don't think it should go through everything you can do with Preact or Tailwind. Those projects have their own docs, and there's no need to duplicate them here or change them later
Migration Guide