Skip to content

Codecademy Curriculum Markdown Style Guide

This page was last updated on February 1, 2022. Content created prior to this date likely deviates from these standards. When appropriate and at your own discretion, apply the current standards to content that does not align with these standards.

Description/Purpose

Codecademy's Markdown rendering supports Github Flavored Markdown (spec) (quick reference).

Italics

Italics (single _ or *) should be used for emphasis where necessary. Italics should not be used for new terms.

Correct:

Product Managers focus on what an application does. Meanwhile, developers focus on how the application works.

Product Managers focus on _what_ an application does. Meanwhile, developers focus on _how_ the application works.

Incorrect:

A function is a procedure: a repeatable set of program instructions to perform a task.

A _function_ is a procedure: a repeatable set of program instructions to perform a task.

Bold

Bold (double __ or **) should be used for new terms, keywords, or concepts, not for emphasis:

Correct:

A function is a procedure: a repeatable set of program instructions to perform a task.

A **function** is a procedure: a repeatable set of program instructions to perform a task.

Incorrect:

It is very important to end every statement with a semicolon (;).

It is **very** important to end every statement with a semicolon (`;`).

Inline Code

Inline code (`) should be used for text that might appear in an actual code file, such as code blocks, function names, or variable names. Inline code should also be used when specifying filenames/file paths.

Correct:

Look at the addNumbers() function in the math_utils.js file.

Look at the `addNumbers()` function in the `math_utils.js` file.

Incorrect:

loops are a language feature for repeating a specific set of instructions based on a condition.

`loops` are a language feature for repeating a specific set of instructions based on a condition.

Code Blocks

Use full code blocks (```) for any code examples that span multiple lines or are excessively long.

Code blocks support syntax highlighting for the following languages:

  • C++: ```cpp
  • C#: ```cs
  • CSS: ```css
  • HTML: ```html
  • Java: ```java
  • JavaScript: ```js
  • PHP: ```php
  • Python: ```py
  • R: ```r
  • Ruby: ```rb
  • Sass: ```scss
  • Shell/Program Output/Unhighlighted: ```
  • SQL: ```sql

Code blocks should always contain syntactically-valid code snippets so that syntax highlighting is consistent.

Correct:

function doSomething() {
   // statements go here
}

Incorrect:

function doSomething() {
   ...
}

Links should use the normal markdown format: (text)[link].

If there are parentheses in the link, replace them with %28 and %29.

Correct:

Hangman

[Hangman](https://en.wikipedia.org/wiki/Hangman_%28game%29)

Incorrect:

Hangman

[Hangman](https://en.wikipedia.org/wiki/Hangman_(game))

Lists

Bulleted lists can be created using either hyphens (-) or asterisks (*). Numbered lists are created starting with a number followed by a period. Bullets and numbers can be used interchangeably within a list

To indent, use 4 spaces.

The following markdown...

- Main bullet
    - sub bullet
        - sub sub bullet

1. Main bullet
    1. sub bullet
        1. sub sub bullet
        2. sub sub bullet
    2. sub bullet
        1. sub sub bullet
        2. sub sub bullet

... produces the lists below:

  • Main bullet

    • sub bullet
      • sub sub bullet
  • Main bullet

    1. sub bullet
      1. sub sub bullet
      2. sub sub bullet
    2. sub bullet
      1. sub sub bullet
      2. sub sub bullet

Tables

Markdown tables used to be created using the narrative-table-container wrapper. Now it can be created without. For example:

| A | B | Ouput |
| --- | --- | --- |
| 0 | 0 | 0 |
| 0 | 1 | 1 |
| 1 | 0 | 1 |
| 1 | 1 | 1 |

will result in:

A B Ouput
0 0 0
0 1 1
1 0 1
1 1 1

Some rules in regard to table markdown rendering:

  • The number of columns with dashes, under the table headers, should be the same as the number of columns.
  • If there are text following the table, there should be a <br> tag after the closing </div> tag.

LaTeX

```tex allows TeX directives to be written into instructional narrative.

x^2 + y^2 = 1

will result in:

LaTex forumula

y = \sqrt{1 - x^2}

will result in:

LaTex forumula

\sum\limits_{n=1}^{\infty} 2^{-n} = 1

will result in:

LaTex forumula

Keyboard Input

Keyboard inputs should be enclosed by the <kbd> tag:

<kbd>control</kbd> + <kbd>c</kbd>

will result in:

control + c.

The <details> HTML element is used to hide information that can be revealable by clicking on <summary> text. Here's an example:

Click here to see more information! This will be hidden until someone clicks on "Click here to see more information!". There needs to be a space before this paragraph, otherwise, markdown like `this` won't render properly.

The syntax for creating this "dropdown" content looks like this:

<details>
<summary>Click here to see more information!</summary>

This will be hidden until someone clicks on "Click here to see more information!". There needs to be a space before this paragraph, otherwise, markdown like `this` won't render properly.

</details>

A few tips: * There must be a new line between the closing </summary> tag and the contents of the dropdown in order for markdown to be rendered inside the <details> element. * Check out this live example (scroll down to the "Testing" header)