I am working on a project in reStructuredText which contains some internal links.

So, for example, this snippet:

.. |page-break| raw:: html

   <div style="page-break-after: always"></div>

`(cf. chap. “The mobile application”) <#the-mobile-application>`__

|page-break|

The mobile application
----------------------

will generate the following HTML:

<p><a class="reference external" href="#the-mobile-application">(cf. chap. “The mobile application”)</a></p>
<p><div style="page-break-after: always"></div></p>
<div class="section" id="the-mobile-application">
    <h1>The mobile application</h1>
</div>

We can see that Docutils has automatically generated a div with an id ("the-mobile-application") and the internal link in this example works well.

Now the problem comes after translation in another language, because Docutils will generate a new id, the link has to be modified also. So the idea is to use a custom id that will be the same for all languages. reStructuredText has a mechanism called “Cross-referencing arbitrary locations” for this purpose.

Unfortunately, the structure of the HTML is different. With this method, Docutils generates an empty span with the custom id.

.. |page-break| raw:: html

   <div style="page-break-after: always"></div>

`(cf. chap. “The mobile application”) <#my-custom-id>`__

|page-break|

.. _my-custom-id:

The mobile application
----------------------

<p><a class="reference external" href="#my-custom-id">(cf. chap. “The mobile application”)</a></p>
<p><div style="page-break-after: always"></div></p>
<div class="section" id="the-mobile-application">
<span id="my-custom-id"></span>
<h1>The mobile application</h1>
</div>

And Prince does not create a link because the span element is empty. Note that the problem does not occur with browsers.

Links to empty spans may not work in Prince at the moment. One solution would be to use a little JavaScript to move the id to the following h1 element instead.