Add a note to the top of parts 5, 6, and 7 that they make sense only if you start with part 4 and go all the way through.

[shannonbux]

Add a note to the top of parts 5, 6, and 7 that they make sense only if you start with part 4 and go all the way through.

[fk]

That sounds like we'd ideally need a "Note" or "callout" UI component—something like

(https://reactjs.org/docs/react-api.html#reactpurecomponent)

or

(http://getbootstrap.com/docs/4.1/getting-started/webpack/#importing-javascript) available from within Markdown.

Maybe that's a good opportunity to decide wether we want to use the "Gatsby Butler" in the .org site? He made his way into the .com design and I hear people have been experimenting with stickers featuring him… ;-)

Indeed the butler originally was thought as a (quoting @KyleAMathews in #408 (comment)) "little whimsical add-on" "popping up throughout the design" and my initial mocks featured him accompanying exactly the type of content this issue is about—see

• [1.0] Discuss next steps on gatsbyjs.org design #1173 (comment)
• [1.0] Discuss next steps on gatsbyjs.org design #1173 (comment)

[ryanditjia]

I like the callout UI component and I tried to achieve the same look using blockquote. Currently our blockquote looks like:

I took a look at Vuepress’s docs one day and was interested in their tip, warning, danger components. But I believe this is not standard markdown, so maybe it’s a no go.

reactjs.org uses blockquote that’s stylized to look like tip. I think this is the most viable right now.

But if we wanna be fancy, we can implement a Butler component using MDX. There’s gatsby-plugin-mdx which I haven’t played around with. I like this one the most.

What do you guys say to giving Butler + MDX a shot? He can make his first appearance here 😄

[fk]

Hey @ryanditjia, nice to meet you! 👋
That is looking great and does a fine job already at making this block of content distinguishable!

I also peeped the reactjs.org source :-D and saw that they are using blockquote. Discovering that had me surprised for a few seconds, but the advantage of doing so became obvious very quickly—you called it already: "standard Markdown".

As I currently understand, to go for a more custom design (butler or even just different background colors per callout type like Vue does) and stick with standard Markdown, we'd need to use inline HTML. The alternatives you mentioned, a custom Markdown block or React component, IMO are fine options not only in terms of readability, but also in regards to showing an example of how to extend Markdown right in the Gatsby docs.

I haven't really used it myself, but I remember gatsby-remark-custom-blocks requires prefixing each line in the block with a pipe. Thinking out loud, IMO I wouldn't want to read (or edit) those blocks in plain Markdown.

[fk]

Hmm this made me remember s/th I posted last year (…searching).
Here it is: https://github.com/gatsbyjs/gatsby/issues/2609#issuecomment-344103582—the essentials:

• http://commonmark.org/ is "a strongly defined, highly compatible specification of Markdown" and is what Gatsby (via remark) uses. IIRC GitHub initiated and/or is using CommonMark right here, but don't quote me on that.
• CommonMark is discussing to add a "Generic directives/plugins syntax" (see also) adding Inline, Leaf block and Container block support. The latter is just what Vuepress is doing for their custom containers, which IMO is the way to go if abandoning that standard path but sticking to Markdown:

::: name [inline-content] {key=val}
contents, which are sometimes further block elements
:::