Markdown Hacks For Technical Writers

Table of contents

• Introduction
• Centering text
• Opening links in a new tab
• Resizing images
• Colored text
• Creating tables the easy way
• Vertical spacing
• Horizontal spacing
• Collapse extra blocks of text
• Quick edit
• Conclusion

Introduction

The beauty of markdown lies in its simple yet powerful syntax. This simplicity comes at a cost though. It lacks some useful formatting features.

Most of these shortcomings can be easily fixed with HTML, that is because markdown is considered a subset of HTML. This means we can write pure HTML in a markdown file and it will be considered valid syntax.

In this post, we will look at leveraging HTML to introduce useful formatting features to our markdown documents.

⚠️NB: Some markdown engines might not support the use of HTML, in which case some of the hacks below might not work as expected.

Centering text

By default markdown content align itself to the left. Unless your markdown renderer or engine comes with a custom syntax for centering any block of text, there is no definition of how to center text in the markdown specification [↗].

We can however achieve this using CSS:

✅ Wrap📋
01:  <p style="text-align:center">some text</p>

This produces:

some text

There is also the HTML center tag we could use, however, this is deprecated and likely not going to work in future browsers.

Here is an example using the center tag:

✅ Wrap📋
01: <center><p>some text</p></center>

Opening links in a new tab

There is a syntax for creating hyperlinks in markdown ie [link text](#url), however, there is no definition in the specification on how to create links that open up in a different browser tab. We can again look to HTML to achieve this.

✅ Wrap📋
01: <a href="https://eddymens.com" target="_blank">Eddymens.com</a>

With the above we get a typical hyperlink that opens up in a new tab:

Eddymens.com

The target="_blank" attribute is responsible for making the link open up in a new tab.

Resizing images

Most markdown engines do not apply any form of sizing when rendering an image, this is good as it allows the writer to resize images to their desired size before referencing them in their markdown document.

Sometimes though it's just easier to adjust the size within the markdown document. For example, we can set a percentage size so that the image resizes depending on the reader's screen size.

✅ Wrap📋
01: <img src="image.png" width="100%" height="100%">

The image below uses the img tag to resize a rather large image into a smaller size. Here is the full-sized image

⚠️NB: It's actually a good idea to resize an image before attaching it to your document as this reduces the overall byte size as well.

Colored text

Sometimes you just want to add colored text to your markdown document, whether it's to emphasize something or to break away from the black and white monotony.

For this, we can sprinkle a bit of CSS.

✅ Wrap📋
01: <p style="color:red"> Red text</p>

With the above we get:

Red text

Creating tables the easy way

The syntax for creating tables in markdown is a messy one. Using an online markdown table generator can make it a lot more pleasant. Here [↗] is one I use

Vertical spacing

If you ever try to add a lot of vertical spacing between two paragraphs by hitting the enter key more than once, you know that will not lead to more spacing. You can use the HTML
tag to create the extra spacing you need.

✅ Wrap📋
01: some text here
02: <br>
03: <br>
04: Second block

Horizontal spacing

Similar to creating vertical spaces, hitting the tab or space key several times won't lead to the text being further apart. To do this we can use  

✅ Wrap📋
01: John      Doe

Collapse extra blocks of text

Sometimes readers do not need to see everything at once as this can be overwhelming. You can tack away extra information using the details tag. This way the user can expand if they are interested in the extra content.

✅ Wrap📋
01: <details>
02:   <summary>Click to read more</summary>
03:     <ul>
04:     <li>line one</li>
05:     <li>line two</li>
06:     <li>line three</li>
07:     </ul>
08: </details>

Output:

⚠️NB: Some markdown engines will not allow the use of markdown in the details block so you will have to write everything out as HTML hence the use of li in the above example.

Quick edit

If you happen to have your markdown files on GitHub [↗] then you can edit your markdown on a web-based editor it provides.

Once you are within the repository you can hit the . key to load up the markdown files in the editor and off you go!

Conclusion

As you can see the shortcomings of markdown can be mitigated using plain old HTML. As a technical writer, it's well worth the time to learn basic HTML as it might come in handy from time to time.

Here is another article you might like 😊 Markdown table of contents (TOC): how to create one