Question: css styling of code blocks in html output

[Joe Lotz]

I'm pretty tired so this may be a dumb question, but...

Back in "vanilla" pelican (before using pandoc-reader) it used the python-markdown converter and syntax-highlighting using pygments. The code blocks in the output html were wrapped in a div class named "highlight" and the html was made pretty by pygments css files.

We could generate different css files for all the different code styles to style the html code blocks:
pygmentize -S default -f html -a .highlight > default.css

When I use this awesome plugin we are no longer using pygments (rather pandoc) and the html output of the code block has different div class names so they highlighting css files are moot.

Where can I find code highlight style css files that are pandoc-friendly? I assume they are standard to pandoc but I don't seem to find anything googling, which means I'm going down the wrong path or have a misunderstanding of what's going on. :-(

Thanks for any advice pointing me in the right direction!

[nandac]

Hi @joelotz

All the plugin does is take the Pandoc you give it and it returns the HTML of the content so it has no idea about syntax highlighting.

To get highlighting for code blocks I just included the CSS for code highlighting into section of my base.html template in Pelican.

Hope that helps.

[Joe Lotz]

Hi @nandoc, I realize this is a pandoc question and not a plugin question, my apologies. I was just expecting pandoc to offer standard CCS sheets like pygments does. Did you build the CSS for code highlighting from scratch? It seems like pandoc would provide the standard styling. Do you mind sharing a link to your website as an example?

[nandac]

@joelotz

To get the CSS stylesheet for a particular code highlight style try this command:

pandoc --print-highlight-style pygments

But this gives a JSON document with the CSS styles.

I think the best way is to generate your document into HTML with your preferred highlight style and then copy the CSS between the <style></style> tags in the head section and move that to a separate CSS file and reference it in your HTML templates. That is what I did.

Nanda

[Joe Lotz]

@nandac
I've found a solution, thanks for your help! This is definitely a pandoc question and not a pandoc-reader issue, but I think it is important as anyone using this plugin on a markdown file with code fences will have to deal with. I'll reply to this with another comment trying to explain the problem and solution.

[Joe Lotz]

Highlighting (i.e. adding color) to the pandoc-generated html code blocks.

Background

Syntax highlighters apply html class ids to different parts of the code-block syntax depending on the language identified. For example, if the markdown code block looks like

​```python 
# This is a comment
​```

after converting to html it will look something like

<div class="highlight">
	<code>
		<span class="c"># This is a comment</span>
    </code>
</div>

And the magic sauce is that we can say in out CSS “color anything that is a comment green.” Something like this

.highlight .c { color: #408090; font-style: italic } /* Used for Comments */

Which means anything inside a class named “highlight” and a class named “c” will be green and italicized.

For "standard pelican" the code-highlighter used was pygments and the CSS files that defined what formatting to apply to the classes was known. There were different CSS files for different highlighting styles.

Problem

When Pandoc generates highlighted html code it doesn’t use the same class names as pygments, so we have to find new stylesheets to color the generated html. Meaning now it looks something like

<div class="sourceCode">
	<code>
		<span class="co"># This is a comment</span>
    </code>
</div>

Notice the class names are different. This is fine, we just have to re-define our styling. But instead of hand-building the stylesheets there must be an automated method.

Solution

Stylesheets can be generated from pandoc just like in pygments, however, it is a little more tricky. The answer is here: https://stackoverflow.com/questions/62774695/pandoc-where-are-css-files-for-syntax-highlighting-code. Assuming you are using pandoc > v2.11 as recommended in the plugin requirements, here are the steps -

1. Create a file named highlighting-css.template with the following content:

   $-- this is file highlighting-css.template
   $highlighting-css$
   

2. Create a file named sample.md with the following content:

   ~~~html
   <p>placeholder</p>
   ~~~
   

3. See the possible highlight styles by typing this in a terminal pandoc --list-highlight-styles

4. Select a style, for this example let’s assume you choose the popular “pygments”

5. In the same directory as the files you made, generate the stylesheet with this command pandoc --highlight-style=pygments --template=highlighting-css.template sample.md -o pygments_highlighting.css

• You should see a generated file named pygments_highlighting.css that you can attached to your blog.

6. Here's another example, suppose you choose the style espresso. You would use the command pandoc --highlight-style=espresso --template=highlighting-css.template sample.md -o espresso_highlighting.css