Markdown and Git in, a fast documentation site out. Blekk previews and checks a Markdown documentation site right in VS Code. You write pages in Markdown, commit them with Git, and see the finished site on localhost as you save. Nothing else to install: the Blekk engine runs inside the extension.
Blekk is Norwegian for ink.
Features
Live preview.Blekk: Preview (or Preview in the status bar) opens the site on http://localhost:4000. The page reloads by itself when you save. If a change breaks the build, the errors are shown over the page while the last good version stays up.
Problems as you save. Broken links and anchors, missing images, unknown components, bad frontmatter and more appear in the Problems panel with the file and line.
The same output as the published site. The preview runs the same engine and sends the same security headers (including the Content-Security-Policy) as the published site, so what works in the preview works when published.
Fast. A full rebuild of a site with about fifty pages takes around a tenth of a second.
Requirements
Git, which VS Code uses anyway. Blekk reads each page's last change from it ("last updated").
A workspace laid out the way Blekk expects:
site/config.yaml the site's settings
site/content/ one Markdown file per page; folders become menu sections
site/assets/ shared files
theme/ templates, CSS, JavaScript and icons
The folder names can be changed with the settings below.
Commands
Command
What it does
Blekk: Preview
Starts the preview and opens it in the browser (or opens it, when it runs)
Blekk: Stop Preview
Stops the preview server
Blekk: Check
Checks the whole site and shows the Problems panel
Settings
Setting
Default
What it does
blekk.port
4000
The preview's port. If it is taken, the next free one is used
blekk.siteFolder
site
The folder with config.yaml and content/, relative to the workspace
blekk.themeFolder
theme
The theme folder, relative to the workspace
Good to know
Search works on the published site, not in the preview. The search index is built by Pagefind, a separate program that runs when the site is published.
The check messages are in Norwegian for now, as the first site built with Blekk is. English messages are planned.
Blekk is young. Building and publishing the site is done with the blekk command-line tool, from the same engine.
Licence
MIT. The licence text is included with the extension.