documentation.adoc

Generic-templates is a special theme providing a template framework and meant to be used as a base for other themes.

Its main purpose is to be composed with other themes to reduce the amount of boilerplate code.

Showcase and Hyde themes take advantage of generic-templates.

This theme also provide templates for some bootstrap components.

Layout structure

Generic templates provide a templates.layout template, divided in many partials that allow to quickly start or adapt a design to styx.

• layout

  • partials.doctype: The doctype can be changed via the configuration interface theme.html.doctype.

  • partials.html

    • partials.head.default: See below for head templates division.

    • partials.body

      • partials.content-pre: Pre content template, usually holds navigation bar, empty by default.

      • partials.content: Main content template, should be overriden to needs.

      • partials.content-post: Post content template, usually holds footer, empty by default.

      • partials.js

        • lib.js.jquery: Loading jquery javascript, controlled by conf.theme.lib.jquery.enable.

        • lib.js.bootstrap: Loading bootstrap javascript, controlled by theme.lib.bootstrap.enable.

        • partials.js-custom: Should be overriden to load custom javascript files, empty by default.

        • partials.js-extra: Add custom javascript that are set in the page attribute set extraJS attribute, allow to have custom javascript per page.

Head templates division:

• partials.head.default

  • partials.head.title-pre

    • partials.head.meta: Include a few default meta tags, can be overriden to fit needs.

  • partials.head.title

  • partials.head.title-post

    • partials.head.feed: Create a link for pages.feed if it exists by default, can be overriden to fit needs.

    • partials.head.css

      • lib.css.bootstrap: Loading bootstrap css, controlled by conf.theme.lib.bootstrap.enable.

      • lib.css.font-awesome: Loading font-awesome css, controlled by conf.theme.lib.font-awesome.enable.

      • partials.head.css-custom: Should be overriden to load custom css files, empty by default.

      • partials.head.css-extra: Add custom css that are set in the page attribute set extraCSS attribute, allow to have custom css per page.

    • partials.head.title-post-extra: Can be overriden to fit needs, empty by default.

Overriding a template

Any template from a theme can be overriden to fit needs.

To override a template, just copy it to a custom theme and change it to your liking:

Overriding the partials.content template

$ styx new theme foo --in ./themes # (1)
$ mkdir -p themes/foo/templates/partials/ # (2)
$ cp $(styx theme-path generic-templates)/templates/partials/content.nix themes/foo/templates/partials/content.nix # (3)

1. Creating a new foo theme.

2. Create the themes/foo/templates/partials/ directory.

3. Copy the generic-templates templates/partials/content.nix to the foo theme.
   This code use the generic-templates bundled with styx, to use another version clone the generic-templates repo, select the desired version, and copy the file from there.

Note	Every template of this theme use the documentedTemplate function that allow to generate template documentation.

Combining generic-templates and my-theme

themes = [
  styx-themes.generic-templates
  ./themes/my-theme
];