Syntax highlighting frustrations

[ruanspies]

Code blocks are a critical component of documentation. We have adopted Vitepress across all of our products and have really enjoyed the overall Vitepress setup but the usage of code block has been frustrating because of poor support from the Shiki project.

The supported languages are limited, which should not be an issue since adding grammar can be done quite easily. The frustration has been that when new grammar is added, it does not result in a new package to be built and therefore does not reflect in Vitepress.

The maintainers of the project are also not very responsive which makes it difficult to get momentum going on the project such that it best serves its need.

Is there perhaps room to consider an alternative syntax highlighter in Vitepress?

[brc-dd]

You can pass a custom function as markdown.highlight. Refer markdown-it docs: https://github.com/markdown-it/markdown-it#syntax-highlighting

[brc-dd]

Just pass it directly:

markdown: {
  highlight: () => {...}
}

[ruanspies]

Great thanks. I have now added it in this way:

markdown:{
	highlight: function (str, lang) {
		if (lang && hljs.getLanguage(lang)) {
			try {
				return hljs.highlight(str, { language: lang }).value;
			} catch (__) {}
		}

		return ''; // use external default escaping
	}
},

But I still don't understand how this then links to the actual markdown document? Should Shiki then be disabled? Should the markdown have some explicit link to this custom function?

[brc-dd]

It'll be picked up automatically, you just need to add the stylesheet. Refer this for a complete working example: https://stackblitz.com/edit/vite-cepfxn?file=docs%2F.vitepress%2Fconfig.ts

PS: Some stuff related to code blocks might break (like line highlighting). You'll need to adjust your highlighting function accordingly.

[ruanspies]

Thanks so much for the example @brc-dd this helped to understand.

Using the default export rather than defineConfig, I have setup my config.ts to contain the following:

export default {
	title: 'Site Title,
	description: 'My description,
	head: [
		['link', { rel: "icon", type: "image/png", sizes: "32x32", href: "/assets/favicon-32x32.png"}],
		['link', { rel: "icon", type: "image/png", sizes: "16x16", href: "/assets/favicon-16x16.png"}],
	],
	markdown:{
		highlight,
	},
	themeConfig: {
	    ...
	}

[ruanspies]

Just a question on the side, is there a reason why shiki is used rather than prismjs as the default syntax highlighter?