Syntax highlighting makes a huge difference when reading blog posts! However, given the limitations of HTML, this effect doesn't come easy. A lot of really smart people have worked on solutions to this problem. I looked at a few of them and decided to go with the FormatToHtml tool from Jeff Atwood at Coding Horror.
When I looked at the tools, I was looking for something that would work with my specific situation:
For source code syntax highlighting, I considered the following tools:
I chose FormatToHtml because Jeff's utility gave the best output and was easy to use. In the future, I may switch to something with fancy features like scrolling, line numbers, a copy to clipboard button, etc. For now, I wanted a tool that gave clean and consistently styled HTML.
Advantages of using FormatToHtml:
- It was quick to use. I could press my shortcut key and nice HTML formatted code was in my clipboard.
- It was not keyword dependent. I didn't need to edit the syntax highlighting if I used beta software or newer versions of the framework.
- It was open source. I have modified it for my own needs.
- I could copy code formatted by this utility directly into Visual Studio. Some tools add extra line breaks between the lines of code. Other tools will include the line numbers in the text you copy from the web. This tool doesn't.
- It used inline styling, which allowed the code to be formatted in RSS readers.
- It worked with Windows Live Writer.
Disadvantages of using FormatToHtml:
- Since it used the same color scheme as your IDE, any color changes you've made will be on the web. This is great for you, but others might not like it as much. For consistency and ease for others to read your code, the best samples will use Visual Studio's default coloring. Since I use the default coloring, this limitation didn't impact me.
- It did not retain the background highlighting. There is not much background highlighting in Visual Studio, so this is not typically noticeable. However, on ASP.NET pages, there is a lot of highlighting. I modified the original code to support ASP.NET background highlighting.
Setting Up FormatToHtml:
I found the setup for Visual Studio 2008 the be a little different than Jeff's original instructions.
The first trick was figuring out how to open the Macro Explorer in Visual Studio 2008. I didn't have a "Tools | Macros" menu option. The easiest way I found to open the Macro Explorer is with ALT+F8. It is a small window and looked something like this.
Once the editor was open, I noticed that a new macro in Visual Studio 2008 included two new "Imports" statements:
Imports EnvDTE80
Imports EnvDTE80
Assigning the macro to a shortcut key was fairly easy - the MSDN provides detailed instructions. I chose "ALT+C" for my shortcut key. It was close enough to the "Copy" shortcut key and was still unassigned. I decided to leave the default "Copy" behavior alone and not override it with Jeff's macro.
Which Macro should you bind to? For Windows Live Writer, use Modern or ModernText. Here's my understanding of the FormatToHtml macros:
- Modern and ModernText use DIV and SPAN
- Legacy and LegacyText use P and FONT.
- Modern and Legacy put the HMTL formatted output in both the clipboard object and the clipboard text.
- ModernText and LegacyText only put the HTML formatted output in the clipboard object and put the plain text version in the clipboard text.
Customizing FormatToHtml:
There was a simple logic bug in “PerformRtfConversion”. Basically, the condition was running backwards. It should have read like this:
If asTextOnly Then
SetClipboardHtml(html, text)
Else
SetClipboardHtml(html, html)
End If
To support ASP.NET background highlighting, I added a new method to scrub the HTML output for the special <% and %> character combinations. I added a configuration variable at the top of the code file to turn this functionality on and off easily. (I don't think I'll ever turn it off.) I used a screenshot of the code to figure out the precise background color. Neither HTML named color "Yellow" nor "Gold" looked correct.
Private Const _ApplyDefaultBackgrounds As Boolean = True
...
Private Sub PerformRtfConversion(ByVal asTextOnly As Boolean, ByVal useModernHtml As Boolean)
If Not SelectionToClipboard() Then Return
'-- retrieve text and rtf from clipboard
GetClipboard(DataFormats.Text)
Dim text As String = Convert.ToString(_ClipboardObj)
GetClipboard(DataFormats.Rtf)
Dim rtf As String = Convert.ToString(_ClipboardObj)
If _RemoveExcessIndentation Then text = RemoveTextIndents(text)
Dim html As String = RtfToHtml(rtf, useModernHtml)
'-- HACK: SN: 3-26-08: Apply default editor background colors to selected characters
If _ApplyDefaultBackgrounds Then
html = ApplyDefaultBackgrounds(html, useModernHtml)
End If
If Not useModernHtml Then
html = ConvertSpanToFont(html)
End If
If asTextOnly Then
SetClipboardHtml(html, text)
Else
SetClipboardHtml(html, html)
End If
End Sub
...
Private Function ApplyDefaultBackgrounds(ByVal html As String, ByVal useModernHtml As Boolean) As String
If useModernHtml Then
html = Regex.Replace(html, "%>", "<span style='background-color:#FFEE62;'>%></span>")
html = Regex.Replace(html, "<%", "<span style='background-color:#FFEE62;'><%</span>")
Else
html = Regex.Replace(html, "%>", "<font style='background-color:#FFEE62;'>%></font>")
html = Regex.Replace(html, "<%", "<font style='background-color:#FFEE62;'><%</font>")
End If
Return html
End Function
To better support CSS styling, I added a class to the DIV tag that wraps the formatted output. This was in Function RtfToHtml.
'-- add block wrapper
If useModernHtml Then
rtf = "<div class='VSCode' style='" & _
"font-family:" & _CodeFontName & "; " & _
"font-size: " & _CodeFontSize & "; " & _
"background-color: " & _CodeBackgroundColor & ";'>" & _n & _
rtf & _n & _
"</div>" & _n
Else
rtf = "<p class='VSCode'><font face='" & _CodeFontName & "' size='" & _CodeFontLegacySize & "'>" & _n & _
rtf & _n & _
"</font></p>" & _n
End If
Using FormatToHtml with Windows Live Writer:
After I got used to using this tool to insert code into my blog posts, I memorized the keystrokes. It's pretty fast!
- Highlight the code you want to copy in Visual Studio
- Press your shortcut key (mine is ALT+C)
- Go to Windows Live Writer
- Press CTRL+SHIFT+V (or select the paste special menu item)
- Press the down arrow key (or select "Keep Formatting")
- Press ENTER (or click the OK button)
Here's the Windows Live Writer's "Paste Special" dialog:
Conclusion
Syntax highlighting makes a blog about source code more readable. FormatToHtml is a powerful and useful code syntax highlighting tool for Visual Studio. It provides nicely formatted output with clean HTML that retains the styling in RSS readers.
Since I chose to use FormatToHtml, I didn't really evaluate the following tools. If you are considering one of them, read Brix Lamoreaux's review.
I look forward to hearing about the tools you use for syntax highlighting.