Index
- NAME
- DESCRIPTION
- OPTIONS
- Pragmas
- Configuration Hashref
- Enabling Plugins
- Blog Configuration
- Automatically Clean The Output Directory
- Default Formatter Options
- Copy Static Files To The Output Directory
- Default Renderer Options
- Default Writer Options
- Custom Options
- End Of The Configuration Hashref
- AUTHOR
- COPYRIGHT AND LICENSE
NAME 
config.pl - Example configuration file for Newcomen.
DESCRIPTION
The example project this configuration belongs to is part of the Newcomen distribution. The project may be used as a starting point to create a simple blog page. It is located in the intro folder of the distribution.
This configuration file is suitable for use with the Newcomen::Config::Perl configuration backend (currently the only existing configuration backend).
In this documentation, nested data structures may be referenced by paths. For example, given the following hashref:
{
'foo' => {
'bar' => 'something',
},
}the value of foo/bar is 'something'. The paths used may be relative to the root of the
configuration hashref or relative to some sub-hashref, this will be mentioned in the specific
sections of this documentation.
OPTIONS
The following is a description of the options used in the example configuration file distributed with Newcomen. It contains basic information about the settings used, for more detailed information please follow the links to the plugin documentation.
Pragmas
use utf8;
Usually no pragmas are required. However, if your configuration file contains UTF-8 characters, the utf8 pragma has to be enabled. It is included by default, though the default configuration only contains plain ASCII text.
Configuration Hashref
This configuration file has to return a hashref (see Newcomen::Config::Perl). All the following
options are included in one single hashref, and this hashref has to be the last statement in the
file, so it will be returned when the file is processed (no explicit return is necessary). The
following opening brace starts the hashref:
{The hashref contains all the following options until the closing brace.
Note: It is probably easier to see the actual nesting/structure of the options in the actual configuration file.
Enabling Plugins
'plugins' => {
'Blog' => 1,
'CleanDirectories' => 1,
'Rewrite::Clean' => 1,
'Static' => 1,
'Newcomen' => 1,
},Every plugin has to be enabled if it should be used for processing a project, see Newcomen::Manual::Configuration. The example configuration enables the plugins Newcomen::Plugin::Blog (which in turn enables all the other blog plugins), Newcomen::Plugin::CleanDirectories, Newcomen::Plugin::Rewrite::Clean, Newcomen::Plugin::Static and Newcomen::Plugin::Newcomen.
To enable a plugin, specify its basename (i.e. the module name without the 'Newcomen::Plugin::'
prefix) as the key in the plugins hashref. Every true value will enable it, every false value
will disable it (this is the default).
Note: Do not disable the Newcomen::Plugin::Newcomen plugin!
Blog Configuration
The configuration of all the different blog plugins is specified in the blog hashref. Usually, the plugin name matches the child hashref, e.g. the configuration for the crawler plugin (Newcomen::Plugin::Blog::Crawler) is set in the hashref blog/crawler.
The following starts the blog options:
'blog' => {From now on, all options are relative to blog, unless mentioned otherwise, until the blog section is closed.
Crawler Options
'crawler' => {
'dirs' => 'articles',
'match' => '\.(?:txt|mmd)$',
},These are options for the Newcomen::Plugin::Blog::Crawler plugin. By default, the crawler will
search for article sources in the directory articles (specified relative to the project's root
directory). All files with the extension '.txt' and '.mmd' will be treated as article source
files.
Note: A description of the source file format can be found in the documentation of the parse_file() function of Newcomen::Util::File.
Backend Defaults
'defaults' => {
'renderer' => 'TemplateToolkit',
'writer' => 'Rendered',
},These options are used by the Newcomen::Plugin::Blog::Defaults plugin to set default backends for the pages. By default, Newcomen::Renderer::TemplateToolkit will be used to render a page, and Newcomen::Writer::Rendered will be used to write a page to disk. No backend options are set, so the default options will be used, some defaults are set below. Also check the documentation of the backends for additional information.
Article Excerpts
'excerpt' => {
'excerpt' => ['<!--excerpt-->', '<!--/excerpt-->'],
},Used by the Newcomen::Plugin::Blog::Excerpt plugin. Keys in this hashref define the name of the excerpt's key in the source's meta data. The values are arrayrefs: the first element specifies the start of the excerpt text in the article source, the second element the end of the excerpt.
In the example, all text between the two strings '<!--excerpt-->' and
'<!--/excerpt-->' will be available in the source's meta data under the key excerpt.
Note: For content formatted with the Newcomen::Formatter::MultiMarkdown formatter, the stop marker should be put in its own paragraph if it is used without a start marker. The excerpt will be extracted after the formatting, this may result in unclosed and/or unopened tags in the excerpt.
Formatters
'formatters' => {
'\.mmd$' => ['MultiMarkdown', 'RelativePaths'],
'\.txt$' => [ 'RelativePaths'],
},The Newcomen::Plugin::Blog::Formatters plugin assigns formatter backends to source file content based on the configuration in this hashref. The keys in the hashref will be used in a regular expression. If it matches a source file's name, the formatter backend (or backends) specified by the value in the hashref will be used for the source.
In the example, all articles in files with the '.mmd' extension will be formatted by the
Newcomen::Formatter::MultiMarkdown formatter backend first, and after that by the
Newcomen::Formatter::RelativePaths formatter (allowing you to reference other pages by a relative
path in article sources). The latter will also be applied to all files with the '.txt' extension
(see above for the crawler configuration).
Note: All regular expressions will be checked for a given piece of content. If more than one matches, all specified formatters will be applied! Make sure the regular expressions are as specific as possible if this is not intended. If multiple formatters should be used, note that the order in which they are applied is determined by sorting the regular expressions (using Perl's standard sort() function).
Single Article Pages
'single' => {
'url' => '<categories/0>/<slug>.html',
'page_info' => {
'title' => '<title>',
},
},These options are used by the Newcomen::Plugin::Blog::Single plugin. The url setting is mandatory, if this is empty, no single article pages will be created. In the example configuration, single article pages will be placed in a directory named after the article's first category (this may be empty if none is specified), the file name will be the article slug (see Newcomen::Plugin::Blog::Source::Slug). Please see the Newcomen::Plugin::Blog::Single documentation for available placeholders.
The page_info hashref contains arbitrary data to be included in the page's meta data. By default, the title option is defined, which will add the meta data info_title to the single article pages, and its value will be set to the title found in the sources' meta data. The same placeholders as for the url option may be used.
Article Sources
'source' => {
'filename_meta' => 'articles/(?:(?<category>.*)?/)?(?:\d+-)?(?<slug>.*)\.(?:txt|mmd)$',
'lists' => {
'category' => 'categories',
'tag' => 'tags',
},
'time' => {
'input_format' => '%Y-%m-%d %H:%M',
'output_format' => '%Y-%m-%d %H:%M',
},
},The Newcomen::Plugin::Blog::Source plugin uses the filename_meta option to add meta data to
the article sources based on the file names. Perl's named capture groups are used for this, please
see perlre. The example configuration creates category meta data based on the directory, and
the slug will be set based on the file name. The file name may start with digits followed by a
hyphen, this prefix will be ignored. The extension will also be ignored. Note that the extension is
included in the regular expression, if you change the crawler settings, you will
also need to modify the filename_meta option accordingly. Also included is the article source
directory ('articles/'), also set in the crawler settings.
source/lists will be used by the Newcomen::Plugin::Blog::Source::Lists plugin to create lists in the sources' meta data. In the example, the meta data category and tag will be used to create the lists categories and tags, respectively. To create the lists, the original data will simply be split on commas (spaces around commas are allowed). These lists are required to create the category and tag index pages (see below).
The hashref source/time contains options used by Newcomen::Plugin::Blog::Source::Time to parse the published and modified meta data if available for an article (i.e. included in the article source). The input_format option will be used for parsing, the output_format option will be used to reformat the parsed time. See the plugin's documentation for more details.
Menu Configuration
'menu' => {
'000_Index' => {
'url' => 'index.html',
'text' => 'Blog Index',
},
},Defines a menu entry for the blog's start page. See Newcomen::Plugin::Blog::Menu for more details on defining menus.
Index Pages
'index' => {The options for all the index plugins are included in the index hashref. The following options are relative to this hashref.
Excluding Articles
'exclude' => {
'on_index' => '^no$',
},The Newcomen::Plugin::Blog::Index::Exclude plugin may be used to remove articles from all
index pages, based on arbitrary meta data. In the example configuration, all articles with the meta
data on_index set to 'no' will not be listed on any index page.
The Main Index
'main' => {
'exclude' => {
'on_main' => '^no$',
},
'page_info' => {
'title' => 'Blog index, page <page> of <pages>',
},
'index' => {
'url' => 'index.html',
},
'pages' => {
'url' => 'page-<page>/index.html',
}
},The blog's main index is created by the Newcomen::Plugin::Blog::Index::Main plugin based on these
options. main/page_info works like the page_info option of the single article pages, see
above (and check the Newcomen::Plugin::Blog::Index::Main documentation
for available placeholders). main/index includes settings for the first index page, main/pages
for all subsequent pages. In the example, only the URLs for the index pages are set. The
Newcomen::Plugin::Blog::Index::Main::Exclude plugin will be used to remove all posts with the
meta data on_main set to 'no' from the main index page (this does not affect the list index
pages, e.g. the category and date listings).
Categories, Tags And Archive Pages
'lists' => {
'categories' => {
'page_info' => {
'title' => 'Category: <list_item>, page <page> of <pages>',
},
'index' => {
'url' => '<list_path>/index.html',
},
'pages' => {
'url' => '<list_path>/page-<page>/index.html',
},
},
'tags' => {
'hierarchical' => 0,
'page_info' => {
'title' => 'Tag: <list_item>, page <page> of <pages>',
},
'index' => {
'url' => 'tag/<list_path>/index.html',
},
'pages' => {
'url' => 'tag/<list_path>/page-<page>/index.html',
},
},
'archive' => {
'source_list' => 'time/lists/day',
'page_info' => {
'title' => 'Archive: <ymd>, page <page> of <pages>',
},
'index' => {
'url' => 'archive/<ymd>/index.html',
},
'pages' => {
'url' => 'archive/<ymd>/page-<page>/index.html',
},
},
},These example options will result in index pages for categories, tags, and daily/monthly/yearly archives. The pages will be created by the Newcomen::Plugin::Blog::Index::Lists plugin. The options are similar to the options for the main index page (see above). For index pages to be created, every article source must include appropriate meta data. In the example, the meta data categories, tags and time/lists/day will be used, determined by the key names in the hashref (for lists/categories and lists/tags), unless overridden by a source_list option (in lists/archive). This meta data must be a list (arrayref), or the article will not be included. The blog/source/lists example options (see above) will cause these lists for the categories and tags to be created automatically from category and tag meta data. The time/lists/day list will be created by the Newcomen::Plugin::Blog::Index::Lists::Date plugin automatically. Please see the documentation of the different plugins for more details and additional options.
End Of The Index Configuration
},
This closing brace marks the end of the blog/index hashref.
Atom Feeds
'feed' => {The options for all the feed plugins are included in the feed hashref. The following options are relative to this hashref.
Feed Defaults
'defaults' => {
'uuid_ns' => 'ac1522b0-4fbb-4712-a73f-b558e5c27334',
'feed_info' => {
'author' => 'Some Author',
'base' => 'http://example.com/',
},
'renderer' => {
'name' => 'TemplateToolkit',
'options' => {
'template' => 'atom.tt',
},
},
},These are some default options used by feed plugins. The renderer setting will be used by the Newcomen::Plugin::Blog::Feed::Defaults plugin to set the renderer options for feed pages. The template atom.tt will be used to render the pages. For more options see the Template Toolkit specific renderer defaults below.
The uuid_ns options is used by several feed plugins to create a unique UUID when required. Important: Please change this setting to a unique value for your project before publishing any feeds, do not use the example value! This has to be a valid UUID.
The feed_info hashref contains additional meta data to be included on the feed pages. In the example an author name and the base URL of the feed are defined. Check the atom.tt template to see how these values are used in the template.
Note: feed_info/base is used in the example template as xml:base value. Links in the
generated feed will probably not work until you set this to the proper value for your website!
Exclude Articles From Feeds
'exclude' => {
'on_feed' => '^no$',
},The Newcomen::Plugin::Blog::Feed::Exclude plugin may be used to remove articles from all
feeds, based on arbitrary meta data. In the example configuration, all articles with the meta
data on_feed set to 'no' will not be included in the generated feeds.
The Main Feed
'main' => {
'url' => 'index.atom',
'feed_info' => {
'title' => "The blog's main feed.",
},
},Setting for the main feed, i.e. the feed that belongs to the main index page. This feed will be created by the plugin Newcomen::Plugin::Blog::Feed::Main. In the example, the feed's URL will be set to index.atom, and a title will be set to be used in the templates. The feed_info option works like the page_info options for index pages, see above.
Category And Tag Feeds
'lists' => {
'categories' => {
'url' => '<list_path>/index.atom',
'feed_info' => {
'title' => 'The feed for category <list_item>',
},
},
'tags' => {
'url' => 'tag/<list_path>/index.atom',
'feed_info' => {
'title' => 'The feed for tag <list_item>',
},
},
},These settings will cause the creation of Atom feeds for category and tag index pages by the plugin Newcomen::Plugin::Blog::Feed::Lists. The keys in the lists hashref must be the same keys used in the blog/index/lists hashref to create a feed for these specific index pages, see above. Again, the feed_info option works like the page_info options for index pages, see above. Only the feeds' URLs and titles are set in the example.
End Of The Feed Configuration
},
This closing brace marks the end of the blog/feed hashref.
End Of The Blog Configuration
},
This closing brace marks the end of the blog hashref, all stuff that follows is again at the top level of the main configuration hashref.
Automatically Clean The Output Directory
'cleandirectories' => {
'dirs' => 'output',
'verbose' => 0,
},The Newcomen::Plugin::CleanDirectories plugin may be used to automatically empty one or more directories before the build process. In the example, the output directory (specified relative to the project's root directory, also check the writer options) will be emptied. The verbose setting is disabled in the example, since it would interfere with the -m command line option of the newcomen script. If you don't use this (or even if you use it and don't care), you may enable it.
Warning: All contents of the specified directory will be deleted!
Default Formatter Options
'formatter' => {
'use_cache' => 1,
},Formatter default options may be specified in the formatter hashref. The only option set in the example is use_cache. This is not an option for a specific formatter backend, it only tells the formatter frontend (see Newcomen::Formatter) to use caching for formatter results. This is the default behaviour. It is included in the example so it can easily be changed in case it causes any problems.
Copy Static Files To The Output Directory
'static' => {
'match' => '.',
'dirs' => 'static',
},The Newcomen::Plugin::Static plugin prepares static files from one or more directories to be copied to the output directory. The dirs option in the example sets the source directory to the static directory (relative to the project's root directory). The match option will be used in a regular expression. Every matching file will be included. In the example configuration, all files will be included.
Default Renderer Options
'renderer' => {
'templatetoolkit' => {
'template' => 'default.tt',
'COMPILE_DIR' => 'cache/tt',
'COMPILE_EXT' => '.ctt',
'ENCODING' => 'utf8',
'INCLUDE_PATH' => 'templates',
'RECURSION' => 1,
},
},Renderer options are set in the renderer hashref. Currently, only one renderer backend is available: Newcomen::Renderer::TemplateToolkit, with its options specified in the renderer/templatetoolkit hashref. Most of the options are Template Toolkit options, with the exception of the template option. In the example configuration, the template directory is set to templates, and templates will be cached in the directory cache/tt (all paths are relative to the project's root directory). The template to be used by default is default.tt. It has to be UTF-8 encoded. In the example project recursive processing of the templates is allowed since this is required for the nested menu structure to be rendered.
Default Writer Options
'writer' => {
'output_dir' => 'output',
},Options for the writer backends may be included in this hashref. Every backend may support different options, please see individual backends for details if required. In the example, only the output_dir option is set. This specifies the directory to which all output files will be written, relative to the project's root directory. All writer backends currently available will respect this option.
Custom Options
'custom' => {
'title' => 'An example blog',
'subtitle' => '...powered by Newcomen',
},These options are not used by any plugin. You may rename custom to anything you like, or even include options at the top level of the configuration hashref, as long as these options do not clash with plugin options (it's probably the best to keep them in custom). You can access every option in the templates, so things like a site's title and subtitle may be declared here (as in the example) to allow these to be changed easily without touching the template itself.
End Of The Configuration Hashref
};
That's all, folks!
AUTHOR
Stefan Goebel - newcomen {at} subtype {dot} de
COPYRIGHT AND LICENSE
Copyright 2013-2014 Stefan Goebel.
This file is part of Newcomen.
Newcomen is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the license, or (at your option) any later version.
Newcomen is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with Newcomen. If not, see <http://www.gnu.org/licenses/>.