Implement #3212 (#3222)

CHANGES.txt

@@ -22,6 +22,8 @@ Bugfixes
 Features
 --------
 
+* Handle fragments in doc role (Issue #3212)
+* Slugify references in doc role.
 * Add Interlingua translation by Alberto Mardegan
 * Add Afrikaans translation by Friedel Wolff
 * Support for docutils.conf (Issue #3188)

docs/manual.rst

@@ -2716,6 +2716,13 @@ and it will produce:
 
     Take a look at :doc:`creating-a-theme` to know how to do it.
 
+The reference in angular brackets should be the `slug` for the target page. It supports a fragment, so
+things like ``<creating-a-theme#starting-from-somewhere>`` should work. You can also use the title, and
+Nikola will slugify it for you, so ``Creating a theme`` is also supported.
+
+Keep in mind that the important thing is the slug. No attempt is made to check if the fragment points to
+an existing location in the page, and references that don't match any page's slugs will cause warnings.
+
 Post List
 ~~~~~~~~~
 
@@ -2834,12 +2841,12 @@ with a ``True`` argument, eg. ``all=True``.
 
 .. sidebar:: Docutils Configuration
 
-   ReStructured Text is "compiled" by docutils, which supports a number of 
+   ReStructured Text is "compiled" by docutils, which supports a number of
    configuration options. It would be difficult to integrate them all into
    Nikola's configuration, so you can just put a ``docutils.conf`` next
    to your ``conf.py`` and any settings in its ``[nikola]`` section will be used.
 
-   More information in the `docutils configuration reference <http://docutils.sourceforge.net/docs/user/config.html>`__ 
+   More information in the `docutils configuration reference <http://docutils.sourceforge.net/docs/user/config.html>`__
 
 
 Importing your WordPress site into Nikola

nikola/plugins/compile/rest/doc.py

@@ -29,7 +29,7 @@
 from docutils import nodes
 from docutils.parsers.rst import roles
 
-from nikola.utils import split_explicit_title, LOGGER
+from nikola.utils import split_explicit_title, LOGGER, slugify
 from nikola.plugin_categories import RestExtension
 
 
@@ -51,6 +51,11 @@ def _doc_link(rawtext, text, options={}, content=[]):
     """Handle the doc role."""
     # split link's text and post's slug in role content
     has_explicit_title, title, slug = split_explicit_title(text)
+    if '#' in slug:
+        slug, fragment = slug.split('#', 1)
+    else:
+        fragment = None
+    slug = slugify(slug)
     # check if the slug given is part of our blog posts/pages
     twin_slugs = False
     post = None
@@ -72,6 +77,8 @@ def _doc_link(rawtext, text, options={}, content=[]):
         # use post's title as link's text
         title = post.title()
     permalink = post.permalink()
+    if fragment:
+        permalink += '#' + fragment
 
     return True, twin_slugs, title, permalink, slug