Creating Code Blocks with Backticks

Date: 15 April 2018

Category: Jekyll

Tag: Markdown

This GitHub help page, and the Markdown documentation, outlines one method of creating and highlighting code blocks:

You can create fenced code blocks by placing triple backticks ``` before and after the code block. We recommend placing a blank line before and after code blocks to make the raw formatting easier to read.

An example of this is as follows:

    ```
    function test() {
      console.log("notice the blank line before this function?");
    }
    ```

What language is that?

It is possible to indicate what language your code block is written in, which will result in appropriate syntax highlighting.

For example, in this wiki article, I have the following code snippet:

def determine_source_type(url):
    url = url.upper()

    internal_url_indicators = ('company.com', 'company.internal.com')
    shared_drive_indicators = ('company_drive_1', 'company_drive_2')
    external_url_indicators = ('HTTP', 'WWW', '.COM')

    if any(indicator in url for indicator in internal_url_indicators):
        return 'INTERNAL_URL'
    if any(indicator in url for indicator in shared_drive_indicators):
        return 'SHARED_DRIVE'
    if any(indicator in url for indicator in external_url_indicators):
        return 'EXTERNAL_URL'
    return 'UNKNOWN'

Which was generated using the following Mardown:

```python
def determine_source_type(url):
    url = url.upper()

    internal_url_indicators = ('company.com', 'company.internal.com')
    shared_drive_indicators = ('company_drive_1', 'company_drive_2')
    external_url_indicators = ('HTTP', 'WWW', '.COM')

    if any(indicator in url for indicator in internal_url_indicators):
        return 'INTERNAL_URL'
    if any(indicator in url for indicator in shared_drive_indicators):
        return 'SHARED_DRIVE'
    if any(indicator in url for indicator in external_url_indicators):
        return 'EXTERNAL_URL'
    return 'UNKNOWN'
```

The full list of languages supported for Markdown syntax highlighting can be found here.

Inception via Markdown

Additional note (and decending down another layer in an Inception-esque manor), the code used to generate the above code snippet (are you still with me?) was as follows:

<pre>
```python
def determine_source_type(url):
    url = url.upper()

    internal_url_indicators = ('company.com', 'company.internal.com')
    shared_drive_indicators = ('company_drive_1', 'company_drive_2')
    external_url_indicators = ('HTTP', 'WWW', '.COM')

    if any(indicator in url for indicator in internal_url_indicators):
        return 'INTERNAL_URL'
    if any(indicator in url for indicator in shared_drive_indicators):
        return 'SHARED_DRIVE'
    if any(indicator in url for indicator in external_url_indicators):
        return 'EXTERNAL_URL'
    return 'UNKNOWN'
```
</pre>

I used HTML in a Markdown page, which I typically try to avoid, but in this case it provided the neatest solution.

The <pre> tag denotes preformated text:

Text in a <pre> element is displayed in a fixed-width font (usually Courier), and it preserves both spaces and line breaks.

Lets do the time warp again

The next level of the dream: to escape the <pre> tags in the above code snippet, I used the HTML entity counterparts for the pointed brackets.

  • < becomes &lt;
  • > becomes &gt;