# Markdown headers intermittently not working

> Source: https://ollybritton.com/blog/markdown-headers-not-working-properly/ · Updated: 2022-02-12 · Tags: blog, safe-to-post-online

* [The problem](#the-problem)
* [How you can fix this](#how-you-can-fix-this)
* [How you can stop this happening again](#how-you-can-stop-this-happening-again)
	* [System Preferences (macOS Only)](#system-preferences-macos-only)
	* [VS Code](#vs-code)
	* [iTerm (macOS Only)](#iterm-macos-only)
	* [Why I'm writing this](#why-im-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:

![broken readme](broken-readme.png)

And here it is after I fixed the problem:

![working readme](working-readme.png)

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](https://www.compart.com/en/unicode/U+00A0) 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:

![mac keyboard](mac-keyboard.png)

Then select an unused shortcut, like _Show Notification Centre_ in this case:

![mac shortcut to change](mac-shortcut-to-change.png)

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

![mac shortcut changed](mac-shortcut-changed.png)

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

[Courtesy of this Superuser answer](https://superuser.com/a/1058566).

### 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:

![command palette](command-palette.png)

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:

![keybindings vscode](keybindings-vscode.png)

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

[Courtesy of `user2361830` on Superuser](https://superuser.com/a/1299775).

### 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+,`.

![iterm settings](iterm-settings.png)

Then select __Keys__ and press the `+` in the lower left corner:

![iterm settings where](iterm-settings-where.png)

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.

![iterm input](iterm-input.png)

[Courtesy of Simon Walker on Superuser](https://superuser.com/questions/78245/how-to-disable-the-option-space-key-combination-for-non-breaking-spaces).

### 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?](https://superuser.com/questions/78245/how-to-disable-the-option-space-key-combination-for-non-breaking-spaces).

---
Olly Britton — https://ollybritton.com. Machine-readable index: https://ollybritton.com/llms.txt