withastro / docs

Astro documentation
https://docs.astro.build/
MIT License
1.3k stars 1.46k forks source link

Make Markdown flavour explicit on the markdown page #9403

Open mlevison opened 1 week ago

mlevison commented 1 week ago

📚 Subject area/topic

Markdown

📋 Page(s) affected (or suggested, for new content)

https://docs.astro.build/en/guides/markdown-content/

📋 Description of content that is out-of-date or incorrect

The page mentions the default markdown type in passing. It code state explicitly, the default markdown flavour is GitHub Flavoured and then link to the spec.

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

No response

sarah11918 commented 19 hours ago

You're right, we do mention this in terms of the plugin that is automatically applied so that Astro follows the spec, but don't prominently display nor link to the spec itself.

We could probably display this prominently by adding to first sentence of the second paragraph:

In Astro, you can author content in Markdown, then render it in .astro components.

In Astro, you can author content in [GitHub Flavored Markdown](https://github.github.com/gfm/), then render it in .astro components. 

Do you think something like this would be helpful? If so, I'd welcome a PR with this addition!

mlevison commented 16 hours ago

Thanks, that's a great start. Run the experiment and see if it changes how often obtuse Ottawan's make the mistake of asking about it again.