Syntax Highlighting with Pygments

Markdown for Python supports syntax highlighting in your documents using Pygments. Here’s how to set up and use it from Markdoc.

First, install the extension in your markdoc.yaml file:

wiki-name: My Wiki
## ...other settings...
markdown:
  extensions:
    - codehilite # the important bit

Pygments should have been installed as a dependency when you installed Markdoc.

Initially, syntax highlighting will be applied to every code block Markdown encounters. Pygments will guess which lexer to apply to each block. To specify the language of a block, add a :::LANG prefix to blocks of code. For example:

:::python
def hello():
    print "Hello, World!"

Will render to:

def hello():
    print "Hello, World!"

To switch syntax highlighting off for a block, use :::text.

If you want a block to have line numbers, use #!LANG instead. For example:

#!ruby
class Foo
  def bar
    @baz
  end
end

Will render to:

1
2
3
4
5
class Foo
  def bar
    @baz
  end
end

If you add a shebang to a code block, like #!/bin/bash or #!/usr/bin/env python, the language will be guessed and the shebang included in the output. In the final text. So for example, the following:

#!/bin/bash
echo "Hello, World"

Will render to:

1
2
#!/bin/bash
echo "Hello, World"