Broken Markdown Links for Functions Containing Underscores

[niall-byrne]

First of all, thanks for making this, I'd like to use it for my project.

I've hit a snag however with functions containing underscores.

It seems when functions contain underscores in their title, the generated markdown strips the underscore out, leading to links that don't work in the wild.

I have an example here that's replicatable:

# @description Asserts that a variable is an array.
# @arg $1 string The name of the variable to check.
# @exitcode 0 If the assertion succeeded.
# @exitcode 1 If the assertion failed.
# @exitcode 127 If the wrong number of arguments were provided.
# @stderr The error message if the assertion fails.
stdlib_array_assert_is_array() { :; }

## Index

* [stdlib_array_assert_is_array](#stdlibarrayassertisarray)

### stdlib_array_assert_is_array

Asserts that a variable is an array.

#### Arguments

* **$1** (string): The name of the variable to check.

#### Exit codes

* **0**: If the assertion succeeded.
* **1**: If the assertion failed.
* **127**: If the wrong number of arguments were provided.

#### Output on stderr

* The error message if the assertion fails.

[niall-byrne]

On investigating it seems this commit introduced the problem.

As it was done deliberately I'm assuming it's for some version of markdown that's NOT github ?
Someone else has even created a PR for this.

It's a shame because this is a great little project, hopefully someone can chime in here to explain the proper behaviour.

A fix for me is to simply revert the commit I referenced above, but... I can't help wondering if there isn't a better way...

If someone is deliberately commiting code that breaks it, and someone is commiting code that fixes it, maybe there's a behaviour fork here that needs to be behind an if statement ?