Anchors do not work like in Sphinx

[linawolf]

I found two functional tests for anchors that don't really work like anchors in sphinx do:

https://github.com/doctrine/rst-parser/blob/0.5.x/tests/Functional/tests/render/anchor/anchor.rst

Anchors
-------

.. _lists:

`go to lists <#lists>`_

This does not appear to be Sphinx syntax. Custom anchors are usually used to give unique anchor names to headlines: https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html#use-a-custom-anchor

They are then used in :ref: links. Anchors which are not attached to headlines do not work usually.

The syntax with the underscore is used for external links. it can be used like this but not for anchors:

`CNN <http://cnn.com>`_

anchors are more used like this:

.. _RST Overview:

Overview
**********

RST Overview content

.. _Sphinx Overview:

Overview
*********

Sphinx Overview content

Somewhere else
=============

This is a link to the RST Overview: :ref:`RST Overview`

This is a link to the Sphinx Overview: :ref:`Sphinx Overview`

[wouterj]

The #... syntax used in the example you mentioned indeed isn't reStructuredText. I guess it's a legacy thing from an older version of this library (and it doesn't hurt "valid" reStructuredText, so I never bothered to remove it).

I don't think explicit hyperlink targets are only allowed in front of titles/sections (although that is a common use-case of explicit hyperlink targets). The reStructuredText markup specification shows examples of them being used throughout a document, to provide an anchor to reference to:

Internal hyperlink targets have empty link blocks. They provide an end point allowing a hyperlink to connect one place to another within a document. An internal hyperlink target points to the element following the target. [15] For example:

Clicking on this internal hyperlink will take us to the target_
below.

.. _target:

The hyperlink target above points to this paragraph.

[linawolf]

Ok these cannot be used as resolved references however. you can link to them via target_ but not via :ref: as they have not title. Also not sure if that would work beyond the page you are currently on