From 85f9608ccb74011969d190bc085afecc71a69f3f Mon Sep 17 00:00:00 2001 From: "gw0 [http://gw.tnode.com/]" Date: Sun, 18 May 2014 20:52:26 +0200 Subject: [PATCH] Minor documentation improvements --- docs/settings.rst | 89 +++++++++++++++++++++++++++++------------------ docs/themes.rst | 64 ++++++++++++++++++++-------------- 2 files changed, 94 insertions(+), 59 deletions(-) diff --git a/docs/settings.rst b/docs/settings.rst index d785cf9b..e64da8ec 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -4,7 +4,7 @@ Settings Pelican is configurable thanks to a settings file you can pass to the command line:: - pelican content -s path/to/your/settingsfile.py + pelican content -s path/to/your/pelicanconf.py (If you used the ``pelican-quickstart`` command, your primary settings file will be named ``pelicanconf.py`` by default.) @@ -28,6 +28,7 @@ templates, which allows you to use your settings to add site-wide content. Here is a list of settings for Pelican: + Basic settings ============== @@ -225,9 +226,9 @@ configuration files for local development and publishing, respectively. 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. +``{slug}/index.html`` and link to them as ``{slug}`` for clean URLs (see +example below). 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 @@ -250,30 +251,12 @@ Example usage: * ``ARTICLE_URL = 'posts/{date:%Y}/{date:%b}/{date:%d}/{slug}/'`` * ``ARTICLE_SAVE_AS = 'posts/{date:%Y}/{date:%b}/{date:%d}/{slug}/index.html'`` +* ``PAGE_URL = 'pages/{slug}/'`` +* ``PAGE_SAVE_AS = 'pages/{slug}/index.html'`` -This would save your articles in something like ``/posts/2011/Aug/07/sample-post/index.html``, -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. -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. - -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``. - -.. note:: - 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. +This would save your articles into something like ``/posts/2011/Aug/07/sample-post/index.html``, +save your pages into ``/pages/about/index.html``, and render them available at +URLs of ``/posts/2011/Aug/07/sample-post/`` and ``/pages/about/``, respectively. ====================================================== ============================================================== Setting name (followed by default value, if any) What does it do? @@ -339,22 +322,48 @@ Setting name (followed by default value, if any) What does it do? set the corresponding ``*_SAVE_AS`` setting to ``''`` to prevent the relevant page from being generated. +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. +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. + +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``. + +.. note:: + 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. + ``DIRECT_TEMPLATES``, which are ``('index', 'tags', 'categories', 'archives')`` by default, work a bit differently than noted above. Only the ``_SAVE_AS`` settings are available: -============================================= =============================================== +============================================= ====================================================== Setting name (followed by default value) What does it do? -============================================= =============================================== +============================================= ====================================================== ``ARCHIVES_SAVE_AS = 'archives.html'`` The location to save the article archives page. +``YEAR_ARCHIVE_SAVE_AS = ''`` The location to save per-year archives of your posts. +``MONTH_ARCHIVE_SAVE_AS = ''`` The location to save per-month archives of your posts. +``DAY_ARCHIVE_SAVE_AS = ''`` The location to save per-day archives of your posts. ``AUTHORS_SAVE_AS = 'authors.html'`` The location to save the author list. ``CATEGORIES_SAVE_AS = 'categories.html'`` The location to save the category list. ``TAGS_SAVE_AS = 'tags.html'`` The location to save the tag list. -============================================= =============================================== +============================================= ====================================================== -URLs for direct template pages are theme-dependent. Some themes hard-code them: +URLs for direct template pages are theme-dependent. Some themes use +corresponding ``*_URL`` setting as string, while others hard-code them: ``'archives.html'``, ``'authors.html'``, ``'categories.html'``, ``'tags.html'``. + Timezone -------- @@ -428,6 +437,7 @@ can get a list of available locales via the ``locale -a`` command; see manpage .. _template_pages: + Template pages ============== @@ -445,6 +455,7 @@ your resume, and a contact page — you could have:: .. _path_metadata: + Path metadata ============= @@ -478,16 +489,17 @@ particular file: # STATIC_SAVE_AS = '{path}' # STATIC_URL = '{path}' STATIC_PATHS = [ - 'extra/robots.txt', + 'static/robots.txt', ] EXTRA_PATH_METADATA = { - 'extra/robots.txt': {'path': 'robots.txt'}, + 'static/robots.txt': {'path': 'robots.txt'}, } __ internal_metadata__ .. _group name notation: http://docs.python.org/3/library/re.html#regular-expression-syntax + Feed settings ============= @@ -530,6 +542,7 @@ If you don't want to generate some or any of these feeds, set the above variable .. [2] %s is the name of the category. + FeedBurner ---------- @@ -549,6 +562,7 @@ Address". In this example, the "Original Feed" would be ``http://www.example.com/thymefeeds/main.xml`` and the "Feed Address" suffix would be ``thymefeeds/main.xml``. + Pagination ========== @@ -572,6 +586,7 @@ Setting name (followed by default value, if any) What does it do? pagination output. ================================================ ===================================================== + Using Pagination Patterns ------------------------- @@ -594,6 +609,7 @@ This would cause the first page to be written to ``{base_name}/index.html``, and subsequent ones would be written into ``page/{number}`` directories. + Tag cloud ========= @@ -640,6 +656,7 @@ For example:: ... + Translations ============ @@ -656,6 +673,7 @@ Setting name (followed by default value, if any) What does it do? .. [3] %s is the language + Ordering content ================ @@ -668,6 +686,7 @@ Setting name (followed by default value) What does it do? alphabetical order; default lists alphabetically.) ================================================ ===================================================== + Themes ====== @@ -752,6 +771,7 @@ adding the following to your configuration:: CSS_FILE = "wide.css" + Logging ======= @@ -769,6 +789,7 @@ For example: ``[(logging.WARN, 'TAG_SAVE_AS is set to False')]`` .. _reading_only_modified_content: + Reading only modified content ============================= @@ -835,6 +856,7 @@ from the ``--checksum`` option. .. _writing_only_selected_content: + Writing only selected content ============================= @@ -848,6 +870,7 @@ on the command line using the ``--write-selected`` option, which accepts a comma-separated list of output file paths. By default this list is empty, so all output is written. + Example settings ================ diff --git a/docs/themes.rst b/docs/themes.rst index 4be9a8e5..c9fc2b37 100644 --- a/docs/themes.rst +++ b/docs/themes.rst @@ -16,6 +16,7 @@ then modified), you can specify that theme via the ``-t`` flag:: If you'd rather not specify the theme on every invocation, you can define ``THEME`` in your settings to point to the location of your preferred theme. + Structure ========= @@ -32,7 +33,7 @@ To make your own theme, you must follow the following structure:: ├── authors.html // must list all the authors ├── categories.html // must list all the categories ├── category.html // processed for each category - ├── index.html // the index. List all the articles + ├── index.html // the index (list all the articles) ├── page.html // processed for each page ├── tag.html // processed for each tag └── tags.html // must list all the tags. Can be a tag cloud. @@ -45,6 +46,7 @@ To make your own theme, you must follow the following structure:: 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 ======================= @@ -55,6 +57,7 @@ variables will be passed to each template at generation time. 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 ---------------- @@ -64,7 +67,7 @@ All of these settings will be available to all templates. Variable Description ============= =================================================== output_file The name of the file currently being generated. For - instance, when Pelican is rendering the homepage, + instance, when Pelican is rendering the home page, output_file will be "index.html". articles The list of articles, ordered descending by date. All the elements are `Article` objects, so you can @@ -81,6 +84,7 @@ categories A list of (category, articles) tuples, containing pages The list of pages ============= =================================================== + Sorting ------- @@ -112,12 +116,13 @@ to the locale given in your settings:: .. _datetime: http://docs.python.org/2/library/datetime.html#datetime-objects .. _strftime: http://docs.python.org/2/library/datetime.html#strftime-strptime-behavior + index.html ---------- -This is the home page of your blog, generated at output/index.html. +This is the home page or index of your blog, generated at ``index.html``. -If pagination is active, subsequent pages will reside in output/index`n`.html. +If pagination is active, subsequent pages will reside in ``index{number}.html``. ====================== =================================================== Variable Description @@ -139,14 +144,14 @@ dates_next_page The next page of articles, ordered by date, page_name 'index' -- useful for pagination links ====================== =================================================== + author.html ------------- This template will be processed for each of the existing authors, with -output generated at output/author/`author_name`.html. - -If pagination is active, subsequent pages will reside as defined by setting -AUTHOR_SAVE_AS (`Default:` output/author/`author_name'n'`.html). +output generated according to the ``AUTHOR_SAVE_AS`` setting (`Default:` +``author/{author_name}.html``). If pagination is active, subsequent pages will by +default reside at ``author/{author_name}{number}.html``. ====================== =================================================== Variable Description @@ -173,14 +178,14 @@ page_name AUTHOR_URL where everything after `{slug}` is removed -- useful for pagination links ====================== =================================================== + category.html ------------- This template will be processed for each of the existing categories, with -output generated at output/category/`category_name`.html. - -If pagination is active, subsequent pages will reside as defined by setting -CATEGORY_SAVE_AS (`Default:` output/category/`category_name'n'`.html). +output generated according to the ``CATEGORY_SAVE_AS`` setting (`Default:` +``category/{category_name}.html``). If pagination is active, subsequent pages will by +default reside at ``category/{category_name}{number}.html``. ====================== =================================================== Variable Description @@ -207,11 +212,14 @@ page_name CATEGORY_URL where everything after `{slug}` is removed -- useful for pagination links ====================== =================================================== + article.html ------------- -This template will be processed for each article, with .html files saved -as output/`article_name`.html. Here are the specific variables it gets. +This template will be processed for each article, with +output generated according to the ``ARTICLE_SAVE_AS`` setting (`Default:` +``{article_name}.html``). The following variables are available when +rendering. ============= =================================================== Variable Description @@ -249,8 +257,10 @@ image for the Facebook open graph tags that will change for each article: page.html --------- -This template will be processed for each page, with corresponding .html files -saved as output/`page_name`.html. +This template will be processed for each page, with +output generated according to the ``PAGE_SAVE_AS`` setting (`Default:` +``pages/{page_name}.html``). The following variables are available when +rendering. ============= =================================================== Variable Description @@ -259,14 +269,14 @@ page The page object to be displayed. You can access its title, slug, and content. ============= =================================================== + tag.html -------- -This template will be processed for each tag, with corresponding .html files -saved as output/tag/`tag_name`.html. - -If pagination is active, subsequent pages will reside as defined in setting -TAG_SAVE_AS (`Default:` output/tag/`tag_name'n'`.html). +This template will be processed for each tag, with +output generated according to the ``TAG_SAVE_AS`` setting (`Default:` +``tag/{tag_name}.html``). If pagination is active, subsequent pages will by +default reside at ``tag/{tag_name}{number}.html``. ====================== =================================================== Variable Description @@ -293,12 +303,13 @@ page_name TAG_URL where everything after `{slug}` is removed -- useful for pagination links ====================== =================================================== + period_archives.html -------------------- This template will be processed for each year of your posts if a path -for YEAR_ARCHIVE_SAVE_AS is defined, each month if MONTH_ARCHIVE_SAVE_AS -is defined and each day if DAY_ARCHIVE_SAVE_AS is defined. +for ``YEAR_ARCHIVE_SAVE_AS`` is defined, each month if ``MONTH_ARCHIVE_SAVE_AS`` +is defined, and each day if ``DAY_ARCHIVE_SAVE_AS`` is defined. =================== =================================================== Variable Description @@ -313,8 +324,9 @@ period A tuple of the form (`year`, `month`, `day`) that =================== =================================================== -You can see an example of how to use `period` in the ``simple`` theme's -period_archives.html +You can see an example of how to use `period` in the `"simple" theme +`_. + Feeds ===== @@ -346,7 +358,7 @@ missing, it will be replaced by the matching template from the ``simple`` theme. So if the HTML structure of a template in the ``simple`` theme is right for you, you don't have to write a new template from scratch. -You can also extend templates from the ``simple`` themes in your own themes by +You can also extend templates from the ``simple`` theme in your own themes by using the ``{% extends %}`` directive as in the following example: .. code-block:: html+jinja