Gatsby: Special design for tutorial "challenges" and "key ideas"

[shannonbux]

Description

In the tutorials and in some guides, there are a few kinds of information, including:

• how to do something (step-by-step instructions)
• examples
• why to do something

That last kind of information, the "why" to do something, is such an enormously important part of teaching what Gatsby is and how it works and WHY it works the way it does, I think it would be cool if that information looked different than the other two types of information. Like some sort of outline or highlighting or something.

There could also be a special design for tutorial "challenges," which are things I'm adding at the end each tutorial that will help beginners expand, without step-by-step instructions, on the task they just learned how to do in the tutorial.

Help needed

Feedback on these ideas and possible designs or other sites that do a good job of this.

[WebRuin]

I agree with your concern, and have a few ideas of my own like adding CodePen snippets to the tutorials. I am looking to contribute. And I have the ability to do this. If I am allowed I will do this ASAP

[shannonbux]

What are CodePen snippets, @WebRuin? We'd love to get contributions in this area. A couple other design ideas for the docs:

• special design for "warnings"--see Vue.js docs for nice examples
• back and forward arrows at the bottom of the tutorials--again, see Vue.js docs for nice examples
• design for callout notes (things that are not part of step-by-step instructions, like tips, interesting facts, etc. in the Django tutorial

[KyleAMathews]

https://codepen.io/pens/<-- some examples of pens.

[shannonbux]

AH cool, @WebRuin! Codepen snippets seem great. I took some codecademy tutorials and the tutorials exist on one column of the screen (left) and the middle column is a code editor, and the right column is the browser. It was super helpful although made me wish I had a larger screen, which is why doing codepen snippets would probably involve figuring out how they'd fit into gatsbyjs.org's responsive design. It would be great to get your contributions!

[fk]

Somewhat related: https://github.com/gatsbyjs/gatsby/issues/5612#issuecomment-394750323

[hsribei]

@WebRuin this Gatsby plugin is a great way to keep snippets synced between git and CodePen: https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-remark-code-repls

[KyleAMathews]

Due to the high volume of issues, we're closing out older ones without recent activity.