Markdown headings support

Support for markdown headings is listed as a goal in the README, but unsupported in https://github.com/microsoft/tsdoc/issues/169. In practice (using the tsdoc playground) it seems to be unsupported. In #169, it is also recommended to open a new issue for further discussion on this point if needed.

To start the discussion, I will share this example that currently works well with TypeDoc:

/**
 * Reverse an array in-place.
 *
 * @param array - The mutable array-like object of interest.
 *
 * @param start - The index of the first element in the range to be
 *   reversed, inclusive. The default value is `0`. Negative values
 *   are taken as an offset from the end of the array.
 *
 * @param stop - The index of the last element in the range to be
 *   reversed, inclusive. The default value is `-1`. Negative values
 *   are taken as an offset from the end of the array.
 *
 * #### Complexity
 * Linear.
 *
 * #### Undefined Behavior
 * A `start` or  `stop` index which is non-integral.
 *
 * #### Example
 * ```typescript
 * import { ArrayExt } from '@lumino/algorithm';
 *
 * let data = [0, 1, 2, 3, 4];
 * ArrayExt.reverse(data, 1, 3);  // [0, 3, 2, 1, 4]
 * ArrayExt.reverse(data, 3);     // [0, 3, 2, 4, 1]
 * ArrayExt.reverse(data);        // [1, 4, 2, 3, 0]
 * ```
 */

In this comment, the #### Example heading can and should be replaced with @example. It is not so clear what to do with the #### Complexity and #### Undefined Behavior headings. A logical first step is to put both in a @remarks section, but it is unclear if there is any way to subdivide the remarks section further (without falling back to HTML), other than to allow markdown headers.

Start with the README goal, reproduce the current behavior in the TSDoc playground, and read issue #169 for prior discussion. Compare the TypeDoc example, then define how markdown headings should interact with @example and @remarks sections; done means the supported behavior and subdivision rules are specified and demonstrated.