Including reference-style links

[cjolowicz]

Hello 👋

I'm having some problems including portions with reference-style links from a README.md into Sphinx docs:

1. The links are not hyperlinked and are rendered with square brackets, e.g. [pytest]
2. The link definitions do not seem to be visible to the Sphinx docs that include them, causing errors when referenced elsewhere.

The README looks like this:

<!-- features-begin -->

- Testing with [pytest]
- Static type-checking with [mypy]

<!-- features-end -->

<!-- references-begin -->

[pytest]: https://docs.pytest.org/
[mypy]: http://mypy-lang.org/

<!-- references-end -->

Includes look like this:

.. include:: ../README.md
   :parser: myst_parser.sphinx_
   :start-after: <!-- features-begin -->
   :end-before: <!-- features-end -->

pytest_ uses assertions to verify expectations in tests.

bla bla typechecking__

__ mypy_

.. include:: ../README.md
   :parser: myst_parser.sphinx_
   :start-after: <!-- references-begin -->
   :end-before: <!-- references-end -->

Errors due to missing link definitions look like this:

path/to/repo/docs/guide.rst:4:Unknown target name: "pytest".

path/to/repo/docs/guide.rst:842:Indirect hyperlink target (id="id18") refers to target "mypy", which does not exist.

Is this expected behavior, and is there something I can do to get this to work?

By the way, I discovered the hard way that docutils' include directive does not process start-after markers in a line-based fashion, unlike Sphinx' literalinclude which removes the entire line where the marker is matched. It does not matter much in RST because the leading .. is ignored in the included text anyway. But if you have to wrap the markers in HTML comments, you need to have that bulky comment syntax inside the include directives too. (I already had a PR for myst-parser ready when I discovered that it just mirrors docutils behavior, and there's nothing to fix.)

[chrisjsewell]

Heya,
the way Markdown parsers work, you cannot parse separately the link references and the link definitions:
they make a first parse of the syntax "blocks", and gather the link definitions,
then make a second parse of the inline syntax within the blocks.
The inline syntax [abc] is only considered to be a link reference, if there is a matching link definition available, otherwise it is just parsed as text.

You can try this out here: https://markdown-it.github.io/

[cjolowicz]

Thanks, that makes sense.

Is there some other way I can avoid duplicating link definitions across documentation files?

[ZviBaratz]

I'm not sure if this is the best method, but it's possible to configure substitutions such as:

sphinx:
  config:
    myst_substitutions:
      website: "[website](https://www.website.com)"

and then in your markdown: {{website}}.
HTH 🙏