:ref: role does not generate a link

[zhouyaoji]

The :ref: role in conjunction with reST labels allows you to link to arbitrary locations in the document. The rest2html script used by GitHub just ignores the :ref: role.

In the example below, the sentence starting with :ref: should be rendered into a link to the label (_ref_link).

:ref:How do you create arbitrary links in reST? <ref_link>

.. _ref_link:
.. topic:: Making Arbitrary LInks in reST

To make arbitrary links in reST, you use the ``:ref:`` role with a label that is prefixed with an underscore....

I wrote documentation in reST for Mojito, a Node.js-based Web framework, but the FAQ does not render nicely because I use the :ref: role to link the questions to the answers.

See the following as a reference: https://github.com/yahoo/mojito/blob/develop/docs/dev_guide/faq/index.rst

[zhouyaoji]

The following from the Sphinx docs also explains how :ref: is supposed to work:
http://sphinx.pocoo.org/markup/inline.html#cross-referencing-arbitrary-locations

[mightyiam]

:ref: is Sphinx specific. Are Sphinx things supposed to work in GitHub Markup?

[bkeepers]

We don't currently support any extensions. You can see the current implementation here: https://github.com/github/markup/blob/master/lib/github/commands/rest2html