Present doc files with text inclusions sensibly in GitHub code browser

[gwhitney]

Currently, if you visit a documentation file (that has MkDocs inclusion syntax) in the GitHub code browser, the ordinary markdown parts look fine but the inclusion syntax produces unintelligible hieroglyphics (see the attached screenshot for an example). It would be better if in the GitHub code browser, the rendered markdown showed a link to the included content rather than this gibberish (I don't think there's any way to get GitHub to run MkDocs on the fly!).

[gwhitney]

The proposed way to implement this is as follows, using the file that produced the above screenshot as a running example:

1. Start from the current inclusion syntax:

{! ../package.json extract: {start: 'scripts', stop: '},', replace: [
    ['help:(.*\D)".*".*echo (.*)"', '### npm run \1\n\2'], # 1-liner help
    '"help:.*[-:]\d*".*echo \\?"?(.*?)\\?"?"', # a continuation line of help
    ['"help:(.*\D)":.*"', '### npm run \1\n'], # header of block of help lines
    '.' # ignore the actual scripts that don't start with help
]} !}

2. Enclose it in special markdown comment delimiters so that it will not show up in the GitHub rendering:

<!-- md-inclusion
{! ../package.json extract: {start: 'scripts', stop: '},', replace: [
    ['help:(.*\D)".*".*echo (.*)"', '### npm run \1\n\2'], # 1-liner help
    '"help:.*[-:]\d*".*echo \\?"?(.*?)\\?"?"', # a continuation line of help
    ['"help:(.*\D)":.*"', '### npm run \1\n'], # header of block of help lines
    '.' # ignore the actual scripts that don't start with help
]} !}
-->

3. Add a link to the extracted code before this, bracketed by special markdown comments:

<!-- for-github -->
You can see the available scripts in [package.json](https://github.com/numberscope/frontscope/blob/main/package.json#L8-L82).
<!-- end-github -->
<!-- md-inclusion
{! ../package.json extract: {start: 'scripts', stop: '},', replace: [
    ['help:(.*\D)".*".*echo (.*)"', '### npm run \1\n\2'], # 1-liner help
    '"help:.*[-:]\d*".*echo \\?"?(.*?)\\?"?"', # a continuation line of help
    ['"help:(.*\D)":.*"', '### npm run \1\n'], # header of block of help lines
    '.' # ignore the actual scripts that don't start with help
]} !}
md -->

4. Modify the filtering parameters in mkdocs.yml to remove anything between <!-- for-github --> and <!-- end-github --> comments, and to remove comment starters that match <!-- md-inclusion and comment closers that match md -->. (Details left to the reader, but mkdocs semiliterate is definitely powerful enough to do this, with the correct stop and start patterns, I think in the extract_standard_markdown parameter block.)