Formatting Code for Blogs & Websites

From the archive. Published 4 years ago. Power BI and Fabric have changed since, so parts of this may be out of date or describe features that no longer work this way.

Formatting code improves readability & accessibility; below I share some tools I use for this

FORMATTING & HIGHLIGHTING CODE

WHY IT’S HELPFUL

When we talk about formatting code, we usually refer to one of two things:

Formatting the code inside the application or where it is used
Formatting & highlighting the code for sharing, either in documentation or a website/blog

For (1), it’s not necessary to highlight the code, since that is done in the application, itself. Rather, the code should be arranged in a readable and concise way. Examples include using indentations and spacing to ensure that there isn’t too much text density on the screen, and to segregate semantic elements or functions. For example, having comments either above or to the right of the line they refer to, or having indentations for nested function calls.

For (2), this is also important; however, the key words and functions should also be highlighted like in the application. This is to exploit the implicit knowledge about what certain words are. So with DAX, if someone sees a purple field between square brackets, they know it’s a measure. Some best practices are listed below:

Use the best practices for formatting agreed to by the community. This is typically documented for each language and easy to find by searching.
Use the highlighting style from the application. If different applications use different styles (i.e. with Python between Visual Studio, Colab, etc.), use the most common or popular one, generally.
Be consistent - if there are certain ways that you are formatting or highlighting code, ensure consistency across the code blocks.
Ensure sufficient contrast between the code and the background. For example if you are using a style from an application’s dark mode (i.e. VS Code Dark), make sure the code block also has the same background colour so it’s readable.
Include comments, titles & section breaks. Logically break up the code into readable sections using comments, and ensure that code has common-language explanations for non-obvious things.
Use Github Gists if you can’t format the code another way; but don’t use them if you are unable to embed the gist in the site.

PYGMENTS: HTML CODE FORMATTING PROGRAMMATICALLY

Pygments is an extremely handy tool for formatting and highlighting code. I use it mainly to format Python and C# with the below script:

The below are a running list of tools I use to format codes in my blog posts. I will keep them up-to-date as I blog about new languages or discover new tools / more efficient ways to use existing tools.

DAX

Website: DAX Formatter https://www.daxformatter.com/

Programmatically: DAX Formatter API

Software: Tabular Editor 3, Bravo, DAX Studio

Power Query

Website: https://www.powerqueryformatter.com/

Programmatically: Power Query Formatter API

Python

Online: http://hilite.me/

Programmatically: *pygments *https://pygments.org/docs/ Example

Online: C# Syntax Highlighter (warning: ads) https://www.pvladov.com/p/syntax-highlighter.html

Programmatically: *pygments *https://pygments.org/docs/

Tables (not code)

Online: tableizer! https://tableizer.journalistopia.com/

Public Gist (All Code; via GitHub)

From https://gist.github.com/ you can create a public gist and then embed this inside of your site.

This is one of the easiest ways that doesn’t involve embedding the HTML. Unfortunately, however, web services like SquareSpace don’t allow embedding .js scripts; so the github gist doesn’t work on those platforms.

Example: Github Gist for a small Python snippet that uses pyments to generate html highlighting Python code.

JSON

Programmatically: Pretty-printing a json string variable, x using json.loads(x) in Python is a good example.

Software: Notepad++ JSON Viewer: Plugin added from the Plugins Admin UI; very easy to do.