diff --git a/docs/getting_started.rst b/docs/getting_started.rst index b7cbe951..985718b5 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -17,7 +17,7 @@ While the above is the simplest method, the recommended approach is to create a virtual environment for Pelican via virtualenv_ and virtualenvwrapper_ before installing Pelican. Assuming you've followed the virtualenvwrapper `installation `_ -and `shell configuration +and `shell configuration `_ steps, you can then open a new terminal session and create a new virtual environment for Pelican:: @@ -26,7 +26,7 @@ environment for Pelican:: Once the virtual environment has been created and activated, Pelican can be be installed via ``pip`` or ``easy_install`` as noted above. Alternatively, if -you have the project source, you can install Pelican using the distutils +you have the project source, you can install Pelican using the distutils method:: $ cd path-to-Pelican-source @@ -209,7 +209,7 @@ Pages If you create a folder named ``pages``, all the files in it will be used to generate static pages. -Then, use the ``DISPLAY_PAGES_ON_MENU`` setting, which will add all the pages to +Then, use the ``DISPLAY_PAGES_ON_MENU`` setting, which will add all the pages to the menu. If you want to exclude any pages from being linked to or listed in the menu @@ -219,7 +219,7 @@ things like making error pages that fit the generated theme of your site. Importing an existing blog -------------------------- -It is possible to import your blog from Dotclear, WordPress, and RSS feeds using +It is possible to import your blog from Dotclear, WordPress, and RSS feeds using a simple script. See :ref:`import`. Translations @@ -277,14 +277,13 @@ For RestructuredText, use the code-block directive:: -For Markdown, include the language identifier just above code blocks:: +For Markdown, include the language identifier just above the code block, +indenting both the identifier and code:: :::identifier - - (indent both the identifier and code) -The specified identifier (e.g. ``python``, ``ruby``) should be one that +The specified identifier (e.g. ``python``, ``ruby``) should be one that appears on the `list of available lexers `_. Publishing drafts diff --git a/docs/settings.rst b/docs/settings.rst index 2f5027b9..bd22f872 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -448,26 +448,27 @@ adding the following to your configuration:: Asset management ---------------- -The `WEBASSETS` setting allows to use the `webassets`_ module to manage assets -(css, js). The module must first be installed:: +The `WEBASSETS` setting allows you to use the `webassets`_ module to manage +assets such as CSS and JS files. The module must first be installed:: pip install webassets -`webassets` allows to concatenate your assets and to use almost all of the -hype tools of the moment (see the `documentation`_): +The `webassets` module allows you to perform a number of useful asset management +functions, including: -* css minifier (`cssmin`, `yuicompressor`, ...) -* css compiler (`less`, `sass`, ...) -* js minifier (`uglifyjs`, `yuicompressor`, `closure`, ...) +* CSS minifier (`cssmin`, `yuicompressor`, ...) +* CSS compiler (`less`, `sass`, ...) +* JS minifier (`uglifyjs`, `yuicompressor`, `closure`, ...) -Others filters include gzip compression, integration of images in css with -`datauri` and more. Webassets also append a version identifier to your asset -url to convince browsers to download new versions of your assets when you use -far future expires headers. +Others filters include gzip compression, integration of images in CSS via data +URIs, and more. `webassets` can also append a version identifier to your asset +URL to convince browsers to download new versions of your assets when you use +far-future expires headers. Please refer to the `webassets documentation`_ for +more information. -When using it with Pelican, `webassets` is configured to process assets in the -``OUTPUT_PATH/theme`` directory. You can use it in your templates with a -template tag, for example: +When using with Pelican, `webassets` is configured to process assets in the +``OUTPUT_PATH/theme`` directory. You can use `webassets` in your templates by +including one or more template tags. For example... .. code-block:: jinja @@ -475,22 +476,22 @@ template tag, for example: {% endassets %} -will produce a minified css file with the version identifier: +... will produce a minified css file with a version identifier: .. code-block:: html -The filters can be combined, for example to use the `sass` compiler and minify -the output:: +These filters can be combined. Here is an example that uses the SASS compiler +and minifies the output: .. code-block:: jinja -{% assets filters="sass,cssmin", output="css/style.min.css", "css/style.scss" %} - -{% endassets %} + {% assets filters="sass,cssmin", output="css/style.min.css", "css/style.scss" %} + + {% endassets %} -Another example for javascript: +Another example for Javascript: .. code-block:: jinja @@ -498,20 +499,20 @@ Another example for javascript: {% endassets %} -will produce a minified and gzipped js file: +The above will produce a minified and gzipped JS file: .. code-block:: html -Pelican's debug mode is propagated to webassets to disable asset packaging, +Pelican's debug mode is propagated to `webassets` to disable asset packaging and instead work with the uncompressed assets. However, this also means that -the `less` and `sass` files are not compiled, this should be fixed in a future -version of webassets (cf. the related `bug report +the LESS and SASS files are not compiled. This should be fixed in a future +version of `webassets` (cf. the related `bug report `_). .. _webassets: https://github.com/miracle2k/webassets -.. _documentation: http://webassets.readthedocs.org/en/latest/builtin_filters.html +.. _webassets documentation: http://webassets.readthedocs.org/en/latest/builtin_filters.html Example settings ================