From: Vladimír Vondruš <mosra@centrum.cz>
Date: Thu, 2 Nov 2017 19:42:43 +0000 (+0100)
Subject: doc: document the format_siteurl Jinja2 filter better.
X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=8261feb5654a940038e4ffce31409bfe43490360;p=blog.git

doc: document the format_siteurl Jinja2 filter better.
---

diff --git a/doc/plugins/htmlsanity.rst b/doc/plugins/htmlsanity.rst
index dde2f61d..3353a60e 100644
--- a/doc/plugins/htmlsanity.rst
+++ b/doc/plugins/htmlsanity.rst
@@ -286,8 +286,14 @@ making use of both fields could look like this:
 ---------------------
 
 Convenience filter replacing the common expression :jinja:`{{ SITEURL }}/{{ page.url }}`
-with a formatter that makes use of `urljoin <https://docs.python.org/3/library/urllib.parse.html#urllib.parse.urljoin>`_ so it does the right thing also when
-dealing with absolute URLs and even when they start with just ``//``:
+with a formatter that makes use of `urljoin <https://docs.python.org/3/library/urllib.parse.html#urllib.parse.urljoin>`_
+so it does the right thing also when dealing with absolute URLs and even when
+they start with just ``//``.
+
+For example, if :py:`SITEURL` is :py:`'http://your.site'` and you apply
+``format_siteurl`` to :py:`'about/'`, then you get ``http://your.site/about/``;
+but if you apply it to :py:`'https://github.com/mosra/m.css'`, then you get
+just ``https://github.com/mosra/m.css``.
 
 .. code:: jinja