The latest updates on your projects. Learn more about Vercel for Git ↗︎

Hello! Thank you for opening your first PR to Astro’s Docs! 🎉

Here’s what will happen next:

1. Our GitHub bots will run to check your changes.
   If they spot any broken links you will see some error messages on this PR.
   Don’t hesitate to ask any questions if you’re not sure what these mean!

2. In a few minutes, you’ll be able to see a preview of your changes on Netlify 🥳

3. One or more of our maintainers will take a look and may ask you to make changes.
   We try to be responsive, but don’t worry if this takes a few days.

There is also another table present further down the page under the The pagination page prop header. Should I also transition that to a similar format? (Screenshot attached)

Thanks for starting to work on this, @SatanshuMishra! I would suggest making this a Draft PR for now, as it's not quite done yet.

@sarah11918 for the sake of consistency, how do you feel about the way that these properties are documented?

I don't think they would work for the properties in Astro.cookies, because of how long the descriptions are. Whatever we come up with for Astro.cookies, should we apply it wherever else properties are documented, such as in Astro.response?

So to answer the questions so far:

YES DESTROY ALL TABLES. I want no tables remaining. 😄

As to the Astro.response, I'm tempted to leave it as is because it's so visually compact, and I think maybe more helpful when you can see it that way? Looking at the cookies.set option, for example, it feels sooooooo long and drawn out, for mostly short entries, I might prefer to see what this looks like in the bulleted form too.

I'm not sure stretching everything out into headings is visually helpful, even if structurally it makes sense. I'll ask some others to take a look here!

Sounds good! I have a meeting in an hour or so. I will make the changes after :)!

Alright, so after some chatting, I say leave Astro.response as is, since in fact we used to just have a link out to a standard response object, but that content was removed so we added it in here to be helpful. (But, it's really not documenting an Astro thing; just saying that we conform to a standard).

As for the tables, let's keep going with the headings. It's the best structure, and so it does make sense to use it. If we need to do visual adjusting from that, we always can later.

The last commit changes the final Table into a heading based layout. The style is consistent with the previous changes made above. Preview of change is attached below:

So to answer the questions so far:

YES DESTROY ALL TABLES. I want no tables remaining. 😄

As to the Astro.response, I'm tempted to leave it as is because it's so visually compact, and I think maybe more helpful when you can see it that way? Looking at the cookies.set option, for example, it feels sooooooo long and drawn out, for mostly short entries, I might prefer to see what this looks like in the bulleted form too.

I'm not sure stretching everything out into headings is visually helpful, even if structurally it makes sense. I'll ask some others to take a look here!

I definitely agree with this. Just wanted to make sure it aligned well with you and DX's standpoint.
I will now log this in my memory as maintainable formatting - and be on the lookout for inconsistencies as the self-proclaimed Docs Inconsistency Sheriff :)

Also, perhaps another PR is in order later to reword some of the property descriptions. But that's just my opinion

@sarah11918, I've made all the changes you were looking for, and they're now available for you to review together :)

Thank you @SatanshuMishra ! We were even talking about asking our designer if he had an opinion to share. I think structurally, this is the best format. Some other docs maintainers and I will review the specific changes to see what we think, but we VERY MUCH appreciate you starting this off and giving us something to look at!

@SatanshuMishra chiming in real quick.

I like this format better than the table! My only comment would be that the vertical rhythm needs some help.

As of now in the example above taken from the preview link all the spacing between lines is very similar if not identical. Where there are arrows I would shrink the space so each line of each section can show that they are connected. Also, helps with readability.

Let me know if I can provide more guidance!

@SatanshuMishra chiming in real quick.

I like this format better than the table! My only comment would be that the vertical rhythm needs some help.

As of now in the example above taken from the preview link all the spacing between lines is very similar if not identical. Where there are arrows I would shrink the space so each line of each section can show that they are connected. Also, helps with readability.

Let me know if I can provide more guidance!

The space between the type and the body text can probably be removed.

Edit: Nevermind, the top-margin of the <p> tags is what is determining this, at the moment.

Thanks to Mark, our designer, for weighing in! We've discussed and decided that the scope of this PR should just be moving to headings... freeing the data from the tables and putting it reasonably out into headings.

Yeah, spacing is a little wide (Chris thinks he found a specific docs issue) and so things aren't visually grouped as well as they could be, but Chris will work separately on that! All we need to do here is liberate the data!

I'll do a closer review of this tomorrow just to make sure, but right now, all we need to worry about is the info structure. We'll tackle styling separately! 🙌

Sounds good! Even though the focus for this PR is content, I am happy to maybe start a thread on discord or some form of discussion (maybe another issue) to start exploring different spacing options and styles with @doodlemarks and @VoxelMC.