denoland
Suggested v2 docs reorganization
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
Great analysis! I pretty much agree on all mentioned points.
Use React instead of Preact
Not possible and it's unlikely to happen.
Use CSS modules
Yup, this now works out of the box with vite.
Not possible and it's unlikely to happen.
Right, so maybe that page should be "How do I use my favourite React library"?
But this is even more reason to be clear from the start that Fresh is based on Preact.
Ooh, maybe there should be a page on what Fresh isn't (eg a static site generator, a SPA, a PWA)
@CAYdenberg can i take up this issue its interesting and i wanna contribute
@harshasiddartha I'm not on the team so it's not up to me, but it's marked "Good First Issue" so I'd imagine you can.
@brettchalupa and @mabasic might also have ideas on a docs-rewrite.
There is no need to ask if you can take an issue. PRs are always welcome.
Hi guys, feel free to tackle whatever you want. I did not have the time initially to create issues, and still don't have the time now to improve the docs and/or fix code. I'm working on a soon to be open-sourced deno application/monorepo which uses Fresh for the website and Deno for the CLI compilation, so my priority is trying to make that happen. After that I have a lot of other things to deal with, before even considering on working on this. Feel free to ping me if you want me to take a look at something or to try something
