diff --git a/docs/settings.rst b/docs/settings.rst index 4701e92d..e125f25a 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 ============== @@ -210,9 +211,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). 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 @@ -235,30 +236,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``, +pages into ``/pages/about/index.html``, and make them available on URLs ``/posts/2011/Aug/07/sample-post/`` +and ``/pages/about/``. ====================================================== ======================================================== Setting name (followed by default value, if any) What does it do? @@ -289,9 +272,6 @@ Setting name (followed by default value, if any) What does it do? ``TAG_SAVE_AS = 'tag/{slug}.html'`` The location to save the tag page. ``AUTHOR_URL = 'author/{slug}.html'`` The URL to use for an author. ``AUTHOR_SAVE_AS = 'author/{slug}.html'`` The location to save an author. -``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. ``SLUG_SUBSTITUTIONS` = ()`` Substitutions to make prior to stripping out non-alphanumerics when generating slugs. Specified as a list of 2-tuples of ``(from, to)`` which are @@ -305,22 +285,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 -------- @@ -390,6 +396,7 @@ can get a list of available locales via the ``locale -a`` command; see manpage .. _template_pages: + Template pages ============== @@ -407,6 +414,7 @@ your resume, and a contact page — you could have:: .. _path_metadata: + Path metadata ============= @@ -440,16 +448,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 ============= @@ -492,6 +501,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 ---------- @@ -511,6 +521,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 ========== @@ -534,6 +545,7 @@ Setting name (followed by default value, if any) What does it do? pagination output. ================================================ ===================================================== + Using Pagination Patterns ------------------------- @@ -556,6 +568,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 ========= @@ -602,6 +615,7 @@ For example:: ... + Translations ============ @@ -618,6 +632,7 @@ Setting name (followed by default value, if any) What does it do? .. [3] %s is the language + Ordering content ================ @@ -630,6 +645,7 @@ Setting name (followed by default value) What does it do? alphabetical order; default lists alphabetically.) ================================================ ===================================================== + Themes ====== @@ -714,6 +730,7 @@ adding the following to your configuration:: CSS_FILE = "wide.css" + Logging ======= @@ -731,6 +748,7 @@ For example: ``[(logging.WARN, 'TAG_SAVE_AS is set to False')]`` .. _reading_only_modified_content: + Reading only modified content ============================= @@ -797,6 +815,7 @@ from the ``--checksum`` option. .. _writing_only_selected_content: + Writing only selected content ============================= @@ -810,6 +829,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 7fcba671..56c31e26 100644 --- a/docs/themes.rst +++ b/docs/themes.rst @@ -14,7 +14,8 @@ then modified), you can specify that theme via the ``-t`` flag:: pelican content -s pelicanconf.py -t /projects/your-site/themes/your-theme 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. +>`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 home page (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 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 @@ -131,14 +136,14 @@ dates_page The current 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 setting ``AUTHOR_SAVE_AS`` (`Default:` +``author/{author_name}.html``). If pagination is active, subsequent pages will by +default reside on ``author/{author_name}{number}.html``. =================== =================================================== Variable Description @@ -157,14 +162,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 setting ``CATEGORY_SAVE_AS`` (`Default:` +``category/{category_name}.html``). If pagination is active, subsequent pages will by +default reside on ``category/{category_name}{number}.html``. =================== =================================================== Variable Description @@ -183,11 +188,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 setting ``ARTICLE_SAVE_AS`` (`Default:` +``{article_name}.html``). The following variables are available when +rendering. ============= =================================================== Variable Description @@ -225,8 +233,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 setting ``PAGE_SAVE_AS`` (`Default:` +``pages/{page_name}.html``). The following variables are available when +rendering. ============= =================================================== Variable Description @@ -235,14 +245,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 setting ``TAG_SAVE_AS`` (`Default:` +``tag/{tag_name}.html``). If pagination is active, subsequent pages will by +default reside on ``tag/{tag_name}{number}.html``. =================== =================================================== Variable Description @@ -261,12 +271,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 @@ -281,8 +292,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 ===== @@ -314,7 +326,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