Website Structure

First, let’s discuss what the website should look like. For complex websites, I would usually use tools such as Figma or its open-source alternative, PenPot, which I can recommend, to draft and design. However, a blog is not complex and often follows a similar structure. So I decided against it.

First, the website needs a home page that welcomes the visitor and tells them a little bit about yourself.

Next is an overview of all posts that lists them in a concise manner and lets the user search for posts of interest. While some blogs like to put this on the home page, I prefer a dedicated page to avoid packing the home page full of content.

Lastly, the website also has to show the posts themselves. This will often just be the rendered posts with some added styling.

In my blog, the home page should be at the root URL /, the post overview at /posts, and each post should be under the dynamic URL /post/[title] plus their title. For example, a post called Creating a Personal Blog should be under /post/creating-a-personal-blog.

Project Setup

pnpm create svelte@latest blog

export const prerender = true;

pnpm build

import mdsvexPkg from 'mdsvex';
const { mdsvex } = mdsvexPkg;

const config = {
	extensions: [
		'.svelte',
		'.md', // Tells svelte to include markdown files
		'.svx'
	],
	preprocess: [mdsvex()]
};

import { error } from '@sveltejs/kit';
import type { LayoutData } from './$types';

export async function load({ params }): LayoutData {
	try {
		const { default: page, metadata } = await import(
			`../../../content/posts/${params.slug}/index.md`
		);

		return {
			post: page,
			metadata
		};
	} catch (e) {
		throw error(404, 'Post not found');
	}
}

<script lang="ts">
	import type { LayoutData } from '../$types';

	export let data: LayoutData;
</script>

<svelte:component this={data.post} />

Development Workflow

Now that we have a simple example running, let’s quickly talk about the development workflow before writing more code.

Consistent code format as well as continuous testing and deployment help detect bugs and inconsistencies before releasing a new version.

I use eslint and prettier to enforce a consistent code style and build a small Continuous Integration (CI) pipeline to check our code after every push.

As I’m using GitHub to manage my code, I will only focus on GitHub workflows. Each workflow is a separate YAML file in the .github/workflows directory. Each workflow file defines its environment and what commands to runs. To check our code style, we only need a simple workflow that sets up Node and runs the eslint and prettier commands. My file looks like this:

name: Check format
on: push
jobs:
  check-format:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v3
      - shell: bash
        run: |
          npm install -g pnpm
          pnpm install
          pnpm eslint .
          pnpm prettier --check .

name: Deploy new release
on:
  release:
    types: [released]
jobs:
  deploy:
    runs-on: ubuntu-latest
    needs: check-format
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v3
      - shell: bash
        env:
          USER: ${{ secrets.USER }}
          SSH_KEY: ${{ secrets.SSH_KEY }}
          TARGET_DIR: ${{ secrets.TARGET_DIR }}
        run: |
          npm install -g pnpm
          pnpm install
          pnpm build
          mkdir -p ~/.ssh/
          touch ~/.ssh/known_hosts
          ssh-keyscan simonkurz.de >> ~/.ssh/known_hosts
          eval $(ssh-agent)
          ssh-add - <<< "$SSH_KEY"
          rsync -e "ssh" --delete -av build/ $USER@simonkurz.de:$TARGET_DIR/

Syntax Highlighting

While mdsvex has built-in support for syntax highlighting and I’m currently using it, I want to explain my process of how I tried to integrate better syntax highlighting with additional features.

Mdsvex uses Prism to implement syntax highlighting. While it works and looks good, I am not quite satisfied with its features and plugin system. I found the amazing rehype plugin rehype-pretty-code which adds beautiful and fine-grained syntax highlighting and has some very helpful features like line highlighting.

However, when I tried disabling syntax highlighting of mdsvex and instead added rehype-pretty-code it added some weird additional characters into the code. Based on my experiments, it seemed like it escapes the code but doesn’t correctly unescape. The root issue wasn’t with rehype-pretty-code but with the underlying syntax highlighting library shikiji. Even after trying many things, like hooking into the unified pipeline and adding a custom plugin to rewrite the syntax tree, I couldn’t fix my issue. It could be that rehype-pretty-code is working as intended and I was just using it wrong, but since I couldn’t get it to work, I decided to stay with Prism. However, I still intend to replace Prism with rehype-pretty-code in the future.

Table of Contents

For adding a static table of contents, I can use the rehype plugin rehype-toc together with rehype-slug. rehype-toc generates the table of contents based on the post’s headings. However, to make the table of contents actually link to the respective heading, rehype-slug must be used, which assigns each heading an id based on its text. Now, rehype-toc links to the heading, and clicking on an item will scroll to that section.

As stated previously, a static table of contents is nice and all, but I would like to implement one that actually shows which sections the user is currently viewing. Unfortunately, I couldn’t find any library that implements this for me, so I have to do it myself.

My overall approach was as follows. Each section, so the heading, its text, and every subheading, keeps track of how much of itself is visible. If a certain percentage is visible, it searches for the table of content entry that links to it and adds a CSS class to the element to highlight the entry.

First, I must wrap each section. By default, a heading and its content are two different HTML elements. However, we need to wrap them with one element to accurately keep track of their visibility. I will use the remark plugin remark-sectionize which does exactly this.

Next, I have to add some Javascript to each section to keep track of its visibility. Here, the first problem is that remark-sectionize uses a simple section HTML element to wrap each section. We have to replace this section element with a custom Svelte component. However, remark-sectionize doesn’t offer this functionality. Fortunately, we can use mdsvex’s Layout and Custom Component features. The layouts feature allows us to specify a Svelte file that is used by mdsvex to wrap the converted post. If we export a Svelte component in the layout component with the name of an HTML element (such as section), our exported component will replace the HTML element in the rendered.

For example, let’s say we have implemented the custom section in file section.svelte. Now, we can export this component in the module script of the layout component.

<script context="module">
	import section from './section.svelte';

	export { section, img };
</script>

Implementing a component that can keep track of its own visibility is relatively straight forward. Each sections uses an Intersection Observer to keep track of its visibility. If a defined percentage threshold is reached, it adds the CSS class toc-link-visible to every link that links to its id by using the query selector `a[href="#${sectionId}]`.

Additional Features

In contrast to the previously two more complex features, support for Mermaid can be added by using the library mermaid and initializing it in the post’s layout component.

<script lang="ts">
	import mermaid from 'mermaid';
	mermaid.initialize({ startOnLoad: true });

	onMount(() => {
		mermaid.run({ querySelector: '.mermaid' });
  });
</script>

At this point, I have implemented all requirements and can focus on some additional nice-to-have features that are simple to add. I will additionally add support for emojis with remark-emoji and GitHub-flavored Markdown with remark-gfm.

What is still missing?

Besides that the blog is obviously missing content, I want to add some additional features.

For example, I would like to enhance code blocks with a label that shows the programming language, a copy button that lets the user copy the code to the clipboard, and an optional banner to display a path. The path banner will most likely be the least often used feature, but I think it can be helpful for guides or posts like this.

The next major addition to the blog are write-ups. Sometimes when I solve challenges, like Hack The Box machines, I work on active machines or challenges where it is forbidden to publish write-ups. However, I would still like to make write-ups available to people who have already solved the challenge and know the flags. Following the initial release of this blog, I will come up with some concepts and ideas for how I could implement such a system. However, I fear that almost any sensible approach would require a server.