Pre-declared explicit links not working

[dylanh724]

Describe the bug

If I declare a .. _foo: path/to/foo at the top of my file, I can't reference it later

How to Reproduce

I tried:

1

===
Foo
===

.. _features: <path/to/features>

.. toctree::
   :maxdepth: 2

   Features <features>

2

===
Foo
===

.. _features: <path/to/features>

.. toctree::
   :maxdepth: 2

   Features <features_>

3

===
Foo
===

.. _features: <path/to/features>

.. toctree::
   :maxdepth: 2

   features

4

===
Foo
===

.. _features: <path/to/features>

.. toctree::
   :maxdepth: 2

   features_

5

===
Foo
===

.. _features: path/to/features

.. toctree::
   :maxdepth: 2

   features_

6

===
Foo
===

.. _features: path/to/features

.. toctree::
   :maxdepth: 2

   Features <features_>

...and a few more similar combos

Environment Information

Platform:              win32; (Windows-10-10.0.22631-SP0)
Python version:        3.10.11 (tags/v3.10.11:7d4cc5a, Apr  5 2023, 00:38:17) [MSC v.1929 64 bit (AMD64)])
Python implementation: CPython
Sphinx version:        7.3.7
Docutils version:      0.20.1
Jinja2 version:        3.1.4
Pygments version:      2.18.0

Sphinx extensions

[
  'myst_parser',
  'sphinx.ext.intersphinx',
  'sphinx_tabs.tabs'
]

Additional context

Pretty minimal examples above --

The docs list the syntax .. _foo linkblock but doesn't actually give examples beyond that or additional rules/nuances. It's very possible I misunderstood a simple concept, as I'm still somewhat newer to Sphinx/RST.

[picnixz]

• Can you tell me which docs you are referring to?
• Have a look at https://www.sphinx-doc.org/en/master/usage/referencing.html#role-ref
• Have a look at https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-references

If you want to have a "variable" so that you replace features by the path/to/features thing you created, it's something different you are trying to achieving. And I'm not sure you can use it in a toctree (in the doctree, you should put the correct path). If you want a "variable-like" thing, you can use the .. replace (see https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions).