Astro.glob(): draft:true warning
#1552
Conversation
There is a warning here: https://docs.astro.build/en/guides/markdown-content/#markdown-drafts Seems wise to have it here as well: https://docs.astro.build/en/reference/api-reference/#astroglob ... Which is what this PR does.
✅ Deploy Preview for astro-docs-2 ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify site settings. |
|
Deploy preview link leading directly to changed section: |
|
Hi @mrienstra! I'm glad you were able to find the warning about draft posts in the Markdown content page! This is where we are choosing to put that info for now, although we do have plans for making sure that page in particular is reviewed again in the coming weeks to make it even more helpful. We have had a lot of product changes under the hood to our MDX and Markdown features, so there have been some content "add-ons" throughout the site for these topics in particular. Making everything easily discoverable is on our radar! We would not typically include this kind of content in our Reference section. That is intentionally kept concise, and is more of a lookup kind of resource. We typically do not include things like edge cases, warnings (other than deprecation notices), or troubleshooting advice on these pages. They would quickly get cluttered and it would be more difficult for those trying to quickly look up properties, types etc. We do also have to balance not duplicating material when possible to reduce maintainance costs when features are updated. So, when the material exists in one logical place, we are unlikely to add it again elsewhere. Thank you for taking the time to help improve the docs, and although I'm closing this PR, I don't think an issue for further exploration is needed. The content is available on the site in an apppropriate place right now, and we will be reorganizing our Markdown/MDX content in the coming weeks. Part of that plan will include highlighting this particular draft feature in a place where people needing that information will find it, including targeted guides for things like enabling draft blog posts, but not adding it to our reference section. |
|
Really appreciate you taking the time to explain the moving pieces & norms, I'll try to soak that up for future reference! 🪴🚰 |
There is a warning here: https://docs.astro.build/en/guides/markdown-content/#markdown-drafts
Seems wise to have it here as well: https://docs.astro.build/en/reference/api-reference/#astroglob
... Which is what this PR does. Happy to open an issue instead if it doesn't flow right, I was a little uncertain where exactly to put it.
This warning could instead be in the existing "Markdown Files" subsection, but I feel like it might seem a little random -- that subsection already feels a little random, as it was a bit unclear to me initially why it was there at all. Looks like it was added in #291. Might open an issue about making it a little more clear, like tweaking the title or adding a short intro paragraph about where it's going.