Microsoft Visual Studio Code
TL;DR Contributing to Visual Studio Code Timeline
What a better way to kick off the new term by continuing right where I left off. Contributing to the open source community. This time around things are going to be a little different. Last semester we were taught the necessary skills and methods to become a successful contributor. Now it’s time to take those skills and continue to grow them with new experiences and practice.
We’re encouraged to step outside of our comfort zone and take on much larger projects/tasks. Maybe it’s that project you always found interesting but too overwhelming. Or how about that open source code editor you use day in and day out?
In this case that was me. I’ve wanted to work on Microsoft’s Visual Studio for quite a long time now. It’s an application that I’ve been using on a daily basis for 3 years now. How cool would it be I can work on a contribution…within the contribution.
The first place I always start off with any new project is the README.
Before I began searching through the 3000+ issues I made sure to setup my development environment. The last thing you want to do is take on a new issue before you can even begin working on it. From past experiences, the setup is the most frustrating and time-consuming task.
With a well detailed, straightforward guide (How to Build and Run VSCode Source), the VS code build process went smooth. A little too smooth…
Searching for a Bug
Once I had my dev environment setup it was time to start searching for a good first bug. I began scrolling through the unfiltered issue page to get a feel for the process.
I came across a bug related to a CSS Emmet feature. So like any new contributor, I opened with my “noob” introduction comment. “I am a new contributor to the vs code community…”
Shortly after I received a response from Ramya Rao, a VSCode member. Ramya had politely informed me that this bug had quite some history behind it and that a whole lot would be changing in the upcoming release. So it was best that she worked on the fix. She had also suggested taking a look at the help-wanted tag for bugs open to contributions.
I took Ramya’s advice and quickly learnt that the help-wanted tag was the best place to search for new issues. Even over the Good first bug tag.
After a short search, I committed to working on Issue#41650 – Support TOML frontmatter syntax highlighting in markdown files.
The author had suggested that “It would be great if VS Code highlighted TOML frontmatter in markdown files like it already does with YAML.”
I’ll be honest, I’ve never worked with syntax highlighting let alone heard of Hugo, Front Matter, TOML.
This sounded like the perfect challenge.
Dissecting the Bug
Luckily for me, Matt Bierner was a huge help in getting off the ground.
He had provided two possible solutions.
Now if you know me, the moment I read “This would be the cleaner approach”, that was the only approach. You know, because it wasn’t already challenging…
To breakdown the possible solutions:
Easy Fix: Visual Code has native support for various languages such as Markdown. The markdown.tmlLanguage.json file contains a ton of rules for syntax highlighting in a Markdown file.
For example, when you create a fenced code block to highlight a specific language.
``` ruby
require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html
```
Displays as
Cleaner Fix: Contribute directly to the TOML syntax highlighting extension, better-toml. This is VSCode’s most popular TOML syntax highlighter. The plan would be to inject a new rule which targets markdown frontmatter.
Foreign term update: Hugo, Front Matter, TOML, tmLanguage, grammar injection.
In order to fix a problem, you have to understand the problem. Considering I had zero knowledge of syntax highlighting and VSCode extensions, I knew I had some serious research to start doing.
Research
I spent a couple days looking examining the code of syntax/ grammar extensions and the methods used to detect a syntax within various file types.
TOML (Tom’s Obvious, Minimal Language)
- easy to read configuration file format
- map unambiguously to a hash table
- easy to parse into data structures in a wide variety of languages
- Language grammars are used to assign names to document elements such as keywords, comments, strings or similar
- syntax highlighting and to make the text editor “smart” about which context the caret is in
- Visual Studio Code extension that supports syntax highlighting for TOML files.
- allows you to keep metadata attached to an instance of a content type
- supports JSON, YAML, and TOML
At this point, I was confused as to how the injection would tie into VS Code grammar. So I reached out for some clarification.
To be continued…
Matt pointed me to his demo repo, vscode-fenced-code-block-grammar-injection-example. This was a great help as it highlights how an extension separate from the editor was able to inject a simple code block using regular expressions. The only issue now was figuring out how to make it work with a language that isn;t natively supported in VS code.
In a follow-up post, I will be going more in-depth about my failed attempts and what really goes into creating a syntax highliter.
Update R0.1.2 | Injecting Front Matter Syntax Highlighting in Markdown Files
