Syntax Highlighting with SvelteKit and mdsvex

Adding syntax highlighting to your dev blog can make or break the overall theme and feel of your site. If you've spent all this time on making your site look like an extension of yourself, but visitors reading your posts see code blocks that look like they've been copy/pasted from someone else's site, you might end up sending the wrong message to your visitors. Thankfully, building a blog in SvelteKit is quick and easy, and with the addition of mdsvex, writing your posts can be easier than ever thanks to the wonderful Markdown syntax.

What is mdsvex?

Mdsvex is a Svelte package that gives you the ability to transform markdown files into renderable content for the web. As a matter of fact, this blog post (and all the other ones on my website) are written in Markdown, and rendered with mdsvex.

The real power and benefit of using the mdsvex package is that, not only can you write posts in Markdown and have them rendered to the page, you can also add your Svelte components to the Markdown file and have them rendered too. But this post is about styling code blocks in mdsvex, so we'll save that for another time.

Styling your code blocks

Mdsvex and SvelteKit provide a lot of the functionality that you need to style code blocks right out of the box, so there aren't too many steps to follow before you have your blog posts looking like one, cohesive unit! Before you start, however, you need to make sure you have mdsvex installed into your SvelteKit project and have it rendering your markdown to the page. We won't go too much into that here, but if you want a quick and easy way to add mdsvex to your project (this is the way I did it, too), check out the svelte-add project.

Setting up your markdown code blocks

First things first, you need to set up a few code blocks in a markdown file that you can toy around with. I recommend setting up a code block or two for each of the languages you most typically write in, so in my case, I'd set up a few for PHP and a few for JavaScript. What you're trying to do here is get a good sample size of all of the types of code you'd likely be writing about.

In case you're fuzzy on how to write code blocks in markdown, here's an example of a PHP class code block (nestled inside a code block, nonetheless):

```php
class Dog extends Pet
{
    public function __construct(
        public string $name,
        public bool $isGoodBoy,
        public bool $isHappy
    ) {};

    public function pat(): void
    {
        $this->isHappy = true;
    }
}
\```

Code blocks in markdown are surrounded by three backticks in a row. You can give the markdown parser a little hint as to what language it should be looking for by adding the name of the included language immediately after your opening set of backticks.

Writing (or borrowing) your styles

The great thing about mdsvex is that, when your code blocks are rendered out to the page, all of the styling is controlled with the same sorts of CSS selectors that you use to style the rest of your website. Because of this, with a handful of CSS styles, you can make your code blocks look exactly how you want.

Now, you certainly can go through and write all of your CSS styles by hand, but I'd recommend using a prebuilt template that's close to what you're looking for, and then change the bits that don't quite match up to your mental model little by little. This is why I recommended having a few code blocks per language in an earlier section–when you have multiple examples; it's much easier to focus in on the specific things you want to change from a prebuilt theme.

Under the hood, mdsvex is using PrismJS to handle its syntax highlighting. The wonderful folks at Prism have actually compiled a very extensive list of themes that work with their package, so this is where we're going to grab our starter theme!

For my site, I started out with the default Gruvbox theme, but take a few minutes to look at that list and find the theme that comes the closest to matching your site. Once you've found the theme that you like best, we can add these styles to your website.

You can add your new syntax highlighting styles anywhere you prefer in your SvelteKit application, but my preference is to make a src/styles/ directory, add your CSS file (src/styles/gruvbox-dark-code.css, for example), and then import that file into your main css file. For my site, I added this line of code to the top of my app.css file:

@import url(./styles/gruvbox-dark-code.css);

If you liked the theme template you found, congratulations! You've successfully styled up your code blocks.

If you, like me, wanted to make a few tweaks to get things just right, here's the fun part. All you have to do to make changes to your theme is to edit the CSS file that we added previously, and watch your code blocks change before your eyes! If you get stuck and can't seem to figure out how to change a specific part of your code's appearance, since the code blocks are rendered to the browser as HTML and CSS, you can always just right-click the piece of code you want to check, open up your console to find the class, then write your CSS rule accordingly!

After all is said and done, you should now have a perfectly-styled code block section for your website! I'll leave you with the same code block we wrote above, but this time, styled with my Gruvbox-inspired color palette.

class Dog extends Pet
{
    public function __construct(
        public string $name,
        public bool $isGoodBoy,
        public bool $isHappy
    ) {};

    public function pat(): void
    {
        $this->isHappy = true;
    }
}