fix: clarify streaming errors #12877
Conversation
✅ Deploy Preview for astro-docs-2 ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
Lunaria Status Overview🌕 This pull request will trigger status changes. Learn moreBy default, every PR changing files present in the Lunaria configuration's You can change this by adding one of the keywords present in the Tracked Files
Warnings reference
|
sarah11918
left a comment
sarah11918
left a comment
There was a problem hiding this comment.
Thanks for jumping on another issue @fkatsuhiro ! We really appreciate the effort and helping us make our docs more complete! I'm going to ask you to look a little bigger than the part you've added, and hope my guidance below is helpful:
In general, we never want to add notes or cautions or any "asides" in docs. Those should only ever be used in very specific situations, and are almost never the right way to add new content.
You've also added a fairly big section here, which makes me think this might be time for a sub heading! So, I'll ask you to rethink this content with these ideas in mind:
-
There is probably a subject heading needed here to describe all this new content. Imagine that you wanted to provide a direct link to someone to this part of the docs (because this would answer their question/solve their problem). What would you call this section? What is the main idea here? Please make that a new heading!
-
With that heading, please think about all the information you want to say and decide what a good information flow is. Some ways to think about this are:
- General statements, moving towards more specific content
- Grouping relevant info together instead of having "oh, but also about that earlier thing..." notes after the fact
- Linear order of how/when things happen
Whatever order makes sense, put all your ideas in that order. Talk about things as they are needed/necessary for someone to understand. This might even mean going back and rewriting some of the earlier content for the
errorentry, or even for the whole "The 500 page" section so that this WHOLE section makes sense! That is OK! -
If necessary, you can even have more subheadings, even inside your new subheading! Let's make sure that instead of cautions and asides, we have a great, solid information architecture and use headings for different topics instead of asides. Headings make it so that you can link people directly to ideas, make it easy to identify at a glance what the content is going to be (instead of just getting someone's attention with CAUTION! you can get their attention with ACTUAL INFO!) and are generally more accessible.
So in general, don't think of "adding new info to the docs" as "adding new individual pieces." If you're going to add to docs, we have to do so in a way that overall improves the existing content and provides a good reading experience!
| <p><Since v="4.11.0" /></p> | ||
|
|
||
| `src/pages/500.astro` is a special page that is automatically passed an `error` prop for any error thrown during rendering. This allows you to use the details of an error (e.g. from a page, from middleware, etc.) to display information to your visitor. | ||
| `src/pages/500.astro` is a special page that is automatically passed an `error` prop for error thrown during rendering. This allows you to use the details of an error (e.g. from a page, from middleware, etc.) to display information to your visitor. |
There was a problem hiding this comment.
Can you explain the change here? I don't think there was a problem with the original sentence. (And, the new sentence is now grammatically incorrect.) What did you mean to change here?
There was a problem hiding this comment.
Hi, @sarah11918 san.
Thank you for your comment!
I've removed the word "any" to make the description a bit more precise. Since some cases might not actually trigger a 500 error, I thought avoiding "any" would help prevent any potential confusion. This way, the documentation stays closer to the actual behavior.
|
|
||
| To avoid leaking sensitive information when displaying content from the `error` prop, consider evaluating the error first, and returning appropriate content based on the error thrown. For example, you should avoid displaying the error's stack as it contains information about how your code is structured on the server. | ||
|
|
||
| :::caution |
There was a problem hiding this comment.
Reminder that we typically only use cautions for dangerous situations (your project won't build, you might lose data) and not just when describing "how things work."
Feel free to rework existing text it reads more like an explanation of how streaming works. That's what we normally do when we want to add more information or context! This doesn't have to be a "patch a note on existing text" situation. If we didn't explain it well, or completely, then our explanation should change!
| } | ||
| }); | ||
| ``` | ||
| :::note |
There was a problem hiding this comment.
Similarly, we should not be using notes (or cautions) to just explain "how things just work." This often means that something wasn't properly described in the first place, and is a sign to think about the flow of information, and make sure it's all presented in appropriate places.
|
Hi, @sarah11918 san. Thank you for the feedback! |
3 participants
Description (required)
This PR clarifies the limitations of
src/pages/500.astroregarding streaming rendering errors and provides a workaround using middleware.Related issues & labels (optional)
implove or update documentation