m.htmlsanity: clarify the use of expand_links a bit.

I wanted to remove it at first, but then realized a more proper solution
would be to not require the user to add random fields to
FORMATTED_FIELDS. In the ideal case the template *could* do just

    {{ field|render_rst|expand_links(article }}

but at the moment Pelican strips all reST formatting from the
non-formatted fields, which kinda prevents this. So keeping the filter
for later when we have this fixed.

diff --git a/doc/plugins/htmlsanity.rst b/doc/plugins/htmlsanity.rst
index 98ee485ce1fb8b4b3b964f53fd018d936c5042ea..8b8cae63d68d6a5fe10530d95a151a330b6c933e 100644 (file)
--- a/doc/plugins/htmlsanity.rst
+++ b/doc/plugins/htmlsanity.rst
@@ -263,14 +263,15 @@ The filter is fully equivalent to the builtin reST rendering and the above
 `Internal link expansion`_
 --------------------------
 
-By default, link expansion works only in document content and article
-summaries. In order to expand links in additional fields and arbitrary strings,
-this plugin provides two Jinja2 filters, producing results equivalent to
+By default, link expansion works only in document content and fields that are
+referenced in the :py:`FORMATTED_FIELDS` (such as article summaries). In order
+to expand links in additional fields and arbitrary strings, this plugin
+provides two Jinja2 filters, producing results equivalent to
 `links expanded by Pelican <http://docs.getpelican.com/en/stable/content.html#linking-to-internal-content>`_.
 
-For fields that are referenced in the :py:`FORMATTED_FIELDS` setting, one can
-use the ``expand_links`` Jinja2 filter in the template. The link expansion
-needs the content object (either ``article`` or ``page``) as a parameter.
+For formatted fields, one can use the ``expand_links`` Jinja2 filter in the
+template. The link expansion needs the content object (either ``article`` or
+``page``) as a parameter.
 
 .. code:: jinja
 

diff --git a/pelican-plugins/m/htmlsanity.py b/pelican-plugins/m/htmlsanity.py
index 703ff3424d8dcef5b56e58a1abe886b7c2e089ae..8bb38f15368c206cd04ee171e8344aacbce71ce4 100644 (file)
--- a/pelican-plugins/m/htmlsanity.py
+++ b/pelican-plugins/m/htmlsanity.py
@@ -648,6 +648,10 @@ def expand_link(link, content):
         link)
 
 def expand_links(text, content):
+    # TODO: fields that are in FORMATTED_FIELDS are already expanded, but that
+    # requires extra work on user side. Ideal would be to handle that all on
+    # template side, so keeping this one for the time when we can replace
+    # FORMATTED_FIELDS with render_rst as well.
     return content._update_content(text, content.get_siteurl())
 
 # To be consistent with both what Pelican does now with '/'.join(SITEURL, url)