Fred's edit pass on content collections guide #2371

FredKSchott · 2023-01-14T07:37:18Z

What kind of changes does this PR include?

updated content

Description

As a part of my v2.0 readiness docs pass, I took a look at the content collections guide and had some suggestions for how to improve the guide. My edits focused on three main areas:

Improve readability and ordering: Since this is meant to be a guide, I took a serious look at how the information is presented and in what order. Instead of jumping the user immediately into TypeScript configuration, the guide now introduces the concepts more slowly, building as it goes. The goal is to define terms early, introduce new concepts one at a time, and not overwhelm.
Collect concepts into a single place: I took a look at places where concepts were explained across multiple sections, and did my best to bring them into a single section. This is feedback we've gotten before so I'm extra sensitive to it!
Remove reference material: Remove anything that is really reference. This was mainly directed at detailed type definitions, which belong in reference and not guides. Adding to reference is left as TODO.

TODO

Add back Content Entry type definition somewhere within reference.
Resolve getEntry() SSR issue

netlify · 2023-01-14T07:37:22Z

✅ Deploy Preview for astro-docs-2 ready!

Name	Link
🔨 Latest commit	`691e541`
🔍 Latest deploy log	https://app.netlify.com/sites/astro-docs-2/deploys/63cde1d2b56078000800ea5c
😎 Deploy Preview	https://deploy-preview-2371--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

src/pages/en/guides/content-collections.mdx

sarah11918 · 2023-01-20T15:19:08Z

Just a reminder that we need to incorporate withastro/astro#5893 here, because getEntry() has now been renamed to getEntryBySlug()

src/pages/en/guides/content-collections.mdx

sarah11918 · 2023-01-20T15:44:39Z

Note: I added a necessary corresponding change to a link reference from api-reference here.

I know this PR might not be in its final form, but at least now the other page that will need changes is here, and visible for editing. (We are also going to have to update this page by renaming getEntry() for example.)

sarah11918 · 2023-01-20T16:25:01Z

Current status:

all links fixed (in both content-collections and api-reference) to correspond to edits to headings
getEntry renamed to getEntryBySlug including any corresponding definitions (id -> slug) and code samples (post-1.md -> post-1)
obvious typos etc. fixed
Conflicts resolved
Editing for content, style etc.

sarah11918

@FredKSchott I have done some tidying, and left some higher level comments here. Mostly, this is great! There are a couple of things I feel are worth mentioning, to make sure we're intentionally choosing against some things that were here before. Otherwise, this is a great revamp in general, and not too many nits! 🥳

src/pages/en/guides/content-collections.mdx

FredKSchott · 2023-01-21T20:47:31Z

@sarah11918 second pass complete!

sarah11918

Fred!

Here are my review notes for your consideration. You're of course free to ingore any and all of them. But, these are the comments that come to mind that I'd at least bring to your attention. Some might seem like style preferences, but I've tried to only do that when I think I can make things tighter.

So, here ya go!

P.S. I have not dealt with failing links/conflicts.

src/pages/en/guides/content-collections.mdx

sarah11918 · 2023-01-22T02:29:39Z

src/pages/en/guides/content-collections.mdx


-// Get all `src/content/blog/` entries
-const allBlogPosts = await getCollection('blog');
+## Querying Collections


From this section, to Generating Routes, I'm not sure the heading levels/right sidebar organization is quite right.

Content-wise, Rendering Content doesn't seem like it should be a ## as it seems more a peer with "Using Content in Astro Templates". But, I'm not sure I'd throw everything under the title of "Querying Collections"? And, they alternate between "script stuff" and "templating stuff".

These related items seem to be:

Script - Making the queries/filtering
Template- Templating the metadata (but not using render())
Script - Passing an entire Content as props
Template - Rendering the content itself with render()
Script/Template of modified metadata

I think these could all be ### peers under one ##? (Which we'd need a name for.)

I'm not sure I entirely follow this, but I agree this feels a little incorrectly placed. Just reorganized it to be a party of "querying", lmk what you think.

src/pages/en/guides/content-collections.mdx

FredKSchott · 2023-01-22T05:50:35Z

@sarah11918 thanks for the amazing review! Made some great improvements based on your feedback. It sounds like you're either "LGTM" or close to it, so I'll leave this open until Monday or until I see your approval come through.

I'm feeling pretty good about where this is now, but don't hesitate to give this another review if you have the time and feel the need.

sarah11918 · 2023-01-22T11:03:39Z

Just a quick reminder that merging this will remove the experimental note, so we might want to wait until Tuesday anyway! We have a "merge.on.release" label we can add for extra safety against forgetting.

I'm sure it will be great, and I'll just find time to scan for typos etc. just to be safe.

sarah11918

OK, a small handful of corrections that must be changed (typos etc.) and a few more things for your consideration!

I am now confident that whatever you choose to make of this, it'll be great! 🥳

src/pages/en/guides/content-collections.mdx

sarah11918 · 2023-01-22T16:30:59Z

src/pages/en/guides/content-collections.mdx

+To get the most out of content collections in Astro, you may need to update your `tsconfig.json` to enable `strictNullChecks`. This change is only required if you **do not** already extend Astro's `strict` or `strictest` recommended TypeScript settings in your `tsconfig.json` file.
+
+```json title="tsconfig.json" ins={5}
+{
+  // Note: No change needed if you use "astro/tsconfigs/strict" or "astro/tsconfigs/strictest"
+  "extends": "astro/tsconfigs/base",
+  "compilerOptions": {
+    "strictNullChecks": true
+  }
+}
+```


Suggested change

To get the most out of content collections in Astro, you may need to update your `tsconfig.json` to enable `strictNullChecks`. This change is only required if you **do not** already extend Astro's `strict` or `strictest` recommended TypeScript settings in your `tsconfig.json` file.

```json title="tsconfig.json" ins={5}

{

// Note: No change needed if you use "astro/tsconfigs/strict" or "astro/tsconfigs/strictest"

"extends": "astro/tsconfigs/base",

"compilerOptions": {

"strictNullChecks": true

}

}

```

To get the most out of content collections in Astro, you may need to update your `tsconfig.json` to enable `strictNullChecks`. This change is only required if currently extend Astro's `base` TypeScript settings in your `tsconfig.json` file.

```json title="tsconfig.json" ins={5} "base"

{

// Note: No change needed if you use "strict" or "strictest"

"extends": "astro/tsconfigs/base",

"compilerOptions": {

"strictNullChecks": true

}

}

```

I think we can tighten this up by avoiding the negative framing.

This is no longer true though. There are situations where you can be extending something other than base (or not extending anything, and defining everything yourself) that you still need to make this change.

src/pages/en/guides/content-collections.mdx

sarah11918 · 2023-01-22T16:45:35Z

src/pages/en/guides/content-collections.mdx

 ```

-Assuming `readingTime` was injected ([see our reading time example](/en/guides/markdown-content/#example-calculate-reading-time)), it will be available on the `remarkPluginFrontmatter` object.
+## Modifying Frontmatter with Remark


This is an appropriate use of the caution! Something we don't actually want anyone to do! 😄

Co-authored-by: Sarah Rainsberger <[email protected]>

FredKSchott · 2023-01-23T01:46:52Z

I'm going to merge this sooner actually, because I realized that the current docs have gotten out of date with the API. There will likely be one more PR to this page before release, so that will give us a chance for any final review before Tuesday's launch.

Looks like this is what it was previous to withastro#2371. Filtering to non-drafts makes sense too, but currently either the variable name (and the copy above) or the filter should change for consistency.

* update translation #1442 * update translation #1434 * update translation #1510 * update translation #1538 * Update src/content/docs/de/basics/astro-pages.mdx * Update src/content/docs/de/basics/astro-pages.mdx * Update src/content/docs/de/basics/astro-pages.mdx * Update src/content/docs/de/basics/astro-pages.mdx * Update src/content/docs/de/basics/astro-pages.mdx * update translation #1638 * update translation #2091 * update translation #2133 * update translation #2409 * update translation #2371 * update translation #4610 * update translation #5128 * update translation #5205 * update translation #5240 * update translation #5364 * update translation #5765 * update translation #6267 * remove paragraph where I cant find when it was deleted in original version * update translation #6620 * update translation #8495 * update translation #8573 * update translation #9336 * update translation #9336 2/2 didnt save file locally, so git didnt add * fix all visual differences by comparing manually against original english version * fix broken links in `astro-pages.mdx` * Breaking changes to other files! fixing links which link to the �stro-pages.mdx file * but now... * Update src/content/docs/de/basics/astro-pages.mdx Co-authored-by: Max <[email protected]> * Update src/content/docs/de/basics/astro-pages.mdx Co-authored-by: Max <[email protected]> * Update src/content/docs/de/basics/astro-pages.mdx Co-authored-by: Max <[email protected]> * revert Update markdown-content.mdx @lunaria-track:src/content/docs/de/basics/astro-pages.mdx --------- Co-authored-by: Max <[email protected]> Co-authored-by: Yan <[email protected]>

FredKSchott commented Jan 14, 2023

View reviewed changes

src/pages/en/guides/content-collections.mdx Outdated Show resolved Hide resolved

FredKSchott force-pushed the content-collections-docs branch 2 times, most recently from 2648856 to 38dc0bc Compare January 14, 2023 07:56

sarah11918 added the improve or update documentation Enhance / update existing documentation (e.g. add example, improve description, update for changes) label Jan 15, 2023

sarah11918 reviewed Jan 20, 2023

View reviewed changes

src/pages/en/guides/content-collections.mdx Outdated Show resolved Hide resolved

sarah11918 reviewed Jan 20, 2023

View reviewed changes

src/pages/en/guides/content-collections.mdx Outdated Show resolved Hide resolved

sarah11918 reviewed Jan 20, 2023

View reviewed changes

src/pages/en/guides/content-collections.mdx Outdated Show resolved Hide resolved

sarah11918 reviewed Jan 20, 2023

View reviewed changes

FredKSchott and others added 3 commits January 21, 2023 20:44

content collections docs pass

74950dd

update link from api-reference page

0912e11

updates for getEntryBySlug incl code examples

3364c00

FredKSchott force-pushed the content-collections-docs branch from 6d90361 to 3364c00 Compare January 21, 2023 20:46

Update content-collections.mdx

1fae08a

sarah11918 reviewed Jan 22, 2023

View reviewed changes

fred pass 3

acd9460

FredKSchott added 2 commits January 21, 2023 21:58

update bad links

7b388b5

update bad links

2818a98

github-actions bot added the i18n Anything to do with internationalization & translation efforts - ask @YanThomas for help! label Jan 22, 2023

update bad links

074fa35

sarah11918 reviewed Jan 22, 2023

View reviewed changes

FredKSchott and others added 3 commits January 22, 2023 10:21

Update src/pages/en/guides/content-collections.mdx

99a42a4

Co-authored-by: Sarah Rainsberger <[email protected]>

Update src/pages/en/guides/content-collections.mdx

6eb697d

Co-authored-by: Sarah Rainsberger <[email protected]>

update copy

5284892

FredKSchott and others added 7 commits January 22, 2023 10:31

Update src/pages/en/guides/content-collections.mdx

49c5657

Co-authored-by: Sarah Rainsberger <[email protected]>

Update src/pages/en/guides/content-collections.mdx

33adbe3

Co-authored-by: Sarah Rainsberger <[email protected]>

Update src/pages/en/guides/content-collections.mdx

735b0f6

Co-authored-by: Sarah Rainsberger <[email protected]>

Update src/pages/en/guides/content-collections.mdx

3479a9e

Co-authored-by: Sarah Rainsberger <[email protected]>

Update src/pages/en/guides/content-collections.mdx

ed97d1b

Co-authored-by: Sarah Rainsberger <[email protected]>

update docs

ab6e92f

update docs

691e541

FredKSchott merged commit 953c3a4 into main Jan 23, 2023

FredKSchott deleted the content-collections-docs branch January 23, 2023 01:46

morinokami mentioned this pull request Feb 6, 2023

i18n(ja): Update astro-pages.mdx #2576

Merged

colmanhumphrey mentioned this pull request Jun 4, 2023

Update content-collections.mdx: true drafts #3416

Merged

trueberryless mentioned this pull request Oct 22, 2024

i18n(de): update basics/astro-pages.mdx #9759

Merged

trueberryless added a commit to trueberryless/withastro-docs that referenced this pull request Oct 22, 2024

update translation withastro#2371

e01c14f

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fred's edit pass on content collections guide #2371

Fred's edit pass on content collections guide #2371

FredKSchott commented Jan 14, 2023 •

edited

Loading

netlify bot commented Jan 14, 2023 •

edited

Loading

sarah11918 commented Jan 20, 2023

sarah11918 commented Jan 20, 2023

sarah11918 commented Jan 20, 2023 •

edited

Loading

sarah11918 left a comment

FredKSchott commented Jan 21, 2023

sarah11918 left a comment

sarah11918 Jan 22, 2023

FredKSchott Jan 22, 2023

FredKSchott commented Jan 22, 2023

sarah11918 commented Jan 22, 2023

sarah11918 left a comment

sarah11918 Jan 22, 2023

FredKSchott Jan 22, 2023

sarah11918 Jan 22, 2023

FredKSchott commented Jan 23, 2023

Fred's edit pass on content collections guide #2371

Fred's edit pass on content collections guide #2371

Conversation

FredKSchott commented Jan 14, 2023 • edited Loading

What kind of changes does this PR include?

Description

TODO

netlify bot commented Jan 14, 2023 • edited Loading

✅ Deploy Preview for astro-docs-2 ready!

sarah11918 commented Jan 20, 2023

sarah11918 commented Jan 20, 2023

sarah11918 commented Jan 20, 2023 • edited Loading

sarah11918 left a comment

Choose a reason for hiding this comment

FredKSchott commented Jan 21, 2023

sarah11918 left a comment

Choose a reason for hiding this comment

sarah11918 Jan 22, 2023

Choose a reason for hiding this comment

FredKSchott Jan 22, 2023

Choose a reason for hiding this comment

FredKSchott commented Jan 22, 2023

sarah11918 commented Jan 22, 2023

sarah11918 left a comment

Choose a reason for hiding this comment

sarah11918 Jan 22, 2023

Choose a reason for hiding this comment

FredKSchott Jan 22, 2023

Choose a reason for hiding this comment

sarah11918 Jan 22, 2023

Choose a reason for hiding this comment

FredKSchott commented Jan 23, 2023

FredKSchott commented Jan 14, 2023 •

edited

Loading

netlify bot commented Jan 14, 2023 •

edited

Loading

sarah11918 commented Jan 20, 2023 •

edited

Loading