Formatting Code for Blogs & Websites

May 5

May 5 Formatting Code for Blogs & Websites

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.

  let Source = Table.FromRows(Json.Document(
  Binary.Decompress(Binary.FromText(
  "i45WcknNySxLLUpNUQhKLUvNK01V0lEyBG
  KXIKVYnWgl/6KU1KJiIN8IiKGc2FgA", BinaryEncoding.Base64), Compression.Deflate)), let _t = ((type nullable text) meta [Serialized.Text = true]) in type table [Measure = _t, Order = _t, Abbreviation = _t]) in Source


   Unformatted Power Query code 

let
  Source = Table.FromRows(
    Json.Document(
      Binary.Decompress(
        Binary.FromText(
          "i45WcknNySxLLUpNUQhKLUvNK01V0lEyBGKXIKVYnWgl/6KU1KJiIN8IiKGc2FgA",
          BinaryEncoding.Base64
        ),
        Compression.Deflate
      )
    ),
    let
      _t = ((type nullable text) meta [Serialized.Text = true])
    in
      type table [Measure = _t, Order = _t, Abbreviation = _t]
  )
in
  Source
  

   Formatted & highlighted Power Query code from powerqueryformatter.com.
  
 
  It's obvious what is easier to read, no?

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:

Example with pygments
  
# Script to format & highlight Python code with HTML.
from pygments import highlight

# Just change the Lexer to do a different language (i.e. C#)
from pygments.lexers import PythonLexer
from pygments.formatters import HtmlFormatter

code = "print('I used the Python to format the Python')"

result = highlight(code, PythonLexer(), HtmlFormatter())

# You need to add the classes to the custom CSS of your blog / website, first:
print(HtmlFormatter().get_style_defs('.highlight'))

# This is the HTML code for highlighting the script:
print('\n', result)

TOOLS FOR FORMATTING POWER BI-RELATED CODE

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.

Website: DAX Formatter
https://www.daxformatter.com/
Programmatically: DAX Formatter API
Software: Tabular Editor 3, Bravo, DAX Studio
Website: https://www.powerqueryformatter.com/
Programmatically: Power Query Formatter API
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/
Online: tableizer!
https://tableizer.journalistopia.com/
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.
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.