Merge branch 'master' of github.com:getpelican/pelican

docs/changelog.rst

@@ -10,7 +10,7 @@ Next release
 * Deprecate ``FILES_TO_COPY`` in favor of ``STATIC_PATHS`` and
   ``EXTRA_PATH_METADATA``
 * Add support for ``{}`` in relative links syntax, besides ``||``
-* Add support for |tag| and |category| relative links
+* Add support for ``{tag}`` and ``{category}`` relative links
 
 3.2.1 and 3.2.2
 ===============

docs/getting_started.rst

@@ -533,6 +533,9 @@ which posts are translations::
 
     That's true, foobar is still alive!
 
+
+.. _internal_pygments_options:
+
 Syntax highlighting
 -------------------
 
@@ -556,6 +559,65 @@ indenting both the identifier and code::
 The specified identifier (e.g. ``python``, ``ruby``) should be one that
 appears on the `list of available lexers <http://pygments.org/docs/lexers/>`_.
 
+When using reStructuredText the following options are available in the
+code-block directive:
+
+=============   ============  =========================================
+Option          Valid values  Description
+=============   ============  =========================================
+anchorlinenos   N/A           If present wrap line numbers in <a> tags.
+classprefix     string        String to prepend to token class names
+hl_lines        numbers       List of lines to be highlighted.
+lineanchors     string        Wrap each line in an anchor using this
+                              string and -linenumber.
+linenos         string        If present or set to "table" output line 
+                              numbers in a table, if set to
+                              "inline" output them inline. "none" means
+                              do not output the line numbers for this 
+                              table.
+linenospecial   number        If set every nth line will be given the 
+                              'special' css class.
+linenostart     number        Line number for the first line.
+linenostep      number        Print every nth line number.
+lineseparator   string        String to print between lines of code,
+                              '\n' by default.
+linespans       string        Wrap each line in a span using this and
+                              -linenumber.
+nobackground    N/A           If set do not output background color for
+                              the wrapping element
+nowrap          N/A           If set do not wrap the tokens at all.
+tagsfile        string        ctags file to use for name definitions.
+tagurlformat    string        format for the ctag links.
+=============   ============  =========================================
+
+Note that, depending on its version, your pygments module might not have
+all of these available. See the `Pygments documentation
+<http://pygments.org/docs/formatters/>`_ for the HTML formatter for more
+details on each of the options.
+
+for example the below code block enables line numbers, starting at 153,
+and prefixes the Pygments CSS classes with *pgcss* to make the names
+more unique and avoid possible CSS conflicts::
+
+    .. code-block:: identifier
+        :classprefix: pgcss
+        :linenos: table
+        :linenostart: 153
+
+       <indented code block goes here>
+
+It is also possible to specify the ``PYGMENTS_RST_OPTIONS`` variable
+in your Pelican configuration file for settings that will be
+automatically applied to every code block.
+
+For example, if you wanted to have line numbers on for every code block
+and a CSS prefix you would set this variable to::
+
+    PYGMENTS_RST_OPTIONS = { 'classprefix': 'pgcss', 'linenos': 'table'}
+
+If specified, settings for individual code blocks will override the
+defaults in the configuration file.
+
 Publishing drafts
 -----------------
 

docs/settings.rst

@@ -161,6 +161,9 @@ Setting name (default value)                                            What doe
                                                                         to enclose the identifier, say ``filename``, in ``{}`` or ``||``.
                                                                         Identifier between ``{`` and ``}`` goes into the ``what`` capturing group.
                                                                         For details see :ref:`ref-linking-to-internal-content`.
+`PYGMENTS_RST_OPTIONS` (``[]``)                                         A list of default Pygments settings for your reStructuredText
+                                                                        code blocks. See :ref:`internal_pygments_options` for a list of
+                                                                        supported options.
 =====================================================================   =====================================================================
 
 .. [#] Default is the system locale.
@@ -602,7 +605,10 @@ Setting name (default value)                        What does it do?
                                                     `THEME_STATIC_PATHS`. Default is `theme`.
 `THEME_STATIC_PATHS` (``['static']``)               Static theme paths you want to copy. Default
                                                     value is `static`, but if your theme has
-                                                    other static paths, you can put them here.
+                                                    other static paths, you can put them here. If files
+                                                    or directories with the same names are included in
+                                                    the paths defined in this settings, they will be
+                                                    progressively overwritten.
 `CSS_FILE` (``'main.css'``)                         Specify the CSS file you want to load.
 ================================================    =====================================================