Markdown format for code tabs

Published: · Last updated:

Estimated Reading Time: 2 minutes

For a while I’ve been working on ui-pack which is intended to be a home for those UI components that aren’t used frequently enough to make it to most component libraries or are often implemented with very little research.

In setting up the documentation website, I wanted more control and power than I have ever had from using documentation tools I would reach out for in the past. This independence has affected my speed of release but, it has simultaneously helped me learn and get to do things how I imagine them.

One of such things is the tabbable code snippets as shown below:

tabbable code preview

With MDX offering full control of how my markdown is rendered, it offered me an opportunity to have markdown for what would have otherwise been a React component I have to use each time I am writing a doc that needs one of those.

Even though MDX allows for both markdown and JSX in the same file, I prefer to keep most of my documentation files written mostly in markdown.

To add a simple multi-line code to markdown now, you write it this way:

Note: Examples below use 2 backtics instead of 3 to avoid cofusing my markdown parser and myself.

``
some code
``

The code markdown takes argument unlike every other markdown syntax1. A lot of platforms will process syntax highlighting based on the language argument passed to your code like:

``js
var fruit = "apple"
console.log(`I ate ${fruit} this morning`)
``

It still feels like we may be limited to tabless code snippets with this format. So how do we get to what we have in the tabbed image above? We pass more arguments like:

``bash tabs='npm|yarn'
npm i @ui-pack/react
--
yarn add @ui-pack/react
``

With this format, the output can be formatted to easily look like what we have in the image.

Are there other markdown formats you process with interesting outputs? Share them with me.


  1. If you know any other syntax that takes argument, let me know in the comments. I want to be able to do more with blockquotes but I haven’t found a way to pass arguments to them. ↩︎