Format Hugo markdown and code

Format your markdown using prettier and you are off to the races.

Hugo static site generator keeps everything simple. I just love the power of typing in something in markdown, and seeing the finished HTML pages and blog formatted to specs (in no time, I might add).

I use VSCode for writing markdown text. This works out beautifully - I can save markdown files and prettier kicks in to format everything - the markdown within those files and the code within markdown.

Why use VSCode?

I keep markdown and code typing similar - no brain-freeze. And, the formatting is a huge bonus as you see below.

What I type -

1
2
3
4
5
6
7


###   Header 3
 Hello World
```js
  if (true){
console.log("hello world")
}
  ```

What the content gets automatically formatted to -

1
2
3
4
5
6
7
8
9


### Header 3

Hello World

```js
if (true) {
  console.log("hello world");
}
```

You may see that -

### line has extra spaces removed
a blank line has been added between header and content
another blank line added between content and the beginning of code block
the js block has been changed to -
- format if statement as a code-block
- semicolons at logical end

If you have been typing in markdown, you would have recognized how valuable adding blank line can be. While it is easier for prettier, markdown does not “see” what you meant and format the entire block of content in an altogether different way.

Another crucial advantage for me - I can type in code-blocks within markdown and let it automatically format. I also get to know any silly mistakes (e.g. a bracket not closed) since Prettier parser will not format the code.

The Alternative

If VSCode is working so well with a couple of extensions, why change that? Two reasons -

I had been trying to make my workflow even more seamless
VSCode gobbles up a lot of memory. I want to minimise stuff I do on VSCode other than main-stream programming. Obviously all those windows are going to be open all the time, which is a big problem

I wanted to retain VSCode’s fantastic formatting support, and I can do that in just a couple of steps - thanks to Hugo.

Go to your Hugo site root directory
If your theme does not use any kind of packages today - do npm init. (in other words, ignore this step if you already have package.json in your Hugo site root directory)
Install husky, lint-staged, and prettier packages -
1

npm install husky lint-staged prettier

Change your package.json to-

1
2
3
4
5
6
7
8


{
  "scripts": {
    "precommit": "lint-staged"
  },
  "lint-staged": {
    "*.md": ["prettier --parser markdown --write", "git add"]
  }
}

We parse markdown file with lint-staged and use prettier to format files. husky enables us to prevent accidental commits before running pre-commit hook.

That’s it - now you can see your files nicely formatted no matter which editor you use.