loading...

These lifehacks will change the way you write Markdown!

yechielk profile image Yechiel Kalmenson ・3 min read

If you're a developer, chances are you've come across markdown editors before (whether you know it or not).

Markdown is supported by GitHub, DEV, many ticket trackers, most documentation and blogging platforms (cough.. cough... Medium...). Getting good with the markdown syntax will help you communicate more effectively as a developer.

There are lots of resources and cheat-sheets for getting started with the basics (like this great gist). In this post I will share a few tips that I haven't seen too many people use or that aren't so well documented.

Ordered Lists

The syntax for ordered lists is pretty simple:

1. Item one
2. Item two
3. another item
Enter fullscreen mode Exit fullscreen mode

renders as:

  1. Item one
  2. Item two
  3. another item

But have you ever written a long list and then realized you missed an item in the middle? Must have been really annoying to go back and insert it and then fix the numbers on all subsequent items...

Except, you don't have to! Markdown doesn't pay attention to the numbers, as long as you have a list of items with numbers in front of them, any numbers, it will render as an ordered list.

The following:

1. Item one
2. Item two
3. another item

1. Item one
1. Item two
1. another item

4. Item one
6. Item two
765. another item
Enter fullscreen mode Exit fullscreen mode

All render as:

  1. Item one
  2. Item two
  3. another item

My preferred style is to just use 1s in front of all of them, but if you prefer to have the actual numbers and find yourself needing to insert a new item say between item 7 and 8 you can just give the new item the number 7 as well and when the markdown gets rendered it will render properly with all of the numbers in order.

Syntax Highlighting

In the following section I've embedded snippets from gist, that is because there's a bug in the dev.to editor that doesn't allow escaping backticks properly.

I've opened an issue on it in the dev.to repo. If any of the readers would like to take a crack at it feel free!

Most people know that wrapping code snippets with three backticks like this:

Will render it as a code snippet like this:

someCodeGoes("here")
Enter fullscreen mode Exit fullscreen mode

You might also know that adding the name of the language your code is in like this:

Will give you syntax highlighting like this:

someCodeGoes("here")
Enter fullscreen mode Exit fullscreen mode

But did you know that you can also put diff as a language, and when you do it will render any line that starts with a - in red and any line that starts with a + in green.

So this:

Will render like this:

    someCodeGoes(here) {
-     oldCode()
+     newCode()
      someMore(code)
    }
Enter fullscreen mode Exit fullscreen mode

I found this particularly useful when writing tutorials and there are steps with only small code changes. It can sometimes be hard for readers to realize what changed, using diffs to highlight the difference can make it a lot easier!

Escaping Backticks; The Lifehack That Wasn't

The next lifehack involves how to escape backticks and other reserved characters in Markdown, but due to the bug mentioned in the beginning of the last section I'll have to leave that for another time :(

If you would like to see how it's done, check out the gist I embedded above and click on the "Raw" button to see how I did it.

I hope you found these useful!

Now get to writing that documentation you've been putting off!

Discussion

pic
Editor guide
Collapse
antjanus profile image
Antonin Januska

I had no idea about the diff highlight! Can you combine it with a JS syntax highlight?

Im definitely using this in my next tutorials btw. Thanks a bunch for the article!

Collapse
yechielk profile image
Yechiel Kalmenson Author

As far as I know you can't have two languages selected so if you have diff there's no way to add another language.

That's why I only use diff when it's a change of a few characters, if the change is more than a line I'll use they language for the syntax highlighting.

Collapse
jmfayard profile image
Jean-Michel Fayard πŸ‡«πŸ‡·πŸ‡©πŸ‡ͺπŸ‡¬πŸ‡§πŸ‡ͺπŸ‡ΈπŸ‡¨πŸ‡΄

My best markdown lifehack is to ditch it in favor of asciidoc as soon as you are doing something non trivial.

Simple things should be easy, complex things should be possible said a wise man. Markdown got only the first part right. Asciidoc is as easy as markdown for the simple things but won't let you down if you do something more complex

asciidoctor.org/docs/user-manual/#...

Collapse
ppetermann profile image
ppetermann

If I really need more complex I might just use good ol' latex

Collapse
jmfayard profile image
Thread Thread
ppetermann profile image
ppetermann

Which really is the only time where I need something more complex than markdown.

Thread Thread
jmfayard profile image
Jean-Michel Fayard πŸ‡«πŸ‡·πŸ‡©πŸ‡ͺπŸ‡¬πŸ‡§πŸ‡ͺπŸ‡ΈπŸ‡¨πŸ‡΄

That's what I thought also, but in fact markdown is never enough if you look at it closely :

  • on GitHub I'm using "markdown plus" some GitHub extensions
  • on dev.to, I'm using "markdown plus" some handy native liquid tags
  • with a static site generator, I'm using "markdown plus" a static front matter thingy

The question then is whether to use multiple incompatible "markdown plus extension" or a standardized better format like asciidoc.

Collapse
daltonbr profile image
Dalton Lima

Love Markdown and this article.
Nice job!

There is a small error, in the Javascript and Diff examples, they are mixed.

To beginners I'll suggest to install a preview extension into VSCode and maybe another extension to handle Markdown shortcuts.

Collapse
yechielk profile image
Yechiel Kalmenson Author

Thank you!

What do you mean that they are mixed? It seems right to me... πŸ€”

Collapse
daltonbr profile image
Dalton Lima

Nevermind, it must be something regarding the renderer on the DEV Android app, or it was me that was just tired after a long week! πŸ˜…

Collapse
ceeoreo profile image
Ceora Ford

Everyone who is new to publishing on here should read this.

Collapse
yechielk profile image
Yechiel Kalmenson Author

Thank you! ❀️

Collapse
andyatkinson profile image
Andy Atkinson

Nice list! I also like to use angle brackets <> around links with no text, quotations with >, and footnotes via the Extended Syntax (supported by GitHub Pages for example). markdownguide.org/extended-syntax/

Collapse
burdettelamar profile image
Burdette Lamar

Javascript and diff, of course. But many, many more. Check out the complete list on Github.

Collapse
yechielk profile image
Yechiel Kalmenson Author

Yes! I didn't mean to imply JavaScript was the only one, I brought it as an example. Most people I've spoken to didn't know about diff though, so that was the main one I wanted to point out.

Collapse
ajonp profile image
Alex Patterson

This is awesome I πŸ’― of the time use 1. Only for allmy lists.

Collapse
yechielk profile image
Collapse
e5pe profile image
Esperanza Cutillas Rastoll

This article is great! I didn't know some of those things!

Collapse
yechielk profile image
Yechiel Kalmenson Author

Glad you found it helpful!

Collapse
ppetermann profile image
ppetermann

Didn't know about diff.
Will deffo use diff

Thank you!

Collapse
mp3 profile image
m-p-3

Just tried it in Joplin (OneNote-like app using Markdown syntax) and it works wonderfully, thanks for the tip!

Collapse
yechielk profile image
Yechiel Kalmenson Author

Glad you found it helpful!

Collapse
vicky209 profile image
vicky209

Wonderful article! I'm using a project management software and they allow us to write Markdown as well. I will definitely use your advice!

Collapse
yechielk profile image
Yechiel Kalmenson Author

Glad you found it helpful! πŸ€—

Collapse
bertheyman profile image
Bert Heyman

Really useful tips!

Collapse
yechielk profile image
Yechiel Kalmenson Author

Glad you found it helpful! πŸ€—

Collapse
chrisachard profile image
Chris Achard

diff looks awesome! I never knew that would work like it does :) nice - thanks!