Markdown headers intermittently not working

• The problem
• How you can fix this
• How you can stop this happening again
  • System Preferences (macOS Only)
  • VS Code
  • iTerm (macOS Only)
  • Why I’m writing this

The problem

I ran into this problem where markdown headers were only rendering properly intermittently. The problem looked like this:

Here’s the README of a project I’ve been working on before I fixed the problem:

And here it is after I fixed the problem:

As you can see, it’s like the markdown renderer isn’t recognising the former as a header and is showing the # character instead, whereas it all gets parsed correctly in the latter. It gets even more confusing when you look at the difference in source code. Here they are, one after another:

# `3d-noughts-and-crosses`
(broken)
https://raw.githubusercontent.com/ollybritton/3d-noughts-and-crosses/d502868fdb46817c815873d364dc76729c737bd4/README.md

# `3d-noughts-and-crosses`
(working)
https://raw.githubusercontent.com/ollybritton/3d-noughts-and-crosses/master/README.md

You might be able to see the difference in the syntax highlighting – the first header is grayed out, whereas the second is in color.

The issue turned out to be a non-breaking space, which is present in the first code block but not the second. Depending on how your keyboard is set up, and what operating system you are using (I had recently switched to using macOS), some keyboards will insert a non-breaking space if you type Alt-Space/Option-Space instead of a normal Space. If you’re writing hashtags with a combination like Alt-3/Option-3 and typing quickly, you may accidentally type this character instead of a normal space.

As the name suggests, a non-breaking space stops the software or browser you’re using from inserting a page break in that space. The problem is that a lot of markdown parsers don’t allow this character to act as a separator between the # and the actual title, so it treats it just like it does for normal text in any paragraph.

How you can fix this

Since this happens when you’ve accidentally entered the wrong character, you can just type out the heading again but make sure to not press Alt-Space/Option-Space. Alternatively, you could do a find/replace for all non-breaking spaces with normal spaces. If you’re not sure how you typed the character, you can use this website to copy and paste it.

How you can stop this happening again

It can be super annoying to make a commit, load up the README on GitHub and then have to make another commit to sort out the headings. If you want to stop this happening, you can add custom settings to the editors you use to treat Alt-Space/Option-Space as a different shortcut that inserts a normal space.

System Preferences (macOS Only)

If you’re on a mac, you can use this hack to override the keyboard shortcut for all applications.

First, open System Preferences and go to the Keyboard section:

Then select an unused shortcut, like Show Notification Centre in this case:

Toggle it on and then type in Alt-Space/Option-Space. Then toggle it off.

This should stop a non-breaking space being inserted in any application.

Courtesy of this Superuser answer.

VS Code

If you’re using VS Code, you can add a custom key binding by opening up the Command Palette (normally Shift+Ctrl+P or Shift+Cmd+P but can be accessed from the View menu at the top of the screen) and typing

>Preferences: Open Keyboard Shortcuts (JSON)

and selecting the option that doesn’t say “Defaults”. It should look something like this:

Then you can insert the following key binding:

{
        "key": "alt+space",
        "command": "type",
        "when": "editorTextFocus",
        "args": { "text": " " }
}

Here’s what the file should end up looking similar to:

(This photo shows another key binding I have set up, but this isn’t necessary to add yourself).

Courtesy of user2361830 on Superuser.

iTerm (macOS Only)

If you’re using iTerm (e.g. you’re running Vim or Emacs in the terminal on a Mac), you can set up a custom keyboard shortcut there too. To do so, open the preferences by going iTerm2 $\to$ Preferences or pressing Cmd+,.

Then select Keys and press the + in the lower left corner:

From there, type Alt+Space/Option+Space into the Keyboard Shortcut input, select Send Text from the Action dropdown and then type a normal space in the input box that appears.

Courtesy of Simon Walker on Superuser.

Why I’m writing this

This is an annoying problem to diagnose. Because of it only happening sometimes when you’re typing quickly, it’s hard to reproduce. I must’ve searched about a gazillion things before figuring out what the issue was:

markdown headers not working

markdown headers not working mac

markdown not rendering properly ** github readme not rendering headers

github mac headers not working properly

I only found any help on how to stop it happening after I worked out what it was, which was this Superuser question: How to disable the Option-Space key combination for non-breaking spaces?.