Guide to official examples (templates)

[mrienstra]

Reading https://github.com/withastro/docs/pull/1394 reminds me that I've been meaning to bring up the idea of a guide / overview of the official examples (templates).

The intent is to make it a little more clear what each example demonstrates, to help guide people toward which ones to use as a starter, or which one to play with to understand something as part of a working whole.

E.g. the blog example -- amongst other things -- demonstrates the usage of Astro.glob() to output a list of pages. Sure, this isn't rocket science -- and there are some nice code samples shown in /en/guides/markdown-content/#importing-markdown and /en/reference/api-reference/#astroglob already, but sometimes it can save a ton of time -- especially if something isn't worked the way you expected it to -- to do something like the following:

1. Run pnpm create astro@latest -- --directory temp_blog --template blog --install 1 --git 1 --typescript strictest && cd temp_blog && git add . && git commit -m "initial" && code -n . && open http://localhost:3000/blog && pnpm dev
2. Verify that Astro.glob() is working.
3. Start playing around with using Astro.glob(), from a working base.

Maybe that's not the best example. And the workflow I just mentioned is not the focus of what I had in mind. I'd mostly just like to have a brief list of what each example is doing, e.g. which integrations it uses, which techniques it demonstrates, that sort of thing. If this doesn't belong in the docs, I can just start by filling out the README.md files in each example, right now they are pretty bare.

Thoughts?

[sarah11918]

My initial thought reading this was your conclusion at the end: beefing up the READMES for each starter makes a lot of sense. At some point, we may consider showcasing the starter templates more. But many of them are still intended to be "proof of concept" starter examples of one specific concept. (Other than the main section at the top of astro.new.)

I think if you wanted to start by tackling a READMEs in the way you described, you'll probably notice a difference between the "top five" and the rest of them. Starting the work this way might give us more insight into how to better eventually showcase them.

[sarah11918]

Closing this issue for now. As we are updating our starters, and are focusing on our themes showcase, our starters are getting better treatment, updated READMEs etc and we are evaluating them for helpfulness as we go. Some of the concepts showcased are very likely to change especially as we get closer to releasing v2 and taking Content Collections out of the experimental phase.

Since our official starters do have 1-click open and play in SB or CSB, it's also not too much friction to see what's in the starters in a more exploratory way, without duplicating docs in the READMEs, or worrying about keeping links up to date.