Code styling

If you just use backticks as below, you’ll get a mono-spaced text all in one color. No language-specific colors.

Code:

Example of `code` in a sentence.

Result:

Example of code in a sentence.

Codeblocks

Indent syntax

Indent the code by 4 spaces.

Code:

    # Indenting this line in markdown turned it into preformatted mono-spaced text, without any particular code syntax.
    print('Hello world'!)

Result:

# Indenting this line in markdown turned it into preformatted mono-spaced text, without any particular code syntax.
print('Hello world'!)

Backtick syntax

Use triple backtick also known as a fenced code block. You can optionally specify a language for format with - this works well in markdown on GitHub but you might need extra set up in a Jekyll theme to get it to work properly.

Code:

```python
# Triple quotes are for code blocks and give more control over the language.
print('Hello world'!)
```

Result:

# Triple quotes are for code blocks and give more control over the language.
print('Hello world'!)

Triple backtickcs also works well under bullet points - see Code snippets in lists.

The short name works too. Note that outside of GitHub, other editing tools like an IDE or StackEdit might only support the long or the short form of a language.

Code:

```py
print("Hello, world!")
```

Result:

print("Hello, world!")

You can even nest them, provided you have a bullet point.

Code:

```md
- Run the greeting.
    ```sh
    echo 'Hello'
    ```
```

Result:

- Run the greeting.
    ```sh
    echo 'Hello'
    ```

Supported languages

Some valid references for language-specific styling, focusing on the ones I use. There are many more available.

See also the Jekyll Supported Languages page.

These are usually based on the file extension.

  • markdown or md for Markdwn. The former shows better rendering in the GitHub editor view.
  • json for JSON.
  • json5 for JSON5, more advanced JSON. It support comments and superfluous comments, without giving red errors when rendered.
  • python or py, or for Python console with >>> lines use pycon.
  • ruby or rb for Ruby.
  • html for HTML.
  • javascript or js for JavaScript.
  • Shell
    • sh or shell across systems. I prefer sh but either works.
    • bash for Bash on Linux/macOS.
    • powershell for Windows PowerShell.
    • console - for interactive console. This can be used across programming languages but I usually use for shell. A line starting with say $ or > will be colored differently to the lines after it without. Great fror demonstrating the output of shell commands. Does not include language-specific syntax highlighting though. See Shell examples section.
  • diff for Git diff. Then lines should start with + or - for differences.
  • liquid for Liquid templating.
  • yaml or yml for YAML.
  • regex or re for Regex. The longer keyword actually provide more/better highlighting when viewing the rendered content.
  • mk, make, Makefile (or lowercase makefile).
    • These all work, I haven’t compared how well though.
    • Make sure to always use tabs for indentation within the codeblock, to avoid red warnings.
  • c for C.
  • c++, cpp, cplusplus for C++.

Examples

Shell

Content from MDBook.

I like to use sh a lot. I seem to get the same results as using shell and also the same as when using bash (except in rare cases like DocsifyJS where the Bash plugin doesn’t recognize sh).

You don’t have to use a dollar sign, but it helps indicate you are in a shell console.

Note the output is colored here, unlike in console below.

sh

$ cargo install mdbook-linkcheck
$ edit book.toml && cat book.toml
[book]
title = "My Awesome Book"
authors = ["Michael-F-Bryan"]

[output.html]

[output.linkcheck]  # enable the "mdbook-linkcheck" renderer

$ mdbook build
2018-10-20 13:57:51 [INFO] (mdbook::book): Book building has started
2018-10-20 13:57:51 [INFO] (mdbook::book): Running the html backend
2018-10-20 13:57:53 [INFO] (mdbook::book): Running the linkcheck backend

shell

$ cargo install mdbook-linkcheck
$ edit book.toml && cat book.toml
[book]
title = "My Awesome Book"
authors = ["Michael-F-Bryan"]

[output.html]

[output.linkcheck]  # enable the "mdbook-linkcheck" renderer

$ mdbook build
2018-10-20 13:57:51 [INFO] (mdbook::book): Book building has started
2018-10-20 13:57:51 [INFO] (mdbook::book): Running the html backend
2018-10-20 13:57:53 [INFO] (mdbook::book): Running the linkcheck backend

bash

$ cargo install mdbook-linkcheck
$ edit book.toml && cat book.toml
[book]
title = "My Awesome Book"
authors = ["Michael-F-Bryan"]

[output.html]

[output.linkcheck]  # enable the "mdbook-linkcheck" renderer

$ mdbook build
2018-10-20 13:57:51 [INFO] (mdbook::book): Book building has started
2018-10-20 13:57:51 [INFO] (mdbook::book): Running the html backend
2018-10-20 13:57:53 [INFO] (mdbook::book): Running the linkcheck backend

console

Note unlike the shell styles above, everything after a $ or > entry is all one color (which is nice if you don’t want t apply shell highlighting to something that is probably be plain text).

And it also separates output nicely in a different color to the input.

$ ncu
Checking package.json
[====================] 5/5 100%

 express           4.12.x  →   4.13.x
 multer            ^0.1.8  →   ^1.0.1

> ncu
Checking package.json
[====================] 5/5 100%

 express           4.12.x  →   4.13.x
 multer            ^0.1.8  →   ^1.0.1

This also works well if you have multiple commands and you want to alternative between input and output clearly.

$ cargo install mdbook-linkcheck
$ edit book.toml && cat book.toml
[book]
title = "My Awesome Book"
authors = ["Michael-F-Bryan"]

[output.html]

[output.linkcheck]  # enable the "mdbook-linkcheck" renderer

$ mdbook build
2018-10-20 13:57:51 [INFO] (mdbook::book): Book building has started
2018-10-20 13:57:51 [INFO] (mdbook::book): Running the html backend
2018-10-20 13:57:53 [INFO] (mdbook::book): Running the linkcheck backend

Diff

```diff
- a
+ b
```

- a
+ b

JSON

```json
{
    "foo": "bar"
}
```

{
    "foo": "bar"
}

With comments, use json5 to avoid getting errors for invalid content on GitHub. Note some platforms like StackEdit don’t recognized json5 but is okay.

```json5
{
    // This is a comment.
    "foo": "bar"
}
```

{
    // This is a comment.
    "foo": "bar"
}

Regex

```re
[a-f]+
```

[a-f]+

Note - from limited testing, I found that re works better than regex.

Code blocks in bullet points

It can look messy to alternate between bullet points and code blocks, especially if using numbered points.

But you can nest code blocks under bullet points, like this.

Code:

- First point
    ```
    My code
    ```
- Second point
    ```
    More code
    ```

Result:

  • First point 
      My code
  • Second point 
      More code

Warning

You may not start a nested code block with a dash. Markdown gets confused and the formatting looks broken.

So don’t do this:

  • First point ```
    • My code ```