Using YAML to Write Docs Indentation in VSCode


VSCode has this great feature where you can configure the language of a document in the YAML front matter. It’s kinda like a printer, only it can’t print, but it can change background colors and stuff.

For example, I could write an entire blog post in YAML and tell VSCode this is YAML and it would respect that. Or I could do something like this:

title: Using YAML to Write Docs Indentation in VSCode

description: a blog around the use of correct indentation when writing documention in markdown.

tags:

Indentation in VSCode: a blog around the use of correct indentation when writing documention in markdown.

Using YAML to Write Docs

A new feature of Visual Studio Code allows developers to add YAML front matter to files and then render it in the editor through a variety of custom views. This is part of how the documentation authoring pack is able to do things like render tables of contents, breadcrumbs, and custom views.

The above image shows how you can right-click on a file in the explorer and choose Show Preview to see an example of what this looks like. What follows is a brief look at how you can customize the view that is rendered.

Indentation in VSCode: a blog around the use of correct indentation when writing documention in markdown.

Inspiration for this blog comes from a recent experience I had with my own documentation. I had been writing documentation that was full of code blocks and at some point, I had to make certain changes to my documentation that required me to add more lines of code.

I noticed that the code blocks were now taking up a lot of space and the lines started wrapping onto the next line. I fixed this by indenting the contents of the code block, which made the end result look pretty good. However, I noticed that when I would export this to PDF, the indentation was not there anymore. What happened?

After a bit of research, it turns out that Github Flavored Markdown (GFM) doesn’t support indentation so this didn’t work as expected. Although it may seem like it is supported since you get the desired output when you view your markdown file on VSCode but it turns out that is just VSCode being helpful by interpreting GFM without getting into the details of how GFM works.

So what is one supposed to do if they want their markdown files to have

The other day I was writing some documentation for a project in Microsoft Visual Studio Code. I was using the built-in Markdown Preview to see how my documentation looked. This is really handy as it shows the rendered Markdown as you are writing it.

However, I noticed that my preview didn’t seem to look correct, and after a little while, I realised why: my indentation was incorrect.

Markdown requires correct indentation when writing lists and code blocks, but also when writing YAML front matter. It seems that if you do not indent correctly, VSCode will render your markdown incorrectly.

So, let’s create a new file in VScode and call it “vscode-markdown.md”.

This article is about using VSCode to write documentation. It shows how to use YAML with markdown to create a good looking documenation experience.

The article is pretty long, and includes some code examples. Code examples are good for this kind of thing, because they show what you should do.

Markdown is a lightweight markup language with plain text formatting syntax. It is designed so that it can be converted to HTML and many other formats using a tool by the same name. Markdown is often used to format readme files, for writing messages in online discussion forums, and to create rich text using a plain text editor.

Markdown provides formatting options for unordered lists (bullet points), ordered lists (numbered), bold and italic text, headers, line breaks, links and quotes.


Leave a Reply

Your email address will not be published. Required fields are marked *