Welcome to Catsup¶

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

User’s Guide¶

Installation¶

If you are familiar with Python, it is strongly suggested that you install everything in virtualenv.

If you are using OS X , make sure you have installed the Command Line Tools .

Install using pip¶

Install Catsup via pip is easy

(sudo) pip install catsup

Upgrade from older version¶

It’s also easy to upgrade your Catsup

(sudo) pip install catsup --upgrade

Install with Git¶

Install with git can always have the latest code

git clone git://github.com/whtsky/catsup.git
cd catsup

# We use git submodules to organize out theme.
# If you don't want the default theme(current version is sealscript)
# You can skip these command.
git submodule init
git submodule update

python setup.py install

Cann’t find Python.h ?¶

Catsup uses misaka as the markdown engine. It requires C compiler.On Ubuntu, you may run

(sudo) apt-get install python-dev

Get Started¶

This section needs you have Catsup installed.If you don’t, please go and Install it

Create a new site¶

It’s pretty simple to create a site using Catsup

$ mkdir site
$ cd site
$ catsup init

Let’s see what happened

$ ls
config.json posts

After running catsup init, Catsup generates a sample config file config.json and an empty post folder posts.

Now, let’s configure your new site.

Configure your site¶

Catsup can be highly customized, but you only need to change a few variables to get started :

site.name : Name of your site
site.description : Description of your site
site.url : Your site’s URL. Like http://example.com or http://example.com/site
author.name : Your nickname

Want to learn more about configuration file? Take a look at Configuration

After configuring your site, it’s time to start writing.

Write posts and pages¶

Let’s write a post first

vim posts/hello-world.md

a Hello World post looks like

# Hello, World!

- time: 2013-08-25 23:30
- tags: hello world

---

Hello, World!
This is my first post in catsup.
I'm writing in **MarkDown** !
<strong>HTML is supported, too</strong>

```python
print("I love python")
```

Then, let’s write a page to talk about your site

vim posts/about.md

a About page looks like

# About the site

- time: 2013-08-25 23:31
- type: page

----

Hi!
This site is generated by [catsup](https://github.com/whtsky/catsup).

Read about Post Syntax to learn more.

Build your site¶

After writing posts and pages, It’s time to build your site and let everyone know!

But don’t hurry, let’s take a look at your site first

catsup server

Then open your favorite web browser, go to http://127.0.0.1:8888 .

Head over to Preview Server to know more.

After making sure everything’s all right, let’s build the site

catsup build

Let’s see what happened

$ ls
config.json deploy posts

Deploy your site¶

Deploy to GitHub Pages¶

Thanks to GitHub, we have a perfect place to host our site.

You need to have a repo called YOUR_GITHUB_USERNAME.github.io. If you don’t, go to create one

Then edit your configuration file, change deploy section like this

"deploy": {
    "default": "git",

    "git": {
        "repo": "git@github.com:YOUR_GITHUB_USERNAME/YOUR_GITHUB_USERNAME.github.io.git",
        "branch": "master",
        "delete": true
    }
},

replace YOUR_GITHUB_USERNAME with your github username, like whtsky .

After that, let’s deploy your site to GitHub Pages

catsup build && catsup deploy

Then open http://YOUR_GITHUB_USERNAME.github.io to enjoy your fresh site.

Deploy to your own server¶

Catsup also supports deploy via rsync. Before continue, make sure you have rsync running on your server.

Then edit your configuration file, change deploy section like this

"deploy": {
    "default": "rsync",

    "rsync": {
        "ssh_port": 22,
        "ssh_user": "USER_NAME_HERE",
                    "ssh_host": "IP_ADDRESS_OF_YOUR_SERVER",
        "document_root": "DEPLOY_TO_WHICH_PATH",
    }
},

Here’s an example

"deploy": {
    "default": "rsync",

    "rsync": {
        "ssh_port": 22,
        "ssh_user": "whtsky",
                    "ssh_host": "whouz.com",
        "document_root": "~/whouz.com",
    }
},

After that, let’s deploy your site via rsync

catsup build && catsup deploy

Head over to Deploy Support to know more.

Post Syntax¶

Catsup currently supports 3 types of post: Markdown, Text and HTML.

Markdown Post¶

Overview¶

Post’s extension should be either .md or .markdown .

A sample post looks like

# Hello, World!                          <---- This is title

- time: 2013-08-25 23:30                 <---- This is meta
- tags: hello world

---

Hello, World!                            <---- This is content
This is my first post in catsup.
I'm writing in **MarkDown** !
<strong>HTML is supported, too</strong>

```python
print("I love python")
```

A post consists of three parts:

Title
Meta
Content

Title¶

Title should always on the first line and starts with #

Content¶

Everything below the separator is the content. Content should be written in Markdown.

Code Highlight¶

Catsup supports GitHub’s style code highlight, like this

```python
print("Hello World!")
```

Text Post¶

Sometimes you may just want to write something without considering the syntax. Then you should use Text Post.

Text post’s extension should be .txt .

The simplest text post looks like

Hello!
This is a text post.

If you want to write meta in a text post, write the meta in YAML format

---
title: Hello, World!
tags: Hello, World
time: 2014-01-04 20:56
---

Hello, World! I'm a text post.

HTML Post¶

HTML post is like Text Post, but you can use HTML in the content.

HTML post’s extension should be .txt .

A HTML post looks like

---
title: Hello, World!
tags: Hello, World
time: 2014-01-04 20:56
---

<p>I'm writing HTML in catsup</p>

Meta¶

Meta is some information about the post. Note that meta is optional, and if your post have meta, remember to put a separator below the meta.

time: When the post is written. like 2013-08-25 11:10
tags: Tags of the post. Separated by comma, like Python, Program
type: Set to page to turn this post into a page.
description: Description of the post.
comment: Set to disabled to forbid comment
permalink: Permalink to the post, link /this-post

The separator¶

The separator separates meta and content. It should be at least three -

---

It’s okay to make it longer

----------------

Page¶

Page is a kind of post. Turn an ordinary post into page by adding - type: page in post’s meta.

So, what’s the difference between page and post?

Page do not have tags
Page do not display in Archives Pages and Index Pages
In general, pages will be linked in every page’s navigation.

Configuration¶

Catsup’s configuration file is a vaild JSON file.

Overview¶

The default config file looks like :

{
    "site": {
        "name": "blogname",
        "description": "Just another catsup blog",
        "url": "http://blog.com/"
    },

    "author": {
        "name": "nickname",
        "email": "name@exmaple.com",
        "twitter": "twitter"
    },

    "config": {
        "source": "posts",
        "static_source": "static",
        "output": "deploy",
        "static_output": "deploy/static",
        "static_prefix": "/static/",
        "analytics": ""
    },

    "permalink": {
        "page": "/page/{page}/",
        "post": "/{filename}/",
        "tag": "/tag/{name}/",
        "tags": "/tag/index.html",
        "archive": "/archive/{year}/",
        "archives": "/archive/index.html",
        "feed": "/feed.xml"
    },

    "comment": {
        "allow": true,
        "system": "disqus",
        "shortname": "catsup"
    },

    "deploy": {
        "default": "rsync",

        "git": {
            "repo": "repo url here",
            "branch": "master",
            "delete": true
        },

        "rsync": {
            "ssh_port": 22,
            "ssh_user": "username",
            "ssh_host": "123.45.6.78",
            "document_root": "~/website.com/",
            "delete": true
        }
    },

    "theme": {
        "name": "sealscript",
        "vars": {
            "github": "whtsky",
            "links": [
                {
                    "name": "catsup",
                    "url": "https://github.com/whtsky/catsup",
                    "description": "Awesome!"
                }
            ]
        }
    }
}

Site & Author & Config¶

It’s easy enough to configure these by yourself.

If you’re using Google Analytics, remember to change config.analytics

"config": {
    "source": "posts",
    "static_source": "static",
    "output": "deploy",
    "static_output": "deploy/static",
    "static_prefix": "/static/",
    "analytics": ""
},

Permalink¶

You can easily change any page’s permalink in config.permalink .

There are some permalink styles for posts you may like :

/{title}.html
{filename}.html
/{date}/{title}/
/{filename}/
/{date}/{filename}/
/{datetime.year}/{filename}/

Note that permalink defined in Post Meta will be used first.

For example, you defined your post permalink like

"permalink": {
    "post": "/{title}/",
    "feed": "/feed.xml"
},

And in your post, you defined a permalink in Post Meta

# About

- datetime: 2013-08-30 12:00
- type: page
- permalink: /about-the-site

-------

This is a about page

In the end the permalink of this page will be /about-the-site .

Comment¶

Catsup supports two comment systems: Disqus and Duoshuo

If you prefer Duoshuo to Disqus, just change your comment system to it

"comment": {
    "allow": true,
    "system": "duoshuo",
    "shortname": "catsup"
},

If you have your own shortname, remember to change comment.shortname to your own

"comment": {
    "allow": true,
    "system": "disqus",
    "shortname": "my_site"
},

If you don’t want to allow any comment, just disable it

"comment": {
    "allow": false
},

If you just want some of the posts can’t be commented, set - comment: disabled in Post Meta

Deploy & Theme¶

It’s easy enough to configure these by yourself.

For more information, read about Deploy Support and your theme’s document.

Theme¶

Overview¶

Install a theme

catsup install theme_name

For instance, install Theme 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>

Goodies¶

Preview Server¶

Preview your site without deploy

catsup server
catsup server -p 8000

Preview server will regenerate your site when :

Your source folder (posts by default) changes (Like add a new post or modify one)
Your theme folder changes(Useful for writing themes for Catsup)
Catsup program changes(Useful for writing codes for Catsup)

Note

Catsup will ignore site.url and build your site into a temporary directory when running Preview Server.

Deploy Support¶

Help you deploy your site via git or rsync

catsup deploy # Deploy via default way
catsup rsync # Deploy via rsync
catsup git # Deploy via git

Webhook¶

If you host your site’s source on GitHub or Bitbucket, Catsup can generate your site when you push to your repo.

You need to clone your repo and start webhook server

git clone git://path/to/your/site.git
cd site
catsup webhook -p 12580

Attention

Catsup webhook is not a daemon process.That means you may need to use Supervisor to turn it into daemon.

Then configure webhook on GitHub or Bitbucket. Here we use GitHub as an example:

Go to the “admin” page for your project
Click “Service Hooks”
In the available service hooks, click “WebHook URLs“
Type your url [1]
Click “Update Settings”

[1]	If your server’s ip is 1.2.3.4 , you can type `http://1.2.3.4:12580/webhook`

Then when you push to GitHub, Catsup will pull and generate your site.

Upgrading to Newer Releases¶

Catsup itself is changing like any software is changing over time. Most of the changes are the nice kind, the kind where you don’t have to change anything in your site to profit from a new release.

However every once in a while there are changes that do require some changes in your site.

This section of the documentation enumerates all the changes in Catsup from release to release and how you can change your site to have a painless updating experience.

If you want to use the easy_install command to upgrade your Catsup installation, make sure to pass it the -U parameter:

$ easy_install -U catsup

Version 0.2.0¶

Catsup adds an cache system since 0.2.0 .

Cache files are stored in .catsup-cache folder, so if you are using git to organize your site and want to ignore the cache files, add the following line to your .gitignore file

.catsup-cache

Changelog¶

Version 0.3.5¶

Fix a theme install bug

Version 0.3.4¶

Change default post permalink
Drop cache property

Version 0.3.3¶

Improve Post Model
Change default post permalink

Version 0.3.2¶

Fix Post meta bug
Code improvement

Version 0.3.1¶

Fix a bug on catsup install

Version 0.3.0¶

Add multi-format post support
Add config.config.static_source
Add config.config.static_output
Support Non-meta post.
Support customize permalink for post
Support TXT format post.
Support HTML format post.
Support YAML format meta.
Rewrite catsup install
Correct the url for Twitter Card Support
Drop file-based cache system.
Improve description creator
Reorganize code.

Version 0.2.1¶

Fix build bugs.

Version 0.2.0¶

Support generate sitemap
Add catsup watch command
Add catsup clean command
Add cache for rendering markdown
Add cache for url_for
Add cache for static_url
Use Jinja2’s Bytecode Cache
Don’t generate analytics codes when running catsup server
Display time cost for loading config and posts
Change json engine to ujson

Version 0.1.0¶

Use full md5 hash in static_url
Add support for pages
Build to tempdir when running catsup server
Add config.site.description
Use config.comment.shortname to replace config.comment.disqus and config.comment.duoshuo
Regenerate the site when your theme or posts changed when running catsup server
Use local static file when running catsup server
Post per page is defined by theme
Now catsup copy non-markdown files in source folder to deploy folder
Drop summary support
Drop escape markdown support
Add sub path support
Support customize any permalink
Rewrite generator, parser and server
Don’t regenerate your site before deploy

Version 0.0.8¶

Rewrite tag and archive code
Add deploy support.(via git or rsync)

Version 0.0.7¶

Released on Feb. 7, 2013

Add pagination for writing theme
Rename excerpt to summary
Add theme utils
Support theme filters