From 9eb259af82567a568b0c5a57e97859d04c1a8ec8 Mon Sep 17 00:00:00 2001 From: David Zaslavsky Date: Wed, 15 Apr 2020 01:35:04 -0700 Subject: Wrong path for attached static content urls (#2158) * Document _URL/_SAVE_AS path matching req. Fix #2158 This commit addresses the fact that some URLs (primarily {attach}) are based on the *_SAVE_AS path instead of the *_URL path. It updates the documentation to point out that the paths of corresponding _URL and _SAVE_AS settings should match, and that the OUTPUT directory should correspond to the web server's document root, in order to avoid producing these incorrect URLs. * Clarify {attach} and *_URL / *_SAVE_AS caveat Co-authored-by: Justin Mayer --- docs/content.rst | 4 ++++ docs/settings.rst | 10 +++++++++- 2 files changed, 13 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/content.rst b/docs/content.rst index a52425a4..6affecce 100644 --- a/docs/content.rst +++ b/docs/content.rst @@ -370,6 +370,10 @@ of ``{attach}``, and letting the file's location be determined by the project's ``STATIC_SAVE_AS`` and ``STATIC_URL`` settings. (Per-file ``save_as`` and ``url`` overrides can still be set in ``EXTRA_PATH_METADATA``.) +.. note:: + When using ``{attach}``, any parent directory in ``*_URL`` / ``*_SAVE_AS`` + settings should match each other. See also: :ref:`url-settings` + Linking to authors, categories, index and tags ---------------------------------------------- diff --git a/docs/settings.rst b/docs/settings.rst index befb6f05..bb673ec0 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -168,7 +168,8 @@ Basic settings .. data:: OUTPUT_PATH = 'output/' - Where to output the generated files. + Where to output the generated files. This should correspond to your web + server's virtual host root directory. .. data:: PATH @@ -358,6 +359,7 @@ Basic settings The IP to which to bind the HTTP server. +.. _url-settings: URL settings ============ @@ -378,6 +380,12 @@ variables allow you to place your articles in a location such as example below). These settings give you the flexibility to place your articles and pages anywhere you want. +.. note:: + If a ``*_SAVE_AS`` setting contains a parent directory that doesn't match + the parent directory inside the corresponding ``*_URL`` setting, this may + cause Pelican to generate unexpected URLs in a few cases, such as when + using the ``{attach}`` syntax. + If you don't want that flexibility and instead prefer that your generated output paths mirror your source content's filesystem path hierarchy, try the following settings:: -- cgit v1.2.1