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::