Mercurial > piecrust2
changeset 1057:fd95fef51705
docs: Update documentation on sources and pipelines.
line wrap: on
line diff
--- a/docs/docs/02_general/04_how-it-works.md Wed Jan 31 20:56:02 2018 -0800 +++ b/docs/docs/02_general/04_how-it-works.md Thu Feb 01 22:03:33 2018 -0800 @@ -6,152 +6,34 @@ principles that you can learn in a minute. -## Page rendering +## Content sources -PieCrust loads pages from [page sources][src], which are most of the time a -sub-directory of your website's root directory, with a bunch of text files in -them. For an [out-of-the-box PieCrust website][def], these are the `pages/` and -`posts/` directories, which contain pages and blog posts respectively. - -Each page or post goes through the same process: - -1. Templating -2. Formatting -3. Layout rendering +A PieCrust website is made of _content sources_, which are what tells PieCrust +where to find content, and how to read it. -The first two steps render the page's contents, which can be split into [content -segments][seg]. Most of the time, a page will only have one content segment, -appropriately called `content`. The third step optionally inserts these contents -into a re-usable piece of markup. - -Let's assume you have this in `pages/recipes.md`: +In most cases, a content source will read content from more-or-less organized +files on disk. Sometimes, that content will be media files (images and +animations), or some kind of code (Javascript or CSS related), but most of the +time this will be the text you want to publish. As a result, in this +documentation, we mostly talk about "page sources" as opposed to the more +generic "content sources". - --- - title: All Recipes - layout: simple - --- - This page lists all the recipes written so far in {{site.title}}: - - {%raw%} - {% for p in family.children %} - * [{{p.title}}]({{p.url}}) - {% endfor %} - {%endraw%} +You can read more on [content sources here][src]. -### Templating - -Each segment first goes through [templating][tpl]. Various pieces of data will -be exposed to the template engine for you to use in your page -- the page's -configuration settings, the website's configuration settings, utilities to -create paginated content, access points to all pages or blog posts, etc. - -The default template engine is [Jinja][]. - -If the `site/title` setting was set to "_Ludovic's Blog_" in the `config.yml` -file, and there are a couple of recipe pages inside `pages/recipes/`, the -`recipes.md` page will come out of the templating phase like this: - - This page lists all the recipes written so far in Ludovic's Blog: - - * [Rhubarb Pie](/recipes/rhubarb-pie) - * [Pound Cake](/recipes/pound-cake) - -### Formatting - -Next, the result goes through a [formatter][fmt], which will convert the -intermediate text into the final text. - -The default formatter is [Markdown][]. So our page becomes: - -```html -<p>This page lists all the recipes written so far in Ludovic’s Blog:</p> -<ul> -<li><a href="/recipes/rhubarb-pie">Rhubarb Pie</a></li> -<li><a href="/recipes/pound-cake">Pound Cake</a></li> -</ul> -``` - - -### Layout rendering - -Last, the page's templated and formatted contents are put inside a _layout_ -(unless the page's `layout` configuration setting is set to `none`). Since our -example page is using the `simple` layout, and if we assume the file -`templates/simple.html` looks like this: +## Content pipelines -```htmldjango -{%raw%} -<html> -<head><title>{{page.title}}</title></head> -<body> -{{content|safe}} -</body> -</html> -{%endraw%} -``` - -...then our final page will be: - -```html -<html> -<head><title>All Recipes</title></head> -<body> -<p>This page lists all the recipes written so far in Ludovic’s Blog:</p> -<ul> -<li><a href="/recipes/rhubarb-pie">Rhubarb Pie</a></li> -<li><a href="/recipes/pound-cake">Pound Cake</a></li> -</ul> -</body> -</html> -``` - -Of course, we glossed over a lot of things here, which you will want to learn -about: +Once PieCrust knows about your content, it needs to be able to bake it into +static files, or to serve it to a browser. That's what _content pipelines_ are +for: they know how to process raw source content, and convert it into whatever +the output format is supposed to be. -* [Site configuration settings][siteconf]. -* [Page configuration settings][pageconf]. -* [Templating][tpl], and [Jinja's syntax][jinja]. -* [Formatting][fmt], with [Markdown][] or [Textile][]. - - -## Asset pipeline - -PieCrust comes with a very capable built-in asset pipeline to process your CSS -and Javscript files, images, etc. It works very well for common use-cases, since -it doesn't require any kind of configuration -- unlike other more powerful -systems like [Grunt][] or [Gulp][]. +In some cases, the output format is a web-related format like HTML, RSS/Atom, +Javascript, or CSS. In other cases, it might be JPEG, PDF, or anything, really. -The PieCrust asset pipeline matches files to *processors*, in a recursive way -- -which means the _outputs_ of a given processor are then potentially re-processed -by others processors. - -For instance, if you have a [Less CSS file][less], it will be processed like so: - - foo.less -> foo.css -> foo.min.css - -Any LessCSS file (_i.e._ a file with the `.less` extension) will be compiled with -the LessCSS processor, which outputs a CSS file. This then gets picked up by -the CleanCSS processor, which will generate a compressed CSS file. - -If you want more information about what processors are mapped to what file -types, you can check the list of [built-in processors][procs]. There's also more -information available about the [asset pipeline][pipe]. +You can read more on [content pipelines here][ppl], especially the two main +pipelines in PieCrust, the page and asset pipelines. [src]: {{docurl('content-model/sources')}} -[def]: {{docurl('content-model/default-model')}} -[seg]: {{docurl('content/content-segments')}} -[tpl]: {{docurl('content/templating')}} -[fmt]: {{docurl('content/formatters')}} -[pipe]: {{docurl('asset-pipeline')}} -[procs]: {{docurl('reference/asset-processors')}} -[siteconf]: {{docurl('general/website-configuration')}} -[pageconf]: {{docurl('content/page-configuration')}} -[jinja]: http://jinja.pocoo.org/docs/dev/templates/ -[markdown]: https://en.wikipedia.org/wiki/Markdown -[textile]: https://en.wikipedia.org/wiki/Textile_(markup_language) -[grunt]: http://gruntjs.com/ -[gulp]: http://gulpjs.com/ -[less]: http://lesscss.org/ - +[ppl]: {{docurl('content-model/pipelines')}}
--- a/docs/docs/03_content/03_formatters.md Wed Jan 31 20:56:02 2018 -0800 +++ b/docs/docs/03_content/03_formatters.md Thu Feb 01 22:03:33 2018 -0800 @@ -21,6 +21,8 @@ Otherwise, the `site/default_format` setting in the site configuration will be used, and that's Markdown by default. +For a list of valid formatter names, see the [formatters reference][fmtref]. + [how]: {{docurl('general/how-it-works')}} @@ -28,4 +30,5 @@ [siteconf]: {{docurl('general/website-configuration')}} [markdown]: https://en.wikipedia.org/wiki/Markdown [textile]: https://en.wikipedia.org/wiki/Textile_(markup_language) +[fmtref]: {{docurl('reference/formatters')}}
--- a/docs/docs/03_content/04_templating.md Wed Jan 31 20:56:02 2018 -0800 +++ b/docs/docs/03_content/04_templating.md Thu Feb 01 22:03:33 2018 -0800 @@ -7,9 +7,13 @@ can execute some logic, insert reusable bits of markup, or reference other pieces of content or metadata from elsewhere in your website. -PieCrust uses [Jinja][] for templating. There's too much data exposed to it to -go over on this page, but check out the [templating data reference][dataref] for -an exhaustive list. The main pieces of data are: +PieCrust uses [Jinja][] for templating by default. See the [template engines +reference][tplengref] for a list of other template engines available by default +in PieCrust. + +There's too much data exposed to it to go over on this page, but check out the +[templating data reference][dataref] for an exhaustive list. The main pieces of +data are: * `page`: the page's configuration header. So if the page has a `title`, `page.title` would be its value. @@ -57,6 +61,7 @@ [pageconf]: {{docurl('content/page-configuration')}} [siteconf]: {{docurl('general/website-configuration')}} [dataref]: {{docurl('reference/templating-data')}} +[tplengref]: {{docurl('reference/template-engines')}} [assets]: {{docurl('content/assets')}} [jinja]: http://jinja.pocoo.org/docs/dev/templates/
--- a/docs/docs/03_content/05_content-segments.md Wed Jan 31 20:56:02 2018 -0800 +++ b/docs/docs/03_content/05_content-segments.md Thu Feb 01 22:03:33 2018 -0800 @@ -39,8 +39,8 @@ ---sidebar--- Sidebar goes here -You can then use, the page's layout, both the `content` and `sidebar` segments -to put each piece of text in its appropriate place. +You can then use, in the page's layout, both the `content` and `sidebar` +segments to put each piece of text in its appropriate place. You can also specify a [formatter][] for a given segment, by adding `:formatter` after the segment's name. For instance, to disable formatting for the `sidebar` @@ -54,7 +54,7 @@ ---sidebar:none--- <aside> - Sidebar goes here + <p>Sidebar goes here</p> </aside>
--- a/docs/docs/03_content/09_filtering.md Wed Jan 31 20:56:02 2018 -0800 +++ b/docs/docs/03_content/09_filtering.md Thu Feb 01 22:03:33 2018 -0800 @@ -1,5 +1,6 @@ --- title: Filtering +needs_pygments: true --- The PieCrust filtering syntax can be used to select items returned by an
--- a/docs/docs/04_content-model.md Wed Jan 31 20:56:02 2018 -0800 +++ b/docs/docs/04_content-model.md Thu Feb 01 22:03:33 2018 -0800 @@ -11,28 +11,27 @@ simple blog site where you can have pages and posts. To create more complex or customized websites, you can define another content -model by specifying [sources][], [routes][], and [generators][] in the [site +model by specifying [sources][] and [routes][] in the [site configuration][siteconf]: * [Sources][] are how you tell PieCrust where to find your content. It defines what sub-directories contain what kind of pages, with what kind of naming - convention, and what kind of metadata. In theory, sources can also provide - pages from other places than the file-system -- like a network connection or - a ZIP file or a database or whatever. + convention, and what kind of metadata. + + In theory, sources can also provide pages from other places than the + file-system -- like a network connection or a ZIP file or a database or + whatever. + + Some sources _generate_ content on the fly, like the a source that lists all + the tags or categories used by your blog posts. * [Routes][] define how the content returned by the sources is exposed to your visitors. This defines both the URLs for that content, and the place on disk where it will be baked to. -* [Generators][] define special types of sources which can procedurally generate - pages based on other content. A common type of generator is a "taxonomy" - generator, for things like "tags" or "categories". Based on how you've tagged - your blog posts, a generator would generate one page for each unique tag. - [def]: {{docurl('content-model/default-model')}} [sources]: {{docurl('content-model/sources')}} [routes]: {{docurl('content-model/routes')}} -[generators]: {{docurl('content-model/generators')}} [siteconf]: {{docurl('general/website-configuration')}}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/docs/04_content-model/02_pipelines.md Thu Feb 01 22:03:33 2018 -0800 @@ -0,0 +1,162 @@ +--- +title: Pipelines +--- + +Content pipelines are what PieCrust uses to actually process articles and assets +and other pieces of content into a static website, or whatever else if the +desired output. + +The two main pipelines that come with PieCrust are the "page" pipeline and the +"asset" pipeline. + + +## Page pipeline + +PieCrust loads pages from [page sources][src], which are most of the time a +sub-directory of your website's root directory, with a bunch of text files in +them. For an [out-of-the-box PieCrust website][def], these are the `pages/` and +`posts/` directories, which contain pages and blog posts respectively. + +Each page or post goes through the following process: + +1. Templating +2. Formatting +3. Layout rendering + +The first two steps render the page's contents, which can be split into [content +segments][seg]. Most of the time, a page will only have one content segment, +appropriately called `content`. The third step optionally inserts these contents +into a re-usable piece of markup. + +Let's assume you have this in `pages/recipes.md`: + + --- + title: All Recipes + layout: simple + --- + This page lists all the recipes written so far in {{site.title}}: + + {%raw%} + {% for p in family.children %} + * [{{p.title}}]({{p.url}}) + {% endfor %} + {%endraw%} + + +### Templating + +Each segment first goes through [templating][tpl]. Various pieces of data will +be exposed to the template engine for you to use in your page -- the page's +configuration settings, the website's configuration settings, utilities to +create paginated content, access points to all pages or blog posts, etc. + +The default template engine is [Jinja][]. + +If the `site/title` setting was set to "_Ludovic's Blog_" in the `config.yml` +file, and there are a couple of recipe pages inside `pages/recipes/`, the +`recipes.md` page will come out of the templating phase like this: + + This page lists all the recipes written so far in Ludovic's Blog: + + * [Rhubarb Pie](/recipes/rhubarb-pie) + * [Pound Cake](/recipes/pound-cake) + +### Formatting + +Next, the result goes through a [formatter][fmt], which will convert the +intermediate text into the final text. + +The default formatter is [Markdown][]. So our page becomes: + +```html +<p>This page lists all the recipes written so far in Ludovic’s Blog:</p> +<ul> +<li><a href="/recipes/rhubarb-pie">Rhubarb Pie</a></li> +<li><a href="/recipes/pound-cake">Pound Cake</a></li> +</ul> +``` + + +### Layout rendering + +Last, the page's templated and formatted contents are put inside a _layout_ +(unless the page's `layout` configuration setting is set to `none`). Since our +example page is using the `simple` layout, and if we assume the file +`templates/simple.html` looks like this: + +```htmldjango +{%raw%} +<html> +<head><title>{{page.title}}</title></head> +<body> +{{content|safe}} +</body> +</html> +{%endraw%} +``` + +...then our final page will be: + +```html +<html> +<head><title>All Recipes</title></head> +<body> +<p>This page lists all the recipes written so far in Ludovic’s Blog:</p> +<ul> +<li><a href="/recipes/rhubarb-pie">Rhubarb Pie</a></li> +<li><a href="/recipes/pound-cake">Pound Cake</a></li> +</ul> +</body> +</html> +``` + +Of course, we glossed over a lot of things here, which you will want to learn +about: + +* [Site configuration settings][siteconf]. +* [Page configuration settings][pageconf]. +* [Templating][tpl], and [Jinja's syntax][jinja]. +* [Formatting][fmt], with [Markdown][] or [Textile][]. + + +## Asset pipeline + +PieCrust comes with a very capable built-in asset pipeline to process your CSS +and Javscript files, images, etc. It works very well for common use-cases, since +it doesn't require any kind of configuration -- unlike other more powerful +systems like [Grunt][] or [Gulp][]. + +The PieCrust asset pipeline matches files to *processors*, in a recursive way -- +which means the _outputs_ of a given processor are then potentially re-processed +by others processors. + +For instance, if you have a [Less CSS file][less], it will be processed like so: + + foo.less -> foo.css -> foo.min.css + +Any LessCSS file (_i.e._ a file with the `.less` extension) will be compiled with +the LessCSS processor, which outputs a CSS file. This then gets picked up by +the CleanCSS processor, which will generate a compressed CSS file. + +If you want more information about what processors are mapped to what file +types, you can check the list of [built-in processors][procs]. There's also more +information available about the [asset pipeline][pipe]. + + +[src]: {{docurl('content-model/sources')}} +[ppl]: {{docurl('content-model/pipelines')}} +[def]: {{docurl('content-model/default-model')}} +[seg]: {{docurl('content/content-segments')}} +[tpl]: {{docurl('content/templating')}} +[fmt]: {{docurl('content/formatters')}} +[pipe]: {{docurl('asset-pipeline')}} +[procs]: {{docurl('reference/asset-processors')}} +[siteconf]: {{docurl('general/website-configuration')}} +[pageconf]: {{docurl('content/page-configuration')}} +[jinja]: http://jinja.pocoo.org/docs/dev/templates/ +[markdown]: https://en.wikipedia.org/wiki/Markdown +[textile]: https://en.wikipedia.org/wiki/Textile_(markup_language) +[grunt]: http://gruntjs.com/ +[gulp]: http://gulpjs.com/ +[less]: http://lesscss.org/ +
--- a/docs/docs/04_content-model/02_routes.md Wed Jan 31 20:56:02 2018 -0800 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,73 +0,0 @@ ---- -title: Routes ---- - -_Routes_ define how your content is exposed to your visitors. This affects the -structure of your baked output, which affects the URLs of your pages. - -Routes are defined as a list of entries under `site/routes`: - - site: - routes: - - url: /foo/%slug% - source: something - - url: /bar/%year%/%month%/%slug% - source: otherthing - -Each route must define the following settings: - - * `url`: That's the pattern to use to figure out where the baked page will go. - You need to use _placeholders_ here (things of the form `%blah%`) otherwise - all your pages would have the same URL and would be overwriting each other. - - The available placeholders depend on the source or generator tied to this - route (see below). Refer to the [list of available sources][refsrc] and - [generators][refgen] to see what kind of routing information they expose. - - You'll notice that some routing parameters are *required*, while others are - *optional*. The *required* parameters *must* be used in the URL pattern. The - *optional* ones are, well, optional. - - * `source` or `generator`: This defines the source or generator that this - route is defined for. Only pages originating from the source or generator of - that name will have their bake output generated with this route. You can't - define both `source` and `generator` -- it needs to be one or the other. - -Optional settings include: - - * `page_suffix`: Pages that create _sub-pages_ (_e.g._ when using pagination) - will append this suffix to the route. By default, this is `/%num%`. You _must_ - use the `%num%` placeholder somewhere in this setting. - - * `func`: The name for a *route function* that you can use through the - [template engine][tpl]. This is what lets you get a URL when you write - {%raw%}`{{pcurl('foo/bar')}}`{%endraw%} (the function name being `pcurl` - here) to generate an URL to the `foo/bar.html` page (or something similar). - The name is up to you, but when you use it, you'll have to pass parameters - in the same order as they appear in the URL pattern. - - So for instance, if you define a route as `/blog/%year%/%slug%`, and that - route has a `func` name of `post_url`, then you would use it as such: - `post_url(2016, "some-blog-post")`. - - To know what routing parameters a given source or generator supports, see - the reference documentation for [sources][refsrc] and [generators][refgen]. - - -## Route ordering - -The order of the routes is important, because the first matching route for a -given page will be the one that's used. This is especially important when -running `chef serve`, or running PieCrust as a dynamic CMS. - -This is because the incoming URL requested by a visitor's browser will be -matched against each route starting from the first one in the list. For each -route that matches, an actual page will be looked for, and the first one to be -found will be returned for that URL. - - - -[tpl]: {{docurl('content/templating')}} -[refsrc]: {{docurl('reference/sources')}} -[refgen]: {{docurl('reference/generators')}} -
--- a/docs/docs/04_content-model/03_generators.md Wed Jan 31 20:56:02 2018 -0800 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,34 +0,0 @@ ---- -title: Generators ---- - -Generators are like [sources][], but they procedurally generate pages based on -the rest of your site's content. - -The [default content model][def] defines generators for your taxonomies (tags, -categories, or whatever else you want to classify your posts with), and one -generator for your blog archives (to generate one archive page per year). - -Generators are defined in the website configuration. For example: - -``` -site: - generators: - my_archives: - type: blog_archives - source: posts - page: 'page:_year.md' -``` - -The only required setting for a generator is the `type` setting, which specifies -what type of generator this should be. Other settings depend on the type of -generator. - -To see what generators are available in PieCrust out of the box, see the -[reference page on generators][refgen]. - - -[sources]: {{docurl('content-model/routes')}} -[refgen]: {{docurl('reference/generators')}} -[def]: {{docurl('content-model/default-model')}} -
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/docs/04_content-model/03_routes.md Thu Feb 01 22:03:33 2018 -0800 @@ -0,0 +1,72 @@ +--- +title: Routes +--- + +_Routes_ define how your content is exposed to your visitors. This affects the +structure of your baked output, which affects the URLs of your pages. + +Routes are defined as a list of entries under `site/routes`: + + site: + routes: + - url: /foo/%slug% + source: something + - url: /bar/%year%/%month%/%slug% + source: otherthing + +Each route must define the following settings: + + * `url`: That's the pattern to use to figure out where the baked page will go. + You need to use _placeholders_ here (things of the form `%blah%`) otherwise + all your pages would have the same URL and would be overwriting each other. + + The available placeholders depend on the source tied to this route (see + below). Refer to the [list of available sources][refsrc] to see what kind of + routing information they expose. + + You'll notice that some routing parameters are *required*, while others are + *optional*. The *required* parameters *must* be used in the URL pattern. The + *optional* ones are, well, optional. + + * `source`: This defines the source that this route is defined for. Only pages + originating from the source of that name will have their bake output + generated with this route. + +Optional settings include: + + * `page_suffix`: Pages that create _sub-pages_ (_e.g._ when using pagination) + will append this suffix to the route. By default, this is `/%num%`. You _must_ + use the `%num%` placeholder somewhere in this setting. + + * `func`: The name for a *route function* that you can use through the + [template engine][tpl]. This is what lets you get a URL when you write + {%raw%}`{{pcurl('foo/bar')}}`{%endraw%} (the function name being `pcurl` + here) to generate an URL to the `foo/bar.html` page (or something similar). + The name is up to you, but when you use it, you'll have to pass parameters + in the same order as they appear in the URL pattern. + + So for instance, if you define a route as `/blog/%year%/%slug%`, and that + route has a `func` name of `post_url`, then you would use it as such: + `post_url(2016, "some-blog-post")`. + + To know what routing parameters a given source supports, see the reference + documentation for [sources][refsrc]. + + +## Route ordering + +The order of the routes is important, because the first matching route for a +given page will be the one that's used. This is especially important when +running `chef serve`, or running PieCrust as a dynamic CMS. + +This is because the incoming URL requested by a visitor's browser will be +matched against each route starting from the first one in the list. For each +route that matches, an actual page will be looked for, and the first one to be +found will be returned for that URL. + + + +[tpl]: {{docurl('content/templating')}} +[refsrc]: {{docurl('reference/sources')}} +[refgen]: {{docurl('reference/generators')}} +
--- a/docs/docs/04_content-model/04_page-references.md Wed Jan 31 20:56:02 2018 -0800 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,46 +0,0 @@ ---- -title: Page References ---- - -There are a few places in PieCrust where you need to specify a reference to a -page -- like for instance when defining taxonomies and specifying a custom index -page. - -Page references are written using the following format: - - source_name:path/to/page.ext - -This means: - -* `source_name`: The source in which to find the page. - -* `path/to/page`: A _source path_ to the page. This is usually just a - file-system relative path, starting from the file-system endpoint of the - source, but some sources may have slightly different ways to specify a - relative path. Refer to the source's documentation. - -* `.ext`: The extension to use. If you want to the user to have some freedom in - the matter -- like for example letting the user use either a `.md` or - `.textile` extension to use either Markdown or Textile syntax -- then you can - use `.%ext%`. This will match any extension registered in the - `site/auto_formats` settings (see the [formatters documentation][fmt]). - - -### Multiple matches - -It's possible to define a reference that will match multiple possible pages -- -in this case, it would resolve to the first found page. Just write additional -page references, using `;` as a separator. - -For instance: - - foo:something/whatever.md;bar:someting.md - -...would match `something/whatever.md` in source `foo` if it exists, otherwise -it would match `something.md` in source `bar` if it exists. Otherwise, the page -isn't found. - -This is especially useful for falling back to a page defined in a theme. - -[fmt]: {{docurl('content/formatters')}} -
--- a/docs/docs/04_content-model/05_default-model.md Wed Jan 31 20:56:02 2018 -0800 +++ b/docs/docs/04_content-model/05_default-model.md Thu Feb 01 22:03:33 2018 -0800 @@ -12,8 +12,12 @@ ## Sources -The default sources define the strict minimum for a personal website: -"free-form" pages (`pages`) and blog posts (`posts`). +The default sources define what you would expect for a personal website: +"free-form" pages (`pages`), blog posts (`posts`), taxonomies (`tags` and +`categories`), and yearly archives. + + +### Pages First, the pages: @@ -32,6 +36,9 @@ * It defines the `item_name` so that you can prepare a new page with `chef prepare page`. + +### Blog posts + The `posts` sources is a bit more complicated: sources: @@ -59,14 +66,12 @@ `default`. -## Generators - ### Taxonomies -The default content model defines 2 taxonomies: categories and tags. Categories -are meant to be exclusive, _i.e._ a blog post can only have one category. Tags -are meant to be used more freely, where a blog post can be tagged with multiple -terms. +The default content model defines 2 taxonomies: "categories" and "tags". +Categories are meant to be exclusive, _i.e._ a blog post can only have one +category. Tags are meant to be used more freely, where a blog post can be tagged +with multiple terms. This shows up more or less like this in the website configuration: @@ -79,44 +84,38 @@ multiple: true term: tag -PieCrust then creates a `taxonomy` generator for each defined taxonomy -(including custom taxonomies you added). Each taxonomy generator will look like -this: +PieCrust then creates a `taxonomy` source for each defined taxonomy (including +custom taxonomies you added or changed in `sites/taxonomies`). Each taxonomy +source will look like this: site: - generators: - posts_FOOS: + sources: + posts_TAXONOMY: type: taxonomy - taxonomy: FOOS + taxonomy: TAXONOMY source: posts - page: "pages:_FOO.%ext%;theme_pages:_FOO.%ext%" + template: _TERM.html -In this example, `FOOS` is the name of the taxonomy (_e.g._: `tags`), and `FOO` -is the `term` value (_e.g._: `tag`). If no `term` is defined, the name of the -taxonomy is used. +In this example, `TAXONOMY` is the name of the taxonomy (_e.g._: `tags`), and +`TERM` is the `term` value (_e.g._: `tag`). If no `term` is defined, the name of +the taxonomy is used. -As you can see, the taxonomy index pages are set to `_category.*` and `_tag.*` -respectively, where the extension can be any of the auto-formats (which means -`.md`, `.textile`, and `.html` by default). They can also fall back to the same -pages defined in the current theme (whose source name is `theme_pages`), which -is what makes the default (built-in) PieCrust theme work, for instance. +As you can see, the taxonomy index layout templates are set to `_category.html` +and `_tag.html` respectively. + ### Archives -The blog archives generator is defined like this by default: +The blog archives source is defined like this by default: site: - generators: + sources: posts_archives: type: blog_archives source: posts - page: "pages:_year.%ext%;theme_pages:_year.%ext%" + template: _year.html -The index page for each year of archives is set to `_year.*`, where the -extension can be any of the auto-formats (which means `.md`, `.textile`, and -`.html` by default). It can also fall back to the same page defined in the -current theme (whose source name is `theme_pages`), which is what makes the -default (built-in) PieCrust theme work, for instance. +The index layout template for each year of archives is set to `_year.html`. ## Routes @@ -126,27 +125,27 @@ - url: /%path:slug% source: pages - func: pcurl(slug) + func: pcurl - url: /%year%/%month%/%day%/%slug% source: posts - func: pcposturl(year,month,day,slug) + func: pcposturl - url: /archives/%year% - generator: posts_archives - func: pcyearurl(year) + source: posts_archives + func: pcyearurl - url: /tag/%tag% - generator: posts_tags - func: pctagurl(tag) + source: posts_tags + func: pctagurl - url: /category/%category% - generator: posts_categories - func: pccaturl(category) + source: posts_categories + func: pccaturl - url: /%path:slug% source: theme_pages - func: pcurl(slug) + func: pcurl Let's go through it: @@ -160,9 +159,9 @@ more than one blog in `site/blogs`, there will be more than one route for posts, and the route will be rooted with `/<blogname>`. -* The next route is for the blog archives generator. +* The next route is for the blog archives source. -* There are then routes for the taxonomy generators. By default, there are +* There are then routes for the taxonomy sources. By default, there are 2 taxonomies (tags and categories) so that's 2 routes. * All routes define some URL functions for use in your pages and templates
--- a/docs/docs/99_reference/01_website-configuration.md Wed Jan 31 20:56:02 2018 -0800 +++ b/docs/docs/99_reference/01_website-configuration.md Thu Feb 01 22:03:33 2018 -0800 @@ -16,6 +16,16 @@ that maps an extension to a format name. This makes it possible to use certain file extensions for pages, like `.md` for Markdown content or `.textile` for Textile content. + + Defaults to: + + ``` + auto_formats: + md: markdown + textile: textile + ``` + + See the [formatters reference][fmtref] for a list of valid formatter names. * `blogs` (`['blog']`): When using the default content model, the list of blogs for which to create posts sources. @@ -42,6 +52,8 @@ using the default content model. * `default_template_engine` (`jinja`): Specifies what template engine to use. + See the [template engines reference][tplengref] for a list of valid engine + names. * `enable_debug_info` (`true`): If you’re using PieCrust in dynamic CMS mode, visitors could use the debugging features to expose potentially private @@ -120,6 +132,8 @@ [fmt]: {{docurl('content/formatters')}} [cm]: {{docurl('content-model')}} +[fmtref]: {{docurl('reference/formatters')}} +[tplengref]: {{docurl('reference/template-engines')}} ## Preparation @@ -146,19 +160,6 @@ The following settings are under the `baker` section, and are used by the `chef bake` command: -* `assets_dirs` (`assets`): The name(s) of the directory(ies) on which to run - the built-in asset pipeline. - -* `force` (`[]`): Patterns to use for always forcing re-processing of some - assets with the built-in asset pipeline. - -* `ignore` (`[]`): Patterns to use for ignoring certain assets with the built-in - asset pipeline. Patterns are either glob-like (_i.e._ using wildcards) or - regex-like (when the pattern starts and ends with a slash). - - Some patterns will always be added to the list: `_cache`, `_counter`, - `theme_info.yml`, `.DS_Store`, `Thumbs.db`, `.git*`, `.hg*`, and `.svn`. - * `is_baking` (`false`): This setting is read-only, and will be set to true while baking the website (_i.e._ while the `chef bake` command is running). This is useful for generating things only when baking the website for @@ -179,99 +180,48 @@ only for preview purposes. -## Template engines - -### Jinja - -Settings for the Jinja template engine are under the `jinja` section: - -* `auto_escape` (`true`): Turns on auto-escaping of text for safer HTML output. - - -## Formatters - -### Markdown - -Settings for the Markdown formatter are under the `markdown` section: - -* `extensions` (`[]`): The list of [Markdown extensions][mdext] to enable. - -[mdext]: https://pythonhosted.org/Markdown/extensions/index.html +## Administration panel - -### Smartypants - -Settings for the Smartypants formatter are under the `smartypants` section: - -* `enable` (`false`): Enables Smartypants on any formatter that outputs HTML. - - -## Asset processors +The following settings are under `admin` and are used by the `chef serve +--admin` command, along with the administration panel that runs if you set that +up on your server. -### CleanCSS - -Settings for the CleanCSS processor are under the `cleancss` section: - -* `bin` (`cleancss`): The path to the CleanCSS executable. By default, PieCrust - assumes it will be in your `PATH` environment variable. - -* `options` (`--skip-rebase`): Custom options and arguments to pass to the - CleanCSS executable. +_Nothing yet._ -### Compass +## Micropub endpoint -Settings for the Compass processor are under the `compass` section: +The following settings are under the `micropub` section, and are used when the +Micropub endpoint is running on your server. -* `bin` (`compass`): The path to the Compass executable. By default, PieCrust - assumes it will be in your `PATH` environment variable. +* `source`: The source to create new content in when submitting new posts via + the Micropub endpoint. Defaults to `posts`. -* `config_path` (`config.rb`): The path to the Compass project's configuration - file, relative to the PieCrust website's root directory. +* `resize_photos`: The thumbnail size (in pixels) to use when receiving pictures + via the Micropub endpoint. If set to more than 0, it will create a resized + copy of the photo, with a `_thumb` suffix, and save it as a JPEG file. + Defaults to 800. -* `enable` (`false`): Enables Compass processing for this website. This means - that the standalone Scss/Sass processor will be disabled and replaced by the - Compass processor. +* `microblogging`: A dictionary that represents a page configuration that will + be used when a microblogging post is submitted via the Micropub endpoint. + A post is considered as "microblogging" if it doesn't have a title. The + typical use-case for this is to automatically set a tag or category on the + post, so that it can be displayed differently. -* `frameworks` (empty): A list of Compass frameworks to enable for this website, - either as a YAML list, or just comma-separated. +* `autocommit`: If `true`, submitted posts will be automatically committed to + source control (if available). Currently, Mercurial and Git are supported. See + also the "Source Control" section below. Defaults to `false`. -* `options` (empty): Custom options and arguments to pass to the Compass - executable. +* `publish_target`: The publish target to run when submitting new posts via the + Micropub endpoint. -### LessC - -Settings for the Less CSS processor are under the `less` section: - -* `bin` (`lessc`): The path to the Less compiler. By default, PieCrust assumes - it will be in your `PATH` environment variable. +## Source control -* `options` (`--compress`): Custom options and arguments to pass to the Less - compiler. - - -### Sass - -Settings for the Scss/Sass CSS processor are under the `sass` section: - -* `bin` (`scss`): The path to the Sass compiler. By default, PieCrust assumes it - will be in your `PATH` environment variable. +The following settings are under `scm`. They used by the Micropub endpoint and +the administration panel (see above). -* `load_paths` (empty): A list of include paths to pass to the Sass compiler. - -* `style` (`nested`): The output CSS style to use. - -* `options` (empty): Custom options and arguments to pass to the Sass compiler. - - -### UglifyJS +* `author`: The author name to use when submitting new posts or pages via the + administration panel. It's generally of the form `FirstName LastName + <email@example.org>`. -Settings for the UglifyJS processor are under the `uglifyjs` section: - -* `bin` (`uglifyjs`): The path to the UglifyJS executable. By default, PieCrust - assumes it will be in your `PATH` environment variable. - -* `options` (`--compress`): Custom options and arguments to pass to the UglifyJS - executable. -
--- a/docs/docs/99_reference/02_page-configuration.md Wed Jan 31 20:56:02 2018 -0800 +++ b/docs/docs/99_reference/02_page-configuration.md Thu Feb 01 22:03:33 2018 -0800 @@ -23,7 +23,8 @@ sources, already set the date using the page's filename. * `format`: Specifies what formatter to use to render this page. Defaults to - `site/default_format`, which defaults to Markdown. + `site/default_format`, which defaults to Markdown. For a list of valid + formatter names, see the [formatters reference][fmtref]. * `items_per_page`: Defines how many items to include per page when using the `pagination` data endpoint. @@ -49,3 +50,4 @@ setting, whether it was set through the configuration header, or by the source. +[fmtref]: {{docurl('reference/formatters')}}
--- a/docs/docs/99_reference/03_sources.md Wed Jan 31 20:56:02 2018 -0800 +++ b/docs/docs/99_reference/03_sources.md Thu Feb 01 22:03:33 2018 -0800 @@ -172,3 +172,116 @@ * Required routing parameter: * `slug` + +## Taxonomy source + +A taxonomy is a way to classify content. The most common taxonomies are things +like "_tags_" or "_categories_" that you use to classify blog posts. + +The taxonomy source creates _index pages_ that list all the content in every +_taxonomy term_ in use. + +A common example of taxonomy is the "_category_" of a blog post. If you have +blog posts in categories "_recipes_", "_kitchen tips_" and "_restaurant +reviews_", you want 3 pages to be created automatically for you so that someone +can see a list of all recipes, kitchen tips, and restaurant reviews. Those +3 pages may of course have _sub-pages_ if they're using pagination to only show +10 or so at a time. + +If you write a new blog post and put it in category "_utensil reviews_", you +want a new page listing all utensil reviews to also be created. + +The taxonomy source creates those pages (one for each category) dynamically for +you. + +* Type: `taxonomy` + +* Configuration settings: + * `taxonomy`: The name of a taxonomy, defined under `site/taxonomies`. See below + for more information. + * `source`: The name of a source from which to look for classified content. For + example, `posts` is the name of the default blog posts source. + * `template`: The name of a layout template to use for rendering each taxonomy + page. This template will be rendered with additional taxonomy data (see + below). Defaults to `_TAXONOMY.html`, where `TAXONOMY` is the taxonomy name + (as specified above in the `taxonomy` setting). + +* Required routing parameters: + * `TAXONOMY`, where `TAXONOMY` is the name of the taxonomy (as specified in + the `taxonomy` setting). + + +### Taxonomy configuration + +Taxonomies are defined under `site/taxonomies` in the website configuration: + + site: + taxonomies: + tags: + multiple: true + term: tag + +These settings should be defined as a map. Each entry is the name of the +taxonomy, and is associated with the settings for that taxonomy. Settings +include: + +* `multiple`: Defines whether a page can have more than one value assigned for + this taxonomy. Defaults to `false` (_i.e._ only a single value can be + assigned). + +* `term`: Taxonomies are usually named using plural nouns. The `term` setting + lets you define the singular form, which is used in multiple places. + +### Template data + +When the taxonomy generator renders your _index page_, it will pass it the +following layout template data: + +* `<taxonomy_name>` (the taxonomy name) will contain the term, or terms, for the + current listing. For instance, for a "_tags_" taxonomy, it will contain the + list of tags for the current listing. In 99% of cases, that list will contain + only one term, but for "_term combinations_" (i.e. listing pages tagged with + 2 or more tags), it could contain more than one. For taxonomies that don't + have the `multiple` flag, though, that template data will only be a single + term (_i.e._ a string value). + +* `pagination.items` will list the classified content, _i.e._ content from the + generator's `source`, filtered for only content with the current term. For + instance, the list of blog posts with the current tag or category or whatever. + Note that this is still pagination data, so it will create _sub-pages_. + + +## Blog archives source + +This source will generate one page per year for a given source of pages. This +is useful for generating a "blog archive" section. + +* Type: `blog_archives` + +* Configuration Settings: + * `source`: The name of a source from which to look for dated content. + * `template`: The name of a layout template to use for rendering each year + page. The template will be rendered with additional data (see below). + Defaults to `_year.html`. + +* Required routing parameters: + * `year` + + +### Template data + +When the blog archives source renders your _index page_, it will pass it the +following template data: + +* `year` is the current year. + +* `pagination.items` lists the content dated for the current year, in + reverse-chronological order. This will potentially create _sub-pages_ since + this is pagination data. + +* `archives` lists the same thing as `pagination.items`, but without paginating + anyting, _i.e._ even if you have _lots_ of blog posts in a given year, they + will all be listed on the same page, instead of being listed, say, 10 per + page, with _sub-pages_ created for the rest. Also, `archives` will list posts + in chronological order. +
--- a/docs/docs/99_reference/04_generators.md Wed Jan 31 20:56:02 2018 -0800 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,120 +0,0 @@ ---- -title: "Appendix 4: Generators Reference" -short_title: Generators Reference ---- - -Here are the generators that come with PieCrust by default. - - -## Taxonomy generator - -A taxonomy is a way to classify content. The most common taxonomies are things -like "_tags_" or "_categories_" that you use to classify blog posts. - -The taxonomy generator creates _index pages_ that list all the content in every -_taxonomy term_ in use. - -### Taxonomy example - -A common example of taxonomies is the "_category_" of a blog post. If you have -blog posts in categories "_recipes_", "_kitchen tips_" and "_restaurant -reviews_", you want 3 pages to be created automatically for you so that someone -can see a list of all recipes, kitchen tips, and restaurant reviews. Those -3 pages may of course have _sub-pages_ if they're using pagination to only show -10 or so at a time. - -If you write a new blog post and put it in category "_utensil reviews_", you -want a new page listing all utensil reviews to also be created. - -### Generator configuration - -The taxonomy generator takes the following configuration settings: - -* `type`: Needs to be `taxonomy`. - -* `taxonomy`: The name of a taxonomy, defined under `site/taxonomies`. See below - for more information. - -* `source`: The name of a source from which to look for classified content. For - example, `posts` is the name of the default blog posts source. - -* `page`: A [page reference][pageref] to an index page to use for each generated - page. This index page will be passed some template data to list the - appropriate content (more on this later). - -### Taxonomy configuration - -Taxonomies are defined under `site/taxonomies` in the website configuration: - - site: - taxonomies: - tags: - multiple: true - term: tag - -These settings should be defined as a map. Each entry is the name of the -taxonomy, and is associated with the settings for that taxonomy. Settings -include: - -* `multiple`: Defines whether a page can have more than one value assigned for - this taxonomy. Defaults to `false` (_i.e._ only a single value can be - assigned). - -* `term`: Taxonomies are usually named using plural nouns. The `term` setting - lets you define the singular form, which is used in multiple places. - -### Template data - -When the taxonomy generator renders your _index page_, it will pass it the -following template data: - -* `<taxonomy_name>` (the taxonomy name) will contain the term, or terms, for the - current listing. For instance, for a "_tags_" taxonomy, it will contain the - list of tags for the current listing. In 99% of cases, that list will contain - only one term, but for "_term combinations_" (i.e. listing pages tagged with - 2 or more tags), it could contain more than one. For taxonomies that don't - have the `multiple` flag, though, that template data will only be a single - term (_i.e._ a string value). - -* `pagination.items` will list the classified content, _i.e._ content from the - generator's `source`, filtered for only content with the current term. For - instance, the list of blog posts with the current tag or category or whatever. - Note that this is still pagination data, so it will create _sub-pages_. - - -## Blog archives - -This generator will generate one page per year for a given source of pages. This -is useful for generating yearly blog archives. - -### Generator configuration - -The blog archives generator takes the following configuration settings: - -* `type`: Needs to be `blog_archives`. - -* `source`: The name of a source from which to look for dated content. - -* `page`: A [page reference][pageref] to an index page to use for each generated - yearly archive page. - -### Template data - -When the blog archives generator renders your _index page_, it will pass it the -following template data: - -* `year` is the current year. - -* `pagination.items` lists the content dated for the current year, in - reverse-chronological order. This will potentially create _sub-pages_ since - this is pagination data. - -* `archives` lists the same thing as `pagination.items`, but without paginating - anyting, _i.e._ even if you have _lots_ of blog posts in a given year, they - will all be listed on the same page, instead of being listed, say, 10 per - page, with _sub-pages_ created for the rest. Also, `archives` will list posts - in chronological order. - - -[pageref]: {{docurl('content-model/page-references')}} -
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/docs/99_reference/04_pipelines.md Thu Feb 01 22:03:33 2018 -0800 @@ -0,0 +1,46 @@ +--- +title: "Appendix 4: Pipelines Reference" +short_title: Pipelines Reference +--- + +Here are the content pipelines that come with PieCrust by default. + + +## Page pipeline + +* Type: `page` + +* Configuration settings: + * `site/pretty_urls`: Whether to bake pages using a "pretty URL" path, _i.e._ + a path with no visible `.html` suffix. Defaults to `false`. + * `baker/no_bake_setting`: The name of a setting to look for in a page, to see + if that page should be excluded from a bake. If that setting is found, and + is `true`, then the page is ignored. Defaults to `draft`. + + +## Asset pipeline + +* Type: `asset` + +* Configuration settings: + * `site/SOURCE/processors`: Filters the asset processors to be used for + content source `SOURCE`. See below. + + +### Processor filtering + +Using the website configuration, it's possible to filter which asset processors +can be used for a given content source. + +Filtering should be done with a list of processor names or patterns. Valid +processor names can be found in the [asset processor reference page][procref]. +Also: + +* `all`: means all processors. This is useful to start with all processors and + exclude just a few. +* `PROCNAME`: include processor `PROCNAME`. +* `-PROCNAME`: exclude processor `PROCNAME`. + + +[procref]: {{docurl('reference/asset-processors')}} +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/docs/99_reference/07_template-engines.md Thu Feb 01 22:03:33 2018 -0800 @@ -0,0 +1,32 @@ +--- +title: "Appendix 7: Template Engines Reference" +short_title: Template Engines Reference +--- + +When a page gets rendered, it goes through a template engine that can expand +special syntax that runs logic. This is useful for authoring pages that list +blog posts by date or category, for instance. + +Here is a list of the template engines that come with PieCrust out of the box. + + +## Jinja2 + +Name: `jinja2` + +[Jinja2][j2] is a powerful template engine that is set by default in PieCrust. +You can read the [templating documentation here][j2tpl]. + + +## Mustache + +Name: `mustache` + +[Mustache][mt] is a minimal template engine that runs fast and keeps your +templates files simple and clean. + + +[j2]: http://jinja.pocoo.org/ +[j2tpl]: http://jinja.pocoo.org/docs/latest/templates/ +[mt]: https://mustache.github.io/ +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/docs/99_reference/08_formatters.md Thu Feb 01 22:03:33 2018 -0800 @@ -0,0 +1,58 @@ +--- +title: "Appendix 8: Formatters Reference" +short_title: Formatters Reference +--- + +When a page gets rendered, it goes through a formatter, _i.e._ something that +can translate whatever syntax you used into the syntax you want the output to +be. In 99% of cases, the syntax will be something like Markdown or Textile, and +the output will be HTML. + +Here is a list of the formatters that come with PieCrust out of the box. + + +## Markdown + +Name: `markdown` or `pymarkdown` + +[Markdown][] is a lightweight markup language that makes it easy to write HTML. +For a primer on its syntax, see the [original documentation][gruber]. + +The default Markdown formatter in PieCrust is powered by [Hoedown][], which is +fast and effective. However, is you want a more fully featured Markdown +formatter and don't mind poorer performance, you can switch to `pymarkdown`, +which uses [Python-Markdown][pymd]. + +You can enable Markdown extensions in your website configuration: + +``` +markdown: + extensions: name,name,name +``` + +The available extension names can be found [here][ext1] for Hoedown, and +[here][ext2] for Python-Markdown. + +In both cases, the name to use in the website configuration should be the short, +vaguely friendly name listed on the referenced webpage -- like `tables`, +`footnotes`, or `fenced_code`. + + +## Textile + +Name: `textile` + +[Textile][] is another lightweight markup language to write HTML. It has more +features than Markdown (see above) but is also more complicated. You can refer +to [this documentation][tx] to learn the syntax. + + +[markdown]: https://en.wikipedia.org/wiki/Markdown +[gruber]: https://daringfireball.net/projects/markdown/syntax +[hoedown]: https://github.com/hoedown/hoedown +[pymd]: https://python-markdown.github.io/ +[ext1]: http://misaka.61924.nl/#extensions +[ext2]: https://python-markdown.github.io/extensions/ +[textile]: https://en.wikipedia.org/wiki/Textile_%28markup_language%29 +[tx]: https://txstyle.org/ +
--- a/docs/docs/99_reference/20_asset-processors.md Wed Jan 31 20:56:02 2018 -0800 +++ b/docs/docs/99_reference/20_asset-processors.md Thu Feb 01 22:03:33 2018 -0800 @@ -10,6 +10,22 @@ configuration, unless noted otherwise. +## Browserify + +Compiles Javascript files using [Browserify][]. + +Name: `browserify` + +This processor isn't used unless the `browserify` configuration exists. It can +simply be set to `true`. + +Configuration settings (under `browserify/`): + +* `bin`: the path to the Browserify executable. Defaults to `browserify`. + +[browserify]: http://browserify.org/ + + ## CleanCSS Compresses CSS files using the `cleancss` utility.
--- a/docs/docs/99_reference/40_publishers.md Wed Jan 31 20:56:02 2018 -0800 +++ b/docs/docs/99_reference/40_publishers.md Thu Feb 01 22:03:33 2018 -0800 @@ -1,5 +1,5 @@ --- -title: "Appendix 8: Publishers" +title: "Appendix 9: Publishers" short_title: "Publishers" ---
--- a/docs/templates/inc/family-sidebar.html Wed Jan 31 20:56:02 2018 -0800 +++ b/docs/templates/inc/family-sidebar.html Thu Feb 01 22:03:33 2018 -0800 @@ -3,11 +3,11 @@ {%- endmacro %} <ul class="doc-level1"> -{% for p in family.root %} +{% for p in family.root.family.siblings %} {% if p.is_dir and p.is_page %} <li>{{ pagelink(p.title, p.url) }} <ul class="doc-level2"> - {% for p2 in p.children %} + {% for p2 in p.family.children %} <li>{{ pagelink(p2.title, p2.url) }}</li> {% endfor %} </ul>
--- a/docs/templates/section-page.html Wed Jan 31 20:56:02 2018 -0800 +++ b/docs/templates/section-page.html Thu Feb 01 22:03:33 2018 -0800 @@ -1,13 +1,15 @@ {% extends "default.html" %} {% block content %} -<div class="container"> - <section class="col-md-8"> - {{ content|safe }} - </section> - <aside class="col-md-4"> - {% include 'inc/family-sidebar.html' %} - </aside> +<div class="container" id="content"> + <div class="row"> + <section class="col-md-8"> + {{ content|safe }} + </section> + <aside class="col-md-4"> + {% include 'inc/family-sidebar.html' %} + </aside> + </div> </div> {% endblock %}