Theme

Overview

Install a theme

catsup install git_repo

For instance, install Theme Clean

catsup install git@github.com:whtsky/catsup-theme-clean.git

Update a installed theme

catsup install theme_name

For instance, update clean

catsup install clean

List all themes installed

catsup themes

Structure

Catsup uses Jinja2 as a Template Engine.You need to learn it if you want to design your own theme.

You can learn how to design your theme by reading source:

A catsup theme should look like

├── README.md                      <-------- how to install/customize your theme.
├── static                         <-------- static files
│   ├── css
│   │   ├── pygments_style.css     <-------- catsup uses Pygments to highlight code
│   │   └── style.css
├── templates                      <-------- template files
│   ├── 404.html
│   ├── archive.html
│   ├── archives.html
│   ├── page.html
│   ├── post.html
│   └── tag.html
│   └── tags.html
├── filters.py                     <--------- filters defined by theme
└── theme.py                       <--------- meta file

Meta File

A demo meta file

name = 'sealscript'
author = 'Lyric'
homepage = 'https://github.com/whtsky/catsup-theme-sealscript'
post_per_page = 3
vars = {
    "github": "whtsky",
}

A theme meta consists of :

  • name
  • author
  • homepage
  • post_per_page
  • vars

Variables

Global Variables

  • generator: Catsup’s Generator instance.
  • site: site in user’s config file.
  • author: author in user’s config file.
  • config: config in user’s config file.
  • comment: commment in user’s config file.
  • theme: theme.vars in user’s config file.
  • pages: All the pages of the current site.

Templatable Variables

Templatable variables are only accessed in specify templates.

  • pagination: available in page.html

  • post: available in post.html

  • permalink: permalink of the current page

    <link rel="canonical" href="{{ permalink }}"/>

Built-in Functions

static_url

Static URL returns a static URL for the given relative static file path.

<link rel="stylesheet" href="{{ static_url("css/style.css") }}" type="text/css" />

url_for

url for returns the permalink of the given object or string

<a href="{{ url_for('index') }}">{{ site.name }}</a>

<a href="{{ url_for(post) }}">{{ post.title }}</a>

<link rel="alternate" type="application/rss+xml" href="{{ url_for('feed') }}" title="{{ site.name }}" />

Filters

Every function in filters.py will be a filter.Catsup also has some build-in filter:

  • xmldatetime

Template Marco

Catsup has some powerful marco to make your job easier

  • render_comment(post): Render comment of the given post.
  • meta(post): Render meta tags of given post.Should be used id <head>.
  • analytics(): Render analytics code.

An example post.html template using built-in marco

<html>
    <head>
        <title>{{ post.title }}</title>
        {% from 'utils.html' import meta, analytics %}
        {{ meta(post) }}
        {{ analytics() }}
        <link rel="canonical" href="{{ permalink }}"/>
    </head>
    <body>
        <article>
            <h1>{{ post.title }}</h1>
            {{ post.content }}
            {% from 'utils.html' import render_comment %}
            {{ render_comment(post) }}
        </article>
    </body>
</html>

Table Of Contents

Related Topics

About Catsup

Catsup is a lightweight static website generator which aims to be simple and elegant.

Translations

Useful Links