TIL: A Little More About Pelican

My Own Worst Enemy

I was getting some weird behavior with my <code> and <pre> tags on my blog. For some reason I was using my custom.css stylesheet to make a few "tweaks" to these tags and shocker it was causing some weird display issues. So I decided it was time to dive into the Python-Markdown module to understand a little better how these tags work with markdown. EDIT: OK, so it was not entirely my fault I was seeing these bugs and the process of making this post has helped me understand some of the stuff going on under the hood of Pelican, Python-Markdown, Pygments, and CSS.

Python-Markdown

I write these post's in convenient markdown language and Pelican processes them and spits them out in HTML and CSS using Python-Markdown ready for my web server to host. Python-Markdown has extensions, one officially supported extension is CodeHilite. This as you might guess is part of our syntax highlighting code magic.

Code Marking

There are several way's to mark code in markdown. Inline, backtick blocks, and indented blocks.

Inline Code

Backticks

Inline code will produce html with <code> tags wrapped around the code. Enclosing `text inside backticks` will mark it as a <code> span inside a normal paragraph. Resulting in the following html.

<p>There are several way's to write code in markdown:
<code>`</code> backticks are one way. Enclosing <code>`text inside backticks`</code>
will mark it as a <code>&lt;code&gt;</code> span inside a normal paragraph.</p>

Code Block

Triple Backticks McTwist

OK, so there is no McTwist but we can use three backticks to open and close a code block, eat your heart out Shaun White. This will wrap the HTML in <pre> and <code> tags.

```
three consectutive backticks will also work above and below
```

Indenting

Indenting can also be used for marking code. Indents will create <pre> and <code> tags in the HTML output. Four spaces at the beginning of each line will mark it as a code block.

    #!/bin/bash
    echo '1337 Code Here'

Indented markdown rendered as HTML.

<div class="highlight"><pre><code>
#!/bin/bash
echo &#39;1337 Code Here&#39;
</code></pre></div>

Lexing

So now we can use markdown to mark inline and code blocks. But one thing remains and that is telling the rendering engine Python-Markdown what language is being used. This is called lexing the code, we have to define what code we are using so that we can properly define how to display code. There are three ways to do this all with different effects.

Full Shebang #!

OK, that heading was fun. If the first line of a code block has a full shebang then the shebang line will be included in the displayed code block and the code block will have line numbers.

#!/bin/bash
while [ script != 'something clever' ]; do
    echo 'try again'
done

Half Shebang?

A shebang with out a path #!bash (a single / or even a space) then the shebang line is removed but line numbers are kept.

#!bash
> make me a samich
> sudo make me a samich

Result

> make me a samich
> sudo make me a samich

Colons

OK, let's ditch the line numbers. Using three consecutive colons followed by the language :::bash, removes the line and the line numbers.

:::bash
> make me a samich
> sudo make me a samich

Renders as:

> make me a samich
> sudo make me a samich

<wrap> up

I learned a lot about how Pelican, Python-Markdown, and pygments work in the process of making this post. Next I want to explore pygments a little more and figure out how to use it to customize the theme for my code blocks (those line numbers are hideous right now). I did also figure out that the theme I am using does seem to have some margin and padding settings that are causing a little weirdness that I want to dive into. For now I simply override those settings with a custom stylesheet.