From 0f39dbdf00ccb7e6fc7b214373037c716d29b900 Mon Sep 17 00:00:00 2001 From: David Zaslavsky Date: Wed, 7 Jun 2017 15:11:58 -0400 Subject: [PATCH] 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. --- docs/content.rst | 5 +++++ docs/settings.rst | 13 ++++++++++--- 2 files changed, 15 insertions(+), 3 deletions(-) diff --git a/docs/content.rst b/docs/content.rst index 507593bf..3ac3aa03 100644 --- a/docs/content.rst +++ b/docs/content.rst @@ -331,6 +331,11 @@ 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:: + Using ``{attach}`` relies on the ``*_URL`` and ``*_SAVE_AS`` settings for + the document type (e.g. ``ARTICLE_URL`` and ``ARTICLE_SAVE_AS``) having the + same directory portion. See also :ref:`url-settings`. + Linking to authors, categories, index and tags ---------------------------------------------- diff --git a/docs/settings.rst b/docs/settings.rst index 4d09ec4c..37c45dd7 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -152,7 +152,8 @@ Basic settings .. data:: OUTPUT_PATH = 'output/' - Where to output the generated files. + Where to output the generated files. This should correspond to the document + root of the web server. .. data:: PATH @@ -312,6 +313,7 @@ Basic settings A list of metadata fields containing reST/Markdown content to be parsed and translated to HTML. +.. _url-settings: URL settings ============ @@ -329,8 +331,13 @@ You can customize the URLs and locations where files will be saved. The ``*_URL`` and ``*_SAVE_AS`` variables use Python's format strings. These variables allow you to place your articles in a location such as ``{slug}/index.html`` and link to them as ``{slug}`` for clean URLs (see -example below). These settings give you the flexibility to place your articles -and pages anywhere you want. +example below). + +.. note:: + If the parent directory of a ``*_SAVE_AS`` setting doesn't match the + directory portion of the corresponding ``*_URL`` setting, this may cause + Pelican to generate incorrect URLs in a few cases, such as when using + ``{attach}``. .. note:: If you specify a ``datetime`` directive, it will be substituted using the