thufie's blog

The writefreely software depends on a javascript plugin called highlight.js to support syntax-highlighting for code-blocks in your blog posts. This guide will outline how to effectively integrate this feature into your blog and customize it to best suit your blog's style. Syntax highlighting isn't possible for inline code, but you can still make it look fairly nice as well if you reference my custom CSS. Preemptive disclaimer: I'm not a web-dev so I don't actually know the proper terminology for some javascript and CSS stuff so let me know on the fediverse if I made any mistakes in that regard.

Here's the general outline: 1. Use the correct markdown spec to specify your coding language 2. Avoid using hashtags in the code block (octothorpes if you are a nerd) since they break with the code block plugin 3. Add a fix to your blog's custom CSS to disable line-wrapping and add a horizontal scrollbar to the code block 4. (Optional) Setup a custom code block color theme to match your blog

Making a code block which specifies the coding language

To specify the coding language in your code-block so the plugin can do fancy syntax-highlighting you need to specify the name of the coding language right after you begin the code block like in this picture:

This code block is specifying that the code inside of it is CSS so the plugin can correctly highlight it. If you do not know what the name for a language might be you can browse the languages supported by the highlight.js plugin here.

By default the plugin on write-freely instances only actually has support for a small subset of these languages downloaded. You can tell which languages are supported by your instance by viewing the source of your blog page when it has a code block on it and searching for “var langs” which has a list of all the languages your particular instance supports next to it. If your language is not in this list, but it is in the list above, consider contacting your admin and asking them to download a version of highlight.js with your language supported.

Avoid using hashtags in the code block

“How can we move forward here? This is probably less trivial than it looks.” – mrvdb on github

Unfortunately writefreely has a known bug that causes hashtags inside of codeblocks to be parsed incorrectly. Until this is fixed, any code blocks containing one will be horribly mangled by an ugly html tag that appears in place of the hashtag. If you are using a language which has syntactically meaningful hashtags (not just for comments, which can be done with the blog post itself), it may be worth substituting hashtags with this character “⋕” and just letting your reader know since if they copy-paste it and get syntax errors they will be very confused.

Fixing your custom-CSS with a scrollbar

By default, writefreely's highlight.js theme has line-breaks enabled which can lead to ugly messes like this: To avoid this, you can add this CSS to your blog's custom CSS:

/* custom line-wrapping fix for highlight.js */
.hljs {
    white-space: pre !important;
    overflow-x: auto !important;
}

Once this has been added, line-wrapping will no longer occur, and a scrollbar will be added to the bottom of the codeblock view which allows readers to scroll horizontally and reach any code which was previously out of sight.

Setup a custom code block color scheme

The highlight.js project has a large variety of CSS themes to choose from here and installing one of them is almost as simple as copying and pasting. I say almost as simple, because you will have to do a bit of slightly-tedious correction work that anyone should be able to figure out even if you don't know CSS syntax.

Since your writefreely instance has a preset syntax-highlighting color scheme set for highlight.js for default, that means that your custom theme CSS has to override the defaults, which in practice just means adding !important after every single property. The code block with the fix for line-wrapping does this above, but for reference here is my blog's custom CSS with the a11y-dark theme at the bottom of the file using !important on every CSS property. I recommend editing a custom CSS file in your own editor rather than just pasting it straight into the custom-css box on your blog's settings page since the box on your settings page does not let you copy text out of it with your clipboard (at least in my experience).

With all that done, you should have fairly-functional and aesthetically appealing code-blocks for all of your blog posts.S