Data collections and collection references by bholmesdev · Pull Request #3233 · withastro/docs

bholmesdev · 2023-05-11T17:08:24Z

What kind of changes does this PR include?

New or updated content

Description

Document the new "data collection" and "collection reference" features. See the RFC for the original feature proposal: withastro/roadmap#569

Update preambles to mention both content and data collections.
Add new sections on defining and resolving references. Each are added as subsections to maintain the overall flow of the guide.
Add the new type field to all defineCollection() examples. Yes, type will default to 'content' to make this change non-breaking for existing content collections. Though to keep these docs future-proof (in case type becomes a required field), type has been added for both content and data collections. Open to adding the line "type defaults to 'content' but you can specify manually" if we prefer!
Update language to be consistent when explaining content or data collections (ex. frontmatter -> "frontmatter or data file")
Update getEntryBySlug() recommendations to use getEntry(). This allows you to query content and data collections, without needing to explain how getEntryBySlug() is for content collections only. getEntryBySlug() is still around in the API reference, with a note to use the new getEntry() function for ease-of-use.
Add new sections to the API reference:
- getEntry()
- getEntries()
- defineCollection() -> type
- reference()
- Update "Collection Entry Type"

netlify · 2023-05-11T17:08:33Z

✅ Deploy Preview for astro-docs-2 ready!

Name	Link
🔨 Latest commit	`fc64768`
🔍 Latest deploy log	https://app.netlify.com/sites/astro-docs-2/deploys/64665448cada590008158868
😎 Deploy Preview	https://deploy-preview-3233--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/content/docs/en/guides/content-collections.mdx

yanthomasdev

Thanks @bholmesdev, amazing work on data collections! Added a few initial suggestions for you 🙌

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

src/content/docs/en/reference/api-reference.mdx

Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com>

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

sarah11918

Yay Ben! Left some more thoughts on the earlier part of this. Really liking it!

I'm tagging out for the night, and I've commented on the entire thing here, so some stuff for you to consider, and think about whether it's helpful!

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

sarah11918 · 2023-05-15T21:30:18Z

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

+A **content collection** is any directory inside the reserved `src/content` project directory, such as `src/content/newsletter` and `src/content/authors`. Only content collections are allowed inside the `src/content` directory. This directory cannot be used for anything else.

-A **content entry** is any piece of content stored inside of your content collection directory. Content entries are stored as either Markdown (`.md`) or MDX (`.mdx`) files. You can use any filename you want, but we recommend using a consistent naming scheme (lower-case, dashes instead of spaces) to make it easier to find and organize your content.
+A **collection entry** is any piece of content stored inside of your content collection directory. Entries can use content authoring formats including Markdown (`.md`) and MDX (`.mdx`) or as data formats including YAML (`.yaml`) and JSON (`.json`). You can use any filename you want, but we recommend using a consistent naming scheme (lower-case, dashes instead of spaces) to make it easier to find and organize your content.


Suggested change

A **collection entry** is any piece of content stored inside of your content collection directory. Entries can use content authoring formats including Markdown (`.md`) and MDX (`.mdx`) or as data formats including YAML (`.yaml`) and JSON (`.json`). You can use any filename you want, but we recommend using a consistent naming scheme (lower-case, dashes instead of spaces) to make it easier to find and organize your content.

A **collection entry** is any piece of content stored inside of your content collection directory. Entries can use content authoring formats including Markdown (`.md`) and MDX (`.mdx`) or as data formats including YAML (`.yaml`) and JSON (`.json`). You can use any filename you want, or begin your filename with an underscore to [exclude pages from the build](/en/core-concepts/routing/#excluding-pages). We recommend using a consistent naming scheme (lower-case, dashes instead of spaces) to make it easier to find and organize your content, but this is not required.

Just had an issue with someone over the underscore thing this morning, so I think this is a good place to qualify "you can use any filename you want"

Good point! I agree documenting the underscore pattern is useful, but this isn't quite right. Underscore files will still be included in the build if you're using them for, say, relative image paths or MDX component imports. They're just excluded from collection queries. Wondering if this is the best place to explain that given it's the intro?

Ok, so rather than get into more detail here, what about dropping that you can name them whatever you want entirely:

A collection entry is any piece of content stored inside of your content collection directory. Entries can use content authoring formats including Markdown (.md) and MDX (.mdx) or as data formats including YAML (.yaml) and JSON (.json). We recommend using a consistent naming scheme (lower-case, dashes instead of spaces) for your files to make it easier to find and organize your content, but this is not required.

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

sarah11918 · 2023-05-15T21:36:17Z

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

-2. Define each collection that you'd like to validate with a schema.
-3. Export a single `collections` object to register your collections.
+1. **Import the proper utilities** from `astro:content`. 
+2. **Define each collection that you'd like to validate.** This includes a `type` specifying whether the collection contains content authoring formats like Markdown (`type: 'content'`) or data formats like JSON or YAML (`type: 'data'`). It also includes a `schema` that defines the shape of your frontmatter or entry data.


Nicely done here, Ben!

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

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

bholmesdev · 2023-05-16T17:22:28Z

@sarah11918 Re "Resolving References" section: I just divided with a heading to split up the examples, not for SEO. Though I do expect people to wonder "ah crap, I just queried. Now how do I get the data for these references?" Resolving references was my stab at a short title to capture that need. Happy to either remove the title or find a better name if you prefer!

We can also merge the examples into one large code block, but this would lead to code comment overload imo 🤷

sarah11918

I think this is it, Ben! 🎉

Very tiny thoughts left for you to look at, and one or two nits. Thank you, this page is even more amazing now!

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

sarah11918 · 2023-05-17T10:15:54Z

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

+A **content collection** is any directory inside the reserved `src/content` project directory, such as `src/content/newsletter` and `src/content/authors`. Only content collections are allowed inside the `src/content` directory. This directory cannot be used for anything else.

-A **content entry** is any piece of content stored inside of your content collection directory. Content entries are stored as either Markdown (`.md`) or MDX (`.mdx`) files. You can use any filename you want, but we recommend using a consistent naming scheme (lower-case, dashes instead of spaces) to make it easier to find and organize your content.
+A **collection entry** is any piece of content stored inside of your content collection directory. Entries can use content authoring formats including Markdown (`.md`) and MDX (`.mdx`) or as data formats including YAML (`.yaml`) and JSON (`.json`). You can use any filename you want, but we recommend using a consistent naming scheme (lower-case, dashes instead of spaces) to make it easier to find and organize your content.


Ok, so rather than get into more detail here, what about dropping that you can name them whatever you want entirely:

A collection entry is any piece of content stored inside of your content collection directory. Entries can use content authoring formats including Markdown (.md) and MDX (.mdx) or as data formats including YAML (.yaml) and JSON (.json). We recommend using a consistent naming scheme (lower-case, dashes instead of spaces) for your files to make it easier to find and organize your content, but this is not required.

src/content/docs/en/reference/api-reference.mdx

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

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

…ro/docs into feat/data-collections-references

sarah11918

It is hereby my pleasure to approve this PR, @bholmesdev! 🥳

yanthomasdev

It is hereby my pleasure to find one more nit! But that's the last one, get my approval as well 🙌

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

Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com>

bholmesdev added 20 commits May 11, 2023 11:07

edit: add YAML and JSON to preamble

a887012

edit: organizing multi-collections

e46f44f

edit: defining collections

85a8063

edit: add types to defining multi-collections

2ba25b9

edit: add more types to defining multi-collections

e512c1e

edit: one more type: 'content'

4874ff8

edit: collection querying updates

6c7ab0e

edit: getEntryBySlug() -> getEntry()

3faf595

edit: one last type: 'content'

a41f6d3

edit: update define instruction comments

34f95ef

edit: add data collection example

82fbbde

new: add "defining collection references"

ae796ba

edit: better reference example

07e7bea

new: "resolving references" section

366c6dc

nit: data -> entry data

72babfd

new: type API reference

a983414

new: getEntry() and getEntries() API reference

29bfc00

chore: p tags to be safe

cbdeddf

nit: simplify wording

f616d9d

new: reference() API reference (heh)

65a9de0

edit: add third collection to organizing section

929e9c2

bholmesdev commented May 11, 2023

View reviewed changes

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

edit: update Collection Entry Type section

4eb0a49

yanthomasdev reviewed May 11, 2023

View reviewed changes

bholmesdev and others added 5 commits May 11, 2023 13:28

nit: ahead of time

44206dd

Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com>

nit: missed closing paren

d66e204

Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com>

nit: missed closing paren

26ffb38

Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com>

nit: bad comma

41af67e

Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com>

nit: bad comma

f68b439

Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com>

bholmesdev and others added 2 commits May 15, 2023 10:47

edit: getEntries() cleanup

8d63281

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

edit: clearer collection docs

75861a0

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

sarah11918 added the merge-on-release Don't merge this before the feature is released! (MQ=approved but WAIT for feature release!) label May 15, 2023

sarah11918 reviewed May 15, 2023

View reviewed changes

bholmesdev and others added 8 commits May 16, 2023 12:41

chore: inline defines -> explicit

6654060

edit: Astro recommends splitting -> you must

f73cd1f

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

chore: caution deprecated

a7e0259

edit: merge getEntry() examples into one

ba88b9a

edit: add getEntries() to "query functions"

2e5973a

chore: Content-only header -> available for list

9ad26bf

edit: make references explanation less abstract

5cff403

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

edit: add "top-level"

6e1eb7e

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

bholmesdev added 2 commits May 16, 2023 13:26

chore: Markdown or MDX -> type: 'content'

cf1ba03

.). oh god

c2d3a49

bholmesdev mentioned this pull request May 16, 2023

Data collections and references withastro/astro#6850

Merged

sarah11918 reviewed May 17, 2023

View reviewed changes

bholmesdev and others added 5 commits May 17, 2023 11:20

edit: way better Content collections lead-in

e91a5d3

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

edit: much better collection entry lead-in

2a063a1

edit: commaaaaaaan

5420f79

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

edit: clean up resolving references

a9dd9be

Merge branch 'feat/data-collections-references' of github.com:withast…

0cac3a6

…ro/docs into feat/data-collections-references

sarah11918 approved these changes May 17, 2023

View reviewed changes

yanthomasdev approved these changes May 17, 2023

View reviewed changes

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

bholmesdev and others added 2 commits May 17, 2023 20:01

edit: runnin runnin and runnin runnin and runnin runnin

b6f0e48

Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com>

Merge branch 'main' into feat/data-collections-references

fc64768

sarah11918 merged commit b18535b into main May 18, 2023

sarah11918 deleted the feat/data-collections-references branch May 18, 2023 16:45

sarah11918 added the minor-release For the next minor release; in the milestone, "merge queue" = approved for merging on release day. label Jun 22, 2023

liruifengv mentioned this pull request Jul 27, 2023

i18n(zh-cn): Translate reference/api-reference.mdx #3864

Merged

Uh oh!

Conversation

bholmesdev commented May 11, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What kind of changes does this PR include?

Description

Uh oh!

netlify bot commented May 11, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for astro-docs-2 ready!

Uh oh!

Uh oh!

yanthomasdev left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sarah11918 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

sarah11918 May 15, 2023

Choose a reason for hiding this comment

Uh oh!

bholmesdev May 16, 2023

Choose a reason for hiding this comment

Uh oh!

sarah11918 May 17, 2023

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

sarah11918 May 15, 2023

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

bholmesdev commented May 16, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sarah11918 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sarah11918 May 17, 2023

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sarah11918 left a comment

Choose a reason for hiding this comment

Uh oh!

yanthomasdev left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bholmesdev commented May 11, 2023 •

edited

Loading

netlify bot commented May 11, 2023 •

edited

Loading

bholmesdev commented May 16, 2023 •

edited

Loading