Style Guide for Written Articles on Ghost
Main Topic Title is in the title of the blog above ^^ (h1), so don't use h1s for anything else in the article.
First-level subtitles (h2)
Second-level subtitles (h4)
Third-level subtitles (h6)
In the markdown, always include a space between the hash marks (##) and the header word: ## First-level subtitles. Never put additional hash marks after the text.
Separate h2-level headers with a horizontal line:
Asides and notes can be done with a quote using the
>symbol at the beginning of the line. This is a great place for parenthetical notes regarding something that was just previously taught/written.
Don't forget to edit the metadata in settings (gear icon in the upper-right.) For the image, try to find a high-resolution image (via unsplash maybe, or search for something relating to what you're looking for.) The photo is reduced to a banner-style image where it is wide and not very tall, so searching for "_ _ banner photo" can be helpful to find something that fits well. E.g. Googling "fingerprint banner photo" might be useful for an article about security.
- Tools: Node, Git, React, etc.
- Topic Part One Link, Topic Part Two Link, etc. [optional] (Use if part of a larger series)
Overview (h2)
- What?
- Why?
- How?
Provide a brief summary (1 - 2 paragraphs max) of the goal of the article. Why is it important? How does it connect to prior concepts? Use bullet points and images/videos if it helps to reinforce the main point.
Real World Examples (h4)
Put the new concept into the context of real world applications. Use images, videos, GIF's, etc. from multiple sources to clearly convey how the concept is relevant to solving actual problems.
Tutorial (h2)
Provide clear step-by-step interactive instructions using every available resource: screenshots, /bash /commands, and
multi-line code blocks.
Don't just code vomit on the page. Provide helpful commentary on the why of things. Here is an example of an informative code block:
// /path/to/file/name/here.js
var uncreativeExample = "Hello World";
console.log(uncreativeExample);
// variables allow programs to store values under aliases and reference them repeatedly throughout the rest of the code.
Students are easily bored by tutorials that merely ask the reader to follow along like a coding zombie. Make the tutorial more interesting and challenging by doing the following:
- Ask questions. What would happen if you do 'xyz' in this case?
- Challenge the reader to try things and experiment. Now that 'abc' is doing 'x', try adding a line to make it do 'y'
Summary (h2)
Briefly recap the main points of the article. Explain some of the limitations and advantages of doing what you just did.