diff --git a/docs/faq.rst b/docs/faq.rst index f7ee6826..da37af04 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -23,8 +23,8 @@ How can I help? There are several ways to help out. First, you can report any Pelican suggestions or problems you might have via IRC or the `issue tracker `_. If submitting an issue -report, please check the existing issue list first in order to avoid submitting -a duplicate issue. +report, please first check the existing issue list (both open and closed) in +order to avoid submitting a duplicate issue. If you want to contribute, please fork `the git repository `_, create a new feature branch, make @@ -96,7 +96,8 @@ This metadata can then be accessed in templates such as ``article.html`` via:: Last modified: {{ article.modified }} {% endif %} -If you want to include metadata in templates outside the article context (e.g., ``base.html``), the ``if`` statement should instead be:: +If you want to include metadata in templates outside the article context (e.g., +``base.html``), the ``if`` statement should instead be:: {% if article and article.modified %} @@ -196,10 +197,10 @@ Is Pelican only suitable for blogs? =================================== No. Pelican can be easily configured to create and maintain any type of static site. -This may require little customization of your theme and Pelican configuration. +This may require a little customization of your theme and Pelican configuration. For example, if you are building a launch site for your product and do not need -tags on your site. You can hide tags by removing relevant html code from your theme. -You can also disable generation of tags pages:: +tags on your site, you could remove the relevant HTML code from your theme. +You can also disable generation of tag-related pages via:: TAGS_SAVE_AS = '' TAG_SAVE_AS = '' diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 2605c3a1..201b9ad4 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -83,15 +83,20 @@ Viewing the generated files --------------------------- The files generated by Pelican are static files, so you don't actually need -anything special to view them. You can either use your browser to open the -files on your disk:: +anything special to view them. You can use your browser to open the generated +HTML files directly:: firefox output/index.html -Or run a simple web server using Python:: +Because the above method may have trouble locating your CSS and other linked +assets, running a simple web server using Python will often provide a more +reliable previewing experience:: cd output && python -m SimpleHTTPServer +Once the ``SimpleHTTPServer`` has been started, you can preview your site at +http://localhost:8000/ + Upgrading --------- @@ -452,25 +457,24 @@ And ``image-test.md`` would include:: ![Alt Text]({filename}/images/han.jpg) Any content can be linked in this way. What happens is that the ``images`` -directory gets copied to ``output/static/`` upon publishing. This is -because ``images`` is in the ``settings["STATIC_PATHS"]`` list by default. If -you want to have another directory, say ``pdfs`` you would need to add the -following to ``pelicanconf.py``:: +directory gets copied to ``output/`` during site generation because Pelican +includes ``images`` in the ``STATIC_PATHS`` setting's list by default. If +you want to have another directory, say ``pdfs``, copied from your content to +your output during site generation, you would need to add the following to +your settings file:: STATIC_PATHS = ['images', 'pdfs'] -And then the ``pdfs`` directory would also be copied to ``output/static/``. +After the above line has been added, subsequent site generation should copy the +``content/pdfs/`` directory to ``output/pdfs/``. You can also link to categories or tags, using the ``{tag}tagname`` and ``{category}foobar`` syntax. -For backward compatibility, Pelican also supports bars ``||``, besides ``{}``, -i.e. the ``filename``, ``tag`` and ``category`` identifiers can be enclosed -in bars ``|`` instead of braces ``{}``, for example, ``|filename|an_article.rst``, -``|tag|tagname``, ``|category|foobar``. - -Using ``{}`` ensures that the syntax will not collide with markdown extensions or -reST directives. +For backward compatibility, Pelican also supports bars (``||``) in addition to +curly braces (``{}``). For example: ``|filename|an_article.rst``, +``|tag|tagname``, ``|category|foobar``. The syntax was changed from ``||`` to +``{}`` to avoid collision with Markdown extensions or reST directives. Importing an existing blog -------------------------- @@ -590,12 +594,12 @@ 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 -`_ for the HTML formatter for more +Note that, depending on the version, your Pygments module might not have +all of these options available. Refer to the *HtmlFormatter* section of the +`Pygments documentation `_ for more details on each of the options. -for example the below code block enables line numbers, starting at 153, +For example, the following 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:: @@ -606,25 +610,25 @@ more unique and avoid possible CSS conflicts:: -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. +It is also possible to specify the ``PYGMENTS_RST_OPTIONS`` variable in your +Pelican settings file to include options that will be automatically applied to +every code block. -For example, if you wanted to have line numbers on for every code block +For example, if you want to have line numbers displayed for every code block and a CSS prefix you would set this variable to:: - PYGMENTS_RST_OPTIONS = { 'classprefix': 'pgcss', 'linenos': 'table'} + PYGMENTS_RST_OPTIONS = {'classprefix': 'pgcss', 'linenos': 'table'} -If specified, settings for individual code blocks will override the -defaults in the configuration file. +If specified, settings for individual code blocks will override the defaults in +your settings file. Publishing drafts ----------------- If you want to publish an article as a draft (for friends to review before -publishing, for example), you can add a ``status: draft`` attribute to its +publishing, for example), you can add a ``Status: draft`` attribute to its metadata. That article will then be output to the ``drafts`` folder and not -listed on the index page nor on any category page. +listed on the index page nor on any category or tag page. .. _virtualenv: http://www.virtualenv.org/ .. _W3C ISO 8601: http://www.w3.org/TR/NOTE-datetime diff --git a/docs/index.rst b/docs/index.rst index eb8883ce..35e859d5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -51,9 +51,13 @@ If you want to see new features in Pelican, don't hesitate to offer suggestions, clone the repository, etc. There are many ways to :doc:`contribute`. That's open source, dude! -Send a message to "authors at getpelican dot com" with any requests/feedback! You -can also join the team at `#pelican on Freenode`_ (or if you don't have an IRC -client handy, use the webchat_ for quick feedback. +Send a message to "authors at getpelican dot com" with any requests/feedback. +For a more immediate response, you can also join the team via IRC at +`#pelican on Freenode`_ — if you don't have an IRC client handy, use the +webchat_ for quick feedback. If you ask a question via IRC and don't get an +immediate response, don't leave the channel! It may take a few hours because +of time zone differences, but f you are patient and remain in the channel, +someone will almost always respond to your inquiry. Documentation ------------- diff --git a/docs/plugins.rst b/docs/plugins.rst index 29d67e24..6de01d05 100644 --- a/docs/plugins.rst +++ b/docs/plugins.rst @@ -135,15 +135,15 @@ shared in the documentation somewhere, so here they are! How to create a new reader -------------------------- -One thing you might want is to add the support for your very own input -format. While it might make sense to add this feature in pelican core, we -wisely chose to avoid this situation, and have the different readers defined in -plugins. +One thing you might want is to add support for your very own input format. +While it might make sense to add this feature in Pelican core, we +wisely chose to avoid this situation and instead have the different readers +defined via plugins. The rationale behind this choice is mainly that plugins are really easy to -write and don't slow down pelican itself when they're not active. +write and don't slow down Pelican itself when they're not active. -No more talking, here is the example:: +No more talking — here is an example:: from pelican import signals from pelican.readers import BaseReader @@ -153,7 +153,7 @@ No more talking, here is the example:: enabled = True # Yeah, you probably want that :-) # The list of file extensions you want this reader to match with. - # In the case multiple readers use the same extensions, the latest will + # If multiple readers were to use the same extension, the latest will # win (so the one you're defining here, most probably). file_extensions = ['yeah'] @@ -173,7 +173,7 @@ No more talking, here is the example:: def add_reader(readers): readers.reader_classes['yeah'] = NewReader - # this is how pelican works. + # This is how pelican works. def register(): signals.readers_init.connect(add_reader) diff --git a/docs/settings.rst b/docs/settings.rst index e8965731..b6c18fa9 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -84,10 +84,10 @@ Setting name (default value) What doe here or a single string representing one locale. When providing a list, all the locales will be tried until one works. -`READERS` (``{}``) A dict of file extensions / Reader classes to overwrite or - add file readers. for instance, to avoid processing .html files: - ``READERS = {'html': None}``. Or to add a custom reader for the - `foo` extension: ``READERS = {'foo': FooReader}`` +`READERS` (``{}``) A dictionary of file extensions / Reader classes for Pelican to + process or ignore. For example, to avoid processing .html files, + set: ``READERS = {'html': None}``. To add a custom reader for the + `foo` extension, set: ``READERS = {'foo': FooReader}`` `IGNORE_FILES` (``['.#*']``) A list of file globbing patterns to match against the source files to be ignored by the processor. For example, the default ``['.#*']`` will ignore emacs lock files. @@ -106,11 +106,9 @@ Setting name (default value) What doe `PAGE_EXCLUDES` (``()``) A list of directories to exclude when looking for pages. `ARTICLE_DIR` (``''``) Directory to look at for articles, relative to `PATH`. `ARTICLE_EXCLUDES`: (``('pages',)``) A list of directories to exclude when looking for articles. -`PDF_GENERATOR` (``False``) Set to ``True`` if you want PDF versions of your documents to be. - generated. You will need to install ``rst2pdf``. `OUTPUT_SOURCES` (``False``) Set to True if you want to copy the articles and pages in their original format (e.g. Markdown or reStructuredText) to the - specified OUTPUT_PATH. + specified ``OUTPUT_PATH``. `OUTPUT_SOURCES_EXTENSION` (``.text``) Controls the extension that will be used by the SourcesGenerator. Defaults to ``.text``. If not a valid string the default value will be used. @@ -144,7 +142,7 @@ Setting name (default value) What doe are not needed, set ``DIRECT_TEMPLATES = ('index', 'archives')`` `PAGINATED_DIRECT_TEMPLATES` (``('index',)``) Provides the direct templates that should be paginated. `SUMMARY_MAX_LENGTH` (``50``) When creating a short summary of an article, this will - be the default length in words of the text created. + be the default length (measured in words) of the text created. This only applies if your content does not otherwise specify a summary. Setting to ``None`` will cause the summary to be a copy of the original content. @@ -155,9 +153,9 @@ Setting name (default value) What doe `ASCIIDOC_OPTIONS` (``[]``) A list of options to pass to AsciiDoc. See the `manpage `_ `WITH_FUTURE_DATES` (``True``) If disabled, content with dates in the future will get a - default status of draft. + default status of ``draft``. `INTRASITE_LINK_REGEX` (``'[{|](?P.*?)[|}]'``) Regular expression that is used to parse internal links. - Default syntax of links to internal files, tags, etc. is + Default syntax of links to internal files, tags, etc., is 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`. @@ -173,7 +171,7 @@ URL settings ------------ The first thing to understand is that there are currently two supported methods -for URL formation: *relative* and *absolute*. Document-relative URLs are useful +for URL formation: *relative* and *absolute*. Relative URLs are useful when testing locally, and absolute URLs are reliable and most useful when publishing. One method of supporting both is to have one Pelican configuration file for local development and another for publishing. To see an example of this @@ -181,16 +179,17 @@ type of setup, use the ``pelican-quickstart`` script as described at the top of the :doc:`Getting Started ` page, which will produce two separate configuration files for local development and publishing, respectively. -You can customize the URLs and locations where files will be saved. The URLs 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. These settings give you the flexibility to place your -articles and pages anywhere you want. +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. These +settings give you the flexibility to place your articles and pages anywhere you +want. .. note:: - If you specify a datetime directive, it will be substituted using the + If you specify a ``datetime`` directive, it will be substituted using the input files' date metadata attribute. If the date is not specified for a - particular file, Pelican will rely on the file's mtime timestamp. + particular file, Pelican will rely on the file's ``mtime`` timestamp. Check the Python datetime documentation at http://bit.ly/cNcJUC for more information. @@ -213,7 +212,7 @@ and the URL to this would be ``/posts/2011/Aug/07/sample-post/``. Pelican can optionally create per-year, per-month, and per-day archives of your posts. These secondary archives are disabled by default but are automatically -enabled if you supply format strings for their respective `_SAVE_AS` settings. +enabled if you supply format strings for their respective ``_SAVE_AS`` settings. Period archives fit intuitively with the hierarchical model of web URLs and can make it easier for readers to navigate through the posts you've written over time. @@ -222,12 +221,12 @@ Example usage: * YEAR_ARCHIVE_SAVE_AS = ``'posts/{date:%Y}/index.html'`` * MONTH_ARCHIVE_SAVE_AS = ``'posts/{date:%Y}/{date:%b}/index.html'`` -With these settings, Pelican will create an archive of all your posts for the year -at (for instance) 'posts/2011/index.html', and an archive of all your posts for -the month at 'posts/2011/Aug/index.html'. +With these settings, Pelican will create an archive of all your posts for the +year at (for instance) ``posts/2011/index.html`` and an archive of all your +posts for the month at ``posts/2011/Aug/index.html``. .. note:: - Period archives work best when the final path segment is 'index.html'. + Period archives work best when the final path segment is ``index.html``. This way a reader can remove a portion of your URL and automatically arrive at an appropriate archive of posts, without having to specify a page name. @@ -299,10 +298,11 @@ Have a look at `the wikipedia page`_ to get a list of valid timezone values. Date format and locale ---------------------- -If no DATE_FORMATS are set, Pelican will fall back to DEFAULT_DATE_FORMAT. If -you need to maintain multiple languages with different date formats, you can -set this dict using the language name (``lang`` metadata in your post content) -as the key. Regarding available format codes, see `strftime document of python`_ : +If no ``DATE_FORMATS`` are set, Pelican will fall back to +``DEFAULT_DATE_FORMAT``. If you need to maintain multiple languages with +different date formats, you can set the ``DATE_FORMATS`` dictionary using the +language name (``lang`` metadata in your post content) as the key. Regarding +available format codes, see `strftime document of python`_ : .. parsed-literal:: @@ -320,8 +320,8 @@ You can set locale to further control date format: ) Also, it is possible to set different locale settings for each language. If you -put (locale, format) tuples in the dict, this will override the LOCALE setting -above: +put (locale, format) tuples in the dict, this will override the ``LOCALE`` +setting above: .. parsed-literal:: # On Unix/Linux @@ -473,9 +473,9 @@ Pagination ========== The default behaviour of Pelican is to list all the article titles along -with a short description on the index page. While it works pretty well -for small-to-medium blogs, for sites with large quantity of articles it would -be convenient to have a way to paginate the list. +with a short description on the index page. While this works well for +small-to-medium sites, sites with a large quantity of articles will probably +benefit from paginating this list. You can use the following settings to configure the pagination. @@ -483,8 +483,8 @@ You can use the following settings to configure the pagination. Setting name (default value) What does it do? ================================================ ===================================================== `DEFAULT_ORPHANS` (``0``) The minimum number of articles allowed on the - last page. Use this when you don't want to - have a last page with very few articles. + last page. Use this when you don't want the last page + to only contain a handful of articles. `DEFAULT_PAGINATION` (``False``) The maximum number of articles to include on a page, not including orphans. False to disable pagination. @@ -528,7 +528,7 @@ Setting name (default value) What does it do? `TAG_CLOUD_MAX_ITEMS` (``100``) Maximum number of tags in the cloud. ================================================ ===================================================== -The default theme does not include a tag cloud, but it is pretty easy to add:: +The default theme does not include a tag cloud, but it is pretty easy to add one::
    {% for tag in tag_cloud %} @@ -536,9 +536,10 @@ The default theme does not include a tag cloud, but it is pretty easy to add:: {% endfor %}
-You should then also define CSS styles with appropriate classes (tag-0 to tag-N, where -N matches `TAG_CLOUD_STEPS` -1), tag-0 being the most frequent, and define a ul.tagcloud -class with appropriate list-style to create the cloud, for example:: +You should then also define CSS styles with appropriate classes (tag-0 to tag-N, +where N matches ``TAG_CLOUD_STEPS`` -1), tag-0 being the most frequent, and +define a ``ul.tagcloud`` class with appropriate list-style to create the cloud. +For example:: ul.tagcloud { list-style: none; diff --git a/docs/themes.rst b/docs/themes.rst index ddf509f8..c5aafb46 100644 --- a/docs/themes.rst +++ b/docs/themes.rst @@ -30,12 +30,12 @@ To make your own theme, you must follow the following structure:: └── tags.html // must list all the tags. Can be a tag cloud. * `static` contains all the static assets, which will be copied to the output - `theme` folder. I've put the CSS and image folders here, but they are - just examples. Put what you need here. + `theme` folder. The above filesystem layout includes CSS and image folders, + but those are just examples. Put what you need here. * `templates` contains all the templates that will be used to generate the content. - I've just put the mandatory templates here; you can define your own if it helps - you keep things organized while creating your theme. + The template files listed above are mandatory; you can add your own templates + if it helps you keep things organized while creating your theme. Templates and variables ======================= @@ -44,8 +44,8 @@ The idea is to use a simple syntax that you can embed into your HTML pages. This document describes which templates should exist in a theme, and which variables will be passed to each template at generation time. -All templates will receive the variables defined in your settings file, if they -are in all-caps. You can access them directly. +All templates will receive the variables defined in your settings file, as long +as they are in all-caps. You can access them directly. Common variables ---------------- @@ -58,19 +58,18 @@ Variable Description output_file The name of the file currently being generated. For instance, when Pelican is rendering the homepage, output_file will be "index.html". -articles The list of articles, ordered descending by date +articles The list of articles, ordered descending by date. All the elements are `Article` objects, so you can access their attributes (e.g. title, summary, author etc.). Sometimes this is shadowed (for instance in the tags page). You will then find info about it in the `all_articles` variable. dates The same list of articles, but ordered by date, - ascending + ascending. tags A list of (tag, articles) tuples, containing all the tags. categories A list of (category, articles) tuples, containing - all the categories. - and the list of respective articles (values) + all the categories and corresponding articles (values) pages The list of pages ============= =================================================== @@ -91,9 +90,9 @@ __ http://jinja.pocoo.org/docs/templates/#sort Date Formatting --------------- -Pelican formats the date with according to your settings and locale +Pelican formats the date according to your settings and locale (``DATE_FORMATS``/``DEFAULT_DATE_FORMAT``) and provides a -``locale_date`` attribute. On the other hand, ``date`` attribute will +``locale_date`` attribute. On the other hand, the ``date`` attribute will be a `datetime`_ object. If you need custom formatting for a date different than your settings, use the Jinja filter ``strftime`` that comes with Pelican. Usage is same as Python `strftime`_ format, diff --git a/docs/tips.rst b/docs/tips.rst index 1864f0dd..7629481f 100644 --- a/docs/tips.rst +++ b/docs/tips.rst @@ -15,16 +15,16 @@ Project Pages and User Pages. Project Pages ------------- -To publish a Pelican site as Project Pages you need to *push* the content of +To publish a Pelican site as a Project Page you need to *push* the content of the ``output`` dir generated by Pelican to a repository's ``gh-pages`` branch on GitHub. The excellent `ghp-import `_, which can be installed with ``easy_install`` or ``pip``, makes this process really easy. -For example, if the sources of your Pelican site are contained in a GitHub -repository, and if you want to publish your Pelican site as Project Pages of -this repository, you can then use the following:: +For example, if the source of your Pelican site is contained in a GitHub +repository, and if you want to publish that Pelican site in the form of Project +Pages to this repository, you can then use the following:: $ pelican content -o output -s pelicanconf.py $ ghp-import output @@ -38,28 +38,28 @@ already exist). The ``git push origin gh-pages`` command updates the remote .. note:: The ``github`` target of the Makefile created by the ``pelican-quickstart`` - command publishes the Pelican site as Project Pages as described above. + command publishes the Pelican site as Project Pages, as described above. User Pages ---------- -To publish a Pelican site as User Pages you need to *push* the content of the -``output`` dir generated by Pelican to the ``master`` branch of your -``.github.com`` repository on GitHub. +To publish a Pelican site in the form of User Pages, you need to *push* the +content of the ``output`` dir generated by Pelican to the ``master`` branch of +your ``.github.io`` repository on GitHub. Again, you can take advantage of ``ghp-import``:: $ pelican content -o output -s pelicanconf.py $ ghp-import output - $ git push git@github.com:elemoine/elemoine.github.com.git gh-pages:master + $ git push git@github.com:elemoine/elemoine.github.io.git gh-pages:master The ``git push`` command pushes the local ``gh-pages`` branch (freshly updated -by the ``ghp-import`` command) to the ``elemoine.github.com`` repository's +by the ``ghp-import`` command) to the ``elemoine.github.io`` repository's ``master`` branch on GitHub. .. note:: - To publish your Pelican site as User Pages feel free to adjust the the + To publish your Pelican site as User Pages, feel free to adjust the ``github`` target of the Makefile. Extra Tips @@ -67,28 +67,30 @@ Extra Tips Tip #1: -To automatically update your Pelican site on each commit you can create +To automatically update your Pelican site on each commit, you can create a post-commit hook. For example, you can add the following to ``.git/hooks/post-commit``:: - pelican pelican content -o output -s pelicanconf.py && ghp-import output && git push origin gh-pages + pelican content -o output -s pelicanconf.py && ghp-import output && git push origin gh-pages Tip #2: To use a `custom domain `_ with -GitHub Pages you need to have a ``CNAME`` file at the root of your pages. For -that you will add ``CNAME`` file to your ``content``, dir and use the -``FILES_TO_COPY`` setting variable to tell Pelican to copy that file -to the ``output`` dir. For example:: +GitHub Pages, you need to put the domain of your site (e.g., +``blog.example.com``) inside a ``CNAME`` file at the root of your site. To do +this, create the ``content/extras/`` directory and add a ``CNAME`` file to it. +Then use the ``STATIC_PATHS`` setting to tell Pelican to copy this file to your +output directory. For example:: - FILES_TO_COPY = (('extra/CNAME', 'CNAME'),) + STATIC_PATHS = ['images', 'extra/CNAME'] + EXTRA_PATH_METADATA = {'extra/CNAME': {'path': 'CNAME'},} -How to add Youtube or Vimeo Videos +How to add YouTube or Vimeo Videos ================================== -The easiest way is to paste embed code of the video from these sites in your -markup file. +The easiest way is to paste the embed code of the video from these sites +directly into your source content. -Alternatively, you can also use Pelican plugins like ``liquid_tags`` or ``pelican_youtube`` -or ``pelican_vimeo`` to embed videos in your blog. +Alternatively, you can also use Pelican plugins like ``liquid_tags``, +``pelican_youtube``, or ``pelican_vimeo`` to embed videos in your content.