Code blocks
To include a code block in your document, place three backticks (```) before and after the code block and, optionally, add a language name.
Leave one blank line before and after the block for easier reading.
```javascript
console.log("Hello world");
```
console.log("Hello world");
Tip: Display triple backticks in a code block
You can always add more backticks! For example, to display triple backticks in a code block, wrap them inside quadruple backticks.
````md
```
Look! You can see my backticks.
```
````
renders as:
```
Look! You can see my backticks.
```
Syntax highlighting
To make your code block clearer, specify the language right after the first three backticks to enable syntax highlighting.
```python
print("Hello, world!")
for i in range(10):
print(i)
```
renders as:
print("Hello, world!")
for i in range(10):
print(i)
Internally, this uses the Pygments library. Check the long list of available languages. This only adds HTML classes; the styles and colors themselves are controlled by CSS.
Showing Line Numbers
To show line numbers in your code block, specify the starting line number with the option linenums="1" after the opening tokens (and language, if present).
The number must be quoted, and it is the number of the first line (it must be greater than 0).
```python {linenums="1"}
import foo.bar
a = "lorem"
b = "ipsum"
```
renders as:
import foo.bar
a = "lorem"
b = "ipsum"
If you want to start with a different line number, simply specify a number other than 1.
```python {linenums="42"}
def foobar():
a = "lorem"
b = "ipsum"
foobar()
```
renders as:
def foobar():
a = "lorem"
b = "ipsum"
foobar()
Pygments also has a few additional options regarding line numbers. One is "line step," which, if set to a number larger than 1, will print only every nth line number.
```python {linenums="1 2"}
"""Some file."""
import foo.bar
import boo.baz
import foo.bar.baz
```
renders as:
"""Some file."""
import foo.bar
import boo.baz
import foo.bar.baz
Highlighting lines
You can specify certain lines for highlighting by using the hl_lines setting directly after the opening tokens (and language, if present), with the targeted line numbers separated by spaces.
```python {hl_lines="1 3"}
"""Some file."""
import foo.bar
import boo.baz
import foo.bar.baz
```
renders as:
"""Some file."""
import foo.bar
import boo.baz
import foo.bar.baz
Line numbers are always referenced starting at 1, regardless of what the line number is labeled as when showing line numbers.
```python {linenums="42" hl_lines="2"}
def foobar():
a = "lorem"
b = "ipsum"
foobar()
```
renders as:
def foobar():
a = "lorem"
b = "ipsum"
foobar()
If you'd like to highlight a range of lines, you can use the notation x-y, where x is the starting line and y is the ending line. You can specify multiple ranges and even mix them with individual lines.
```python {hl_lines="1-2 5 7-8"}
import foo
import boo.baz
import foo.bar.baz
class Foo:
def __init__(self):
self.foo = None
self.bar = None
self.baz = None
```
renders as:
import foo
import boo.baz
import foo.bar.baz
class Foo:
def __init__(self):
self.foo = None
self.bar = None
self.baz = None
Title Headers
A header with a title can be applied to a code block using the title option. Typically, you use it to show a filename, but it can be anything.
```python {title="cool_file.py"}
import foo
import boo.baz
import foo.bar.baz
class Foo:
def __init__(self):
self.foo = None
self.bar = None
self.baz = None
```
renders as:
import foo
import boo.baz
import foo.bar.baz
class Foo:
def __init__(self):
self.foo = None
self.bar = None
self.baz = None