Content¶
Everything below the separator is the content. Content should be written in Markdown.
Catsup is a lightweight static website generator which aims to be simple and elegant.
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 .
It’s also easy to upgrade your Catsup
(sudo) pip install catsup --upgrade
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
Catsup uses misaka as the markdown engine. It requires C compiler.On Ubuntu, you may run
(sudo) apt-get install python-dev
This section needs you have Catsup installed.If you don’t, please go and Install it
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.
Catsup can be highly customized, but you only need to change a few variables to get started :
Want to learn more about configuration file? Take a look at Configuration
After configuring your site, it’s time to start writing.
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.
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
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.
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.
Catsup currently supports 3 types of post: Markdown, Text and HTML.
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 should always on the first line and starts with #
Everything below the separator is the content. Content should be written in Markdown.
Catsup supports GitHub’s style code highlight, like this
```python
print("Hello World!")
```
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 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 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.
The separator separates meta and content. It should be at least three -
---
It’s okay to make it longer
----------------
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?
Catsup’s configuration file is a vaild JSON file.
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!"
}
]
}
}
}
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": ""
},
You can easily change any page’s permalink in config.permalink .
There are some permalink styles for posts you may like :
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 .
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
It’s easy enough to configure these by yourself.
For more information, read about Deploy Support and your theme’s document.
Install a theme
catsup install theme_name
For instance, install Theme Clean
catsup install clean
List all themes installed
catsup themes
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
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 :
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 }}"/>
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 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 }}" />
Every function in filters.py will be a filter.Catsup also has some build-in filter:
Catsup has some powerful marco to make your job easier
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>
Preview your site without deploy
catsup server
catsup server -p 8000
Preview server will regenerate your site when :
Note
Catsup will ignore site.url and build your site into a temporary directory when running Preview Server.
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
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:
| [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.
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
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
Released on Feb. 7, 2013