Inspired by google's styleguide
The Grassroot Project uses Markdown for the layout and formatting of lesson and project files to get properly formatted HTML for the The Grassroot Project website.
The goals of this style guide are to help create Markdown that is:
- Readable for as many users as possible.
- Editable by any contributor.
- Consistent across the The Grassroot Project website.
Contents:
- Lesson layout
- Project layout
- Headings
- Newlines
- Lists
- Code
- Links
- Images
- Codepen embeds
- Maintainer instructions
- English writing style
In general, the following layouts should be used for all lessons and projects. Text that should be replaced with the author's own content will be in all CAPS, with any additional information regarding a section listed at the end of the layout code block.
When adding new lessons or projects, make a copy of either the lesson template or the project template in the appropriate folder where the new lesson/project should be placed. Then begin editing the template copy.
The lesson example and project example files both show how this style guide can be put to use in an actual lesson/project. They don't cover every situation (the lesson example doesn't show a lesson with an assignment and one without, for example), but they should give you a better representation of how lessons/projects should look after this style guide is applied.
### Introduction
A BRIEF INTRODUCTION.
### Lesson overview
This section contains a general overview of topics that you will learn in this lesson.
- A LESSON OVERVIEW ITEM.
### CUSTOM SECTION HEADING
CUSTOM SECTION CONTENT.
### Assignment
<div class="lesson-content__panel" markdown="1">
1. A RESOURCE OR EXERCISE ITEM
- AN INSTRUCTION ITEM
</div>
### Knowledge check
This section contains questions for you to check your understanding of this lesson on your own. If you’re having trouble answering a question, click it and review the material it links to.
- [A KNOWLEDGE CHECK QUESTION](A-KNOWLEDGE-CHECK-URL)
### Additional resources
This section contains helpful links to related content. It isn’t required, so consider it supplemental.
- It looks like this lesson doesn't have any additional resources yet. Help us expand this section by contributing to our curriculum.
-
### Introduction
: A brief summary on what the lesson is about and/or why the topics or concepts it covers are important. Replace theA BRIEF INTRODUCTION.
text with your own lesson introduction. -
### Lesson overview
: A bulleted list of items that provide a general overview of what the user will learn about in the lesson. Lesson Overviews should include general, higher level statements that cover the core concepts of the lesson. They should serve and be phrased as a list of key items that a user should be expected to learn about throughout the lesson, rather than a list of things they should be able to do by the end of it.Replace the
A LESSON OVERVIEW ITEM.
text with your own lesson overview item, then add any additional bulleted lesson overview items. The lesson should ideally have no more than 7 lesson overview items, but this number might vary by lesson. If the lesson does not have a lesson overview, remove this entire section from the lesson. -
### CUSTOM SECTION HEADING
: A custom section that contains some of the main content of the lesson. Replace theCUSTOM SECTION HEADING
text with a proper section heading and theCUSTOM SECTION CONTENT.
text with your own content, then add any additional custom sections. If the lesson does not have any custom sections, remove this entire section from the lesson. -
### Assignment
: A numbered list of external resources the user must read or watch, or practical exercises the user must complete (such as our exercise repos), in order to fully complete the lesson.Each assignment item should include some brief text that further informs the user on why it is included in the assignment or what purpose it serves. When necessary, an assignment item should also explicitly state any instructions that should be followed. Examples of instructions can include (but aren't limited to) a specific section the user should read, whether the user should complete any specific exercises, and whether the user should redirect themselves to additional links within the resource.
Replace the
A RESOURCE OR EXERCISE ITEM.
text with your own text and a link to the resource or exercise (or any applicable instructions if an exercise isn't external), then add any additional numbered assignment items. The lesson should ideally have no more than 3-5 assignment items (reading several sections on a web page or completing a folder of 5 exercises would be considered a single assignment item). If the lesson does not have an assignment, remove this entire section from the lesson.If an assignment item includes any instructions, replace the
AN INSTRUCTION ITEM
text with a single instruction, then add any additional bulleted instruction items.If a user should only read specific sections within a resource (e.g. "Skip Chapter 7") or complete only specific exercises (e.g. "Complete the first two exercises in the repo"), each instruction item should be its own bullet.
If an assignment item does not have any instructions, remove the bulleted
AN INSTRUCTION ITEM
text from it. -
### Knowledge check
: A bulleted list of specific questions that a user should be able to answer on their own after reading the lesson and completing any assignment or practice. A knowledge check should only link either to a section within the lesson (either with a Heading 3###
or Heading 4####
, or by wrapping text in a<span>
element with anid
attribute) or a resource previously linked to in the lesson. This link should help users review the necessary material in order to answer the knowledge check without requiring them to re-read the entire lesson.Replace the
A KNOWLEDGE CHECK URL
text with the actual link to the section/resource and theA KNOWLEDGE CHECK QUESTION.
text with your own question/problem that the user should be able to answer/solve. Then add any additional bulleted knowledge check items. The lesson should ideally have no more than 7 knowledge checks, but this number might vary by lesson. If the lesson does not have a knowledge check, remove this entire section from the lesson.In order to link to a Heading 3
###
or Heading 4####
within the lesson, replace the value within the parenthesis for the knowledge check link with a hashtag#
followed immediately by the section title in lowercase and any spaces replaced with a hyphen-
. For example, a Heading 3 section titled### Creating a Method
would be linked to with(#creating-a-method)
.In order to link to a
<span>
element within the lesson, replace the value within the parenthesis with the exactid
attribute of the<span>
element (this will be case sensitive). For example, a<span id="Knowledge-Check-3">
element would be linked to with(#Knowledge-Check-3)
. -
### Additional resources
: A bulleted list of optional resources for the user to read. Additional resources should be related to the content of the lesson in some way, without being necessary to gain an understanding of the lesson content. An additional resource should include brief text that further informs the user on why it is included or what purpose it serves.If the lesson doesn't include any additional resources, leave this section as-is. Otherwise, replace the default bulleted resource item with your own resource, then add any additional bulleted resource items. The lesson should ideally have no more than 3-5 additional resources.
### Introduction
A BRIEF INTRODUCTION.
### PRE-ASSIGNMENT SECTION HEADING
PRE-ASSIGNMENT SECTION CONTENT.
### Assignment
<div class="lesson-content__panel" markdown="1">
1. A REQUIREMENT/USER STORY.
#### Extra credit
- AN OPTIONAL ADD-ON/USER STORY.
</div>
### POST-ASSIGNMENT SECTION HEADING
POST-ASSIGNMENT SECTION CONTENT.
-
### Introduction
: A brief summary on what the project is and an overview of what the user will be building. Replace theA BRIEF INTRODUCTION.
text with your own project introduction. -
### PRE-ASSIGNMENT SECTION HEADING
: Optional. A section that contains content that should come before the actual project assignment. This section will most likely not be needed for most projects, but when it is needed simply replace thePRE-ASSIGNMENT SECTION HEADING
text with a proper section heading and thePRE-ASSIGNMENT SECTION CONTENT.
text with your own content. Then add any additional pre-assignment sections. If the project does not have a pre-assignment section, remove this entire section from the project. -
### Assignment
: A numbered list of items that describe detailed requirements or user stories that must be followed in order to complete the project. Replace theA REQUIREMENT/USER STORY.
with your own requirement, then add any additional numbered requirement items. -
#### Extra credit
: A bulleted list of items that describe any optional add-ons or user stories that might make a user's project stand out. Replace theAN OPTIONAL ADD-ON/USER STORY.
text with your own add-on, then add any additional bulleted add-on items. If the project does not have any extra credit items, remove the extra credit section from the assignment. -
### POST-ASSIGNMENT SECTION HEADING
: Optional. A section that contains content that should come after the actual project assignment. This section will most likely not be needed for most projects, but when it is needed simply replace thePOST-ASSIGNMENT SECTION HEADING
text with a proper section heading and thePOST-ASSIGNMENT SECTION CONTENT.
text with your own content. Then add any additional post-assignment sections. If the project does not have a post-assignment section, remove this entire section from the project.
Headings should always use sentence case:
### This Is Not Sentence case
### This is sentence case
### This is also sentence case with HTML
Headings should never contain any code snippets.
<!-- Wrong -->
### The `id` property
<!-- Right -->
### The id property
Use Heading 3 ###
for main section titles ("Lesson overview", "Assignment", custom sections, etc):
### Section heading
Use either Heading 4 ####
for sub-headings that are on their own line or Markdown's bold syntax, e.g. **Sub-heading**
, for inline sub-headings:
...text before.
#### Sub-heading
Text after...
**Inline sub-heading:** Some text defining this sub-heading...
Each Markdown file should have an empty newline at the very end, after all of the file's contents.
Always add a newline before and after a heading, a list, an Assignment panel, or any other content that is not strictly text:
Content before...
### Section heading
1. A list item
...content after.
Markdown is smart enough to let the resulting HTML render your numbered lists correctly. For longer lists that may change, especially long nested lists, use "lazy" numbering:
1. Foo.
1. Bar.
1. Foofoo.
1. Barbar.
1. Baz.
When nesting lists, use a 2 space indent when nesting inside a bulleted list and a 3 space indent when nesting inside a numbered list. The following Markdown:
1. The first item
2. A second item
- A sub-item for the second item with 3 spaces before the hyphen
- A bulleted list item
- A sub-bullet with a 2 space indent
- A new list item
Will result in the following output:
- The first item
- A second item
- A sub-item for the second item with 3 spaces before the hyphen
- A bulleted list item
- A sub-bullet with a 2 space indent
- A new list item
When list items should wrap onto multiple lines – such as to create a line break between a lengthy list item – insert an empty line before and after each wrapped line and use a 2 to 3 space indent on the wrapped line. You should use a 2 space indent for bulleted lists and a 3 space indent for numbered lists. The following Markdown:
1. This is a lengthy list item.
This is related information to the first item, but visually separated out.
2. A new list item
- This is a lengthy bulleted list item.
This is related information to the first item, but visually separated out.
- A new bulleted list item
Will result in the following output:
-
This is a lengthy list item.
This is related information to the first item, but visually separated out.
-
A new list item
-
This is a lengthy bulleted list item.
This is related information to the first item, but visually separated out.
-
A new bulleted list item
The preferred way to create unordered lists for The Grassroot Project is by using hyphens -
. Both hyphens and asterisks give the same results, but sticking to one way keeps the source markdown consistent.
- This is a list item made using a hyphen.
- This is a list item made using a hyphen.
- This is a list item made using a hyphen.
`Backticks` designate inline code
, and will render all wrapped content
literally. Use them for short code quotations, field names, or file names:
Write these in the `script` tag of a skeleton HTML file.
...which is why we can call `taco.printString()` but not `taco.capitalizeString()`.
Create a new file named `styles.css` first.
For code quotations longer than a single line, use a codeblock with 3 opening anc closing tilde marks:
~~~javascript const obj = { name: "object", marker: "X" } ~~~
It is best practice to explicitly declare the language immediately after the opening tilde marks, so that neither the syntax highlighter nor the next editor must guess.
Codeblocks should only contain actual code snippets, terminal commands, or commented out text. Never include leading terminal content, such as the dollar sign $
you might see preceding any commands you type in.
// The below example is incorrect
$ cd Documents
// The below is correct
cd Documents
If you need a codeblock within a list, you should follow the same indenting rules for multi-line list items, with the codeblock being indented with 2 spaces for a bulleted list item and 3 spaces for a numbered list item. The following Markdown:
- Bullet. ~~~javascript // We start indenting with 2 space for the codeblock function tester() { const yay = 'From here we can indent like we normally would' } ~~~ - Next bullet.
Will result in the following output:
-
Bullet.
// We start indenting with 2 space for the codeblock function tester() { const yay = 'From here we can indent like we normally would' }
-
Next bullet.
Long links make source Markdown difficult to read and break the 80 character wrapping. Wherever possible, shorten your links.
Markdown link syntax allows you to set a link title, just as HTML does. Use it wisely.
Titling your links as "link" or "here" tells the reader precisely nothing when quickly scanning your doc and is a waste of space. Instead, write the sentence naturally, then go back and wrap the most appropriate phrase with the link:
See the [lesson template](./templates/lesson-template.md) for a more easily copyable lesson file.
Or, check out the [project template](./templates/project-template.md) for a more easily copyable project file.
Links to required reading should not be scattered throughout a lesson, and should instead be placed in either the ### Assignment
or ### Additional resources
section. Links that refer a user to a previous lesson as a refresher, or a link to a Wikipedia page that offers a definition/explanation of a term are fine to place outside of these two sections.
Images in Markdown follow the same syntax as links, except they begin with an exclamation point !
:
![flex shorthand](https://cdn.statically.io/gh/grassroot-software/grassroot_curriculum/495704c6eb6bf33bc927534f231533a82b27b2ac/html_css/v2/foundations/flexbox/imgs/10.png)
The text in square brackets will be included as the image's alt text. Similar to link titles, the alt text should be informative, but shouldn't be overly verbose.
In order to properly add images to a lesson, follow the instructions in our Adding Images to the Curriculum Wiki page to get a statically URL as seen in the codeblock above.
In order to embed a Codepen example into a lesson, you must be in the editor view for the Codepen you wish to embed and then click the Embed
button at the bottom right of the page.
The following options should be selected when creating a Codepen embed:
- Default Tabs: The "Result" tab must be selected in addition to one of the other three options (HTML, CSS, or JavaScript), depending on the main purpose of the Codepen. If the purpose is to show an HTML concept then the "HTML" option must also be selected, for example.
- Theme: "Dark"
- Use Click-to-Load: "Off"
- Make Code Editable: "On"
Finally, the HTML (Recommended) code option must be the one that is copy + pasted into the lesson.
When a user adds a Codepen embed to a lesson, a maintainer should fork the embed to the official The Grassroot Project Codepen account. When necessary, the name of new pens should be updated to better reflect their purpose, e.g. Simple SVG Example
for a pen showing a simple SVG or max-width | CSS Responsiveness
for a pen about the max-width
property.
After forking a pen to the The Grassroot Project account and ensuring the embeds options from above are selected, the lesson the original embed is from should be updated to include the forked, The Grassroot Project version instead.
As a general note, The Grassroot Project follows American English and American style punctuation. When adding content to the curriculum, be sure to follow this practice for consistency across lessons.