Document path metadata extraction

docs/getting_started.rst

@@ -213,6 +213,8 @@ The idea behind "pages" is that they are usually not temporal in nature and are
 used for content that does not change very often (e.g., "About" or "Contact"
 pages).
 
+.. _internal_metadata:
+
 File metadata
 -------------
 

docs/settings.rst

@@ -62,9 +62,12 @@ Setting name (default value)                                            What doe
                                                                         For example, if you would like to extract both the
                                                                         date and the slug, you could set something like:
                                                                         ``'(?P<date>\d{4}-\d{2}-\d{2})_(?P<slug>.*)'``.
+                                                                        See :ref:`path_metadata`.
 `PATH_METADATA` (``''``)                                                Like ``FILENAME_METADATA``, but parsed from a page's
                                                                         full path relative to the content source directory.
+                                                                        See :ref:`path_metadata`.
 `EXTRA_PATH_METADATA` (``{}``)                                          Extra metadata dictionaries keyed by relative path.
+                                                                        See :ref:`path_metadata`.
 `DELETE_OUTPUT_DIRECTORY` (``False``)                                   Delete the output directory, and **all** of its contents, before
                                                                         generating new files. This can be useful in preventing older,
                                                                         unnecessary files from persisting in your output. However, **this is
@@ -335,6 +338,52 @@ your resume, and a contact page — you could have::
                       'src/resume.html': 'dest/resume.html',
                       'src/contact.html': 'dest/contact.html'}
 
+
+.. _path_metadata:
+
+Path metadata
+=============
+
+Not all metadata needs to be `embedded in source file itself`__.  For
+example, blog posts are often named following a ``YYYY-MM-DD-SLUG.rst``
+pattern, or nested into ``YYYY/MM/DD-SLUG`` directories.  To extract
+metadata from the filename or path, set ``FILENAME_METADATA`` or
+``PATH_METADATA`` to regular expressions that use Python's `group name
+notation`_ ``(?P<name>…)``.  If you want to attach additional metadata
+but don't want to encode it in the path, you can set
+``EXTRA_PATH_METADATA``:
+
+.. parsed-literal::
+
+    EXTRA_PATH_METADATA = {
+        'relative/path/to/file-1': {
+            'key-1a': 'value-1a',
+            'key-1b': 'value-1b',
+            },
+        'relative/path/to/file-2': {
+            'key-2': 'value-2',
+            },
+        }
+
+This can be a convenient way to shift the installed location of a
+particular file:
+
+.. parsed-literal::
+
+    # Take advantage of the following defaults
+    # STATIC_SAVE_AS = '{path}'
+    # STATIC_URL = '{path}'
+    STATIC_PATHS = [
+        'extra/robots.txt',
+        ]
+    EXTRA_PATH_METADATA = {
+        'extra/robots.txt': {'path': 'robots.txt'},
+        }
+
+__ internal_metadata__
+.. _group name notation:
+   http://docs.python.org/3/library/re.html#regular-expression-syntax
+
 Feed settings
 =============
 

pelican/settings.py

@@ -258,7 +258,7 @@ def configure_settings(settings):
     for old,new,doc in [
             ('LESS_GENERATOR', 'the Webassets plugin', None),
             ('FILES_TO_COPY', 'STATIC_PATHS and EXTRA_PATH_METADATA',
-             'https://github.com/getpelican/pelican/pull/795'),
+             'https://github.com/getpelican/pelican/blob/master/docs/settings.rst#path-metadata'),
             ]:
         if old in settings:
             message = 'The {} setting has been removed in favor of {}'