欢迎来到 Catsup¶

Catsup 是一个以简洁、优雅为目标的轻量级静态站点生成器。

用户手册¶

安装¶

如果你对 Python 足够熟悉，我强烈建议你把所有东西都装到 Virtualenv 里面。

如果你在使用 OS X ，请确保你安装了 Command Line Tools .

使用 Pip 安装¶

使用 Pip 安装 Catsup 十分容易

(sudo) pip install catsup

从旧版本升级¶

从旧版本升级也很容易

(sudo) pip install catsup --upgrade

用 Git 安装¶

使用 Git 安装可以用到最新版本的代码

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

# 我们使用了 git submodule 来管理主题
# 如果你不喜欢默认主题（当前版本是 sealscript ）
# 你可以跳过接下来的两条命令
git submodule init
git submodule update

python setup.py install

Cann’t find Python.h ?¶

Catsup 使用 misaka 作为 Markdown 引擎，这个库需要编译才能使用。如果你在使用 Ubuntu ，可以运行

(sudo) apt-get install python-dev

快速起步¶

这部分文档需要你安装 Catsup 。如果你没有，最好先去安装

建立一个新站点¶

用 Catsup 建立一个新站点非常容易

$ mkdir site
$ cd site
$ catsup init

让我们看看发生了什么

$ ls
config.json posts

在执行 catsup init 之后， Catsup 创建了一个配置文件 config.json 和一个空白的文章目录 posts

现在，该配置这个新站点啦。

配置你的站点¶

Catsup 可以被高度自定义，但你只要改几个设置就可以让你的站点跑起来啦 :

site.name : 站点的名字
site.description : 站点的描述
site.url : 站点的 URL 。比如 http://example.com 或者 http://example.com/site
author.name : 你的名字

如果你想要深入了解配置文件的话，情看一看配置

配置完站点之后，该开始写文章啦。

写文章和独立页面¶

让我们先写一个文章

vim posts/hello-world.md

一个 Hello World 文章看起来是这样的

# Hello, World!

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

---

你好, 世界!
这是我在 Catsup 中的第一篇文章.
我在用 **MarkDown** 写东西!
<strong>哇，还支持 HTML </strong>

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

然后，让我们写一个独立页面来介绍你的站点

vim posts/about.md

一个「关于」页面看起来是这样的

# 关于这个站点

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

----

Hi!
这个站点是用 [catsup](https://github.com/whtsky/catsup). 生成的

想要深入了解文章语法？可以去看看文章语法文档。

生成站点¶

在写完文章和独立页面之后，该生成站点然后四处宣传啦！

但是别急，先预览一下这个站点

catsup server

然后打开你的浏览器，进入 http://127.0.0.1:8888 .

如果你想要获取关于预览服务器的更多信息，请前往预览服务器。

在预览完站点，确定一切无误之后，让我们来生成站点

catsup build

看看发生了什么

$ ls
config.json deploy posts

部署站点¶

部署到 GitHub Pages¶

感谢 GitHub, 我们有了一个绝佳的站点部署平台。

你需要一个叫做 YOUR_GITHUB_USERNAME.github.io 的 repo 。如果你还没有，现在去创建一个吧。

然后修改你的配置文件，将 deploy 部分改成这样

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

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

用你的 GitHub 用户名（比如 whtsky ）替换掉 YOUR_GITHUB_USERNAME 。

在这之后，让我们把站点部署到 GitHub Pages 上

catsup build && catsup deploy

然后打开 http://YOUR_GITHUB_USERNAME.github.io 来细细品味你的新站点吧。

部署到自己的服务器上¶

Catsup 也支持通过 rsync 进行部署。在继续之前，你需要确保你的服务器上运行着 rsync 。

然后修改你的配置文件，将 deploy 部分改成这样

"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",
    }
},

这里有份儿例子

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

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

在这之后，让我们通过 rsync 部署我们的站点

catsup build && catsup deploy

读一读部署支持来详细了解这个功能。

文章语法¶

Catsup 目前支持三种格式的文章： Markdown, 纯文本和 HTML.

Markdown 格式的文章¶

总览¶

文章的扩展名应为 .md 或 .markdown .

一个 Hello World 文章看起来是这样的

# 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")
```

一篇文章由三部分构成:

标题
元数据
正文

标题¶

标题应该始终在文章的第一行，以 # 起头。

正文¶

分隔符下的一切都是正文，正文应该以 Markdown 形式书写。

代码高亮¶

Catsup 支持 GitHub 风格的代码高亮，就像这样

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

纯文本格式的文章¶

有时候你只是想写些东西而不想去考虑文章的格式，那么你应该选择纯文本格式的文章。

纯文本格式的文章的扩展名应该是 .txt 。

最简单的纯文本格式的文章看起来是这样的

Hello!
This is a text post.

如果你想要加一些元数据的话，你应该使用 YAML 格式的元数据

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

Hello, World! I'm a text post.

HTML 格式的文章¶

HTML 格式的文章就像纯文本格式的文章, 但是你可以在文章正文中使用 HTML .

HTML 格式的文章的扩展名应该是 .html .

文章样例

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

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

元数据¶

元数据是关于文章的一些信息。元数据不是必须的，如果你的文章有元数据的话，记得在元数据下面加上分隔符

time: 文章是何时写成的，比如 2013-08-25 11:10
tags: 文章的 Tag ，以英文逗号分割，比如 Python, Program
type: 设置为 page 来把这篇文章转换为一个独立页面
description: 文章的描述
comment: 设置为 disabled 来禁止评论
permalink: 文章的永久链接地址，比如 /this-post

分隔符¶

分隔符将文章元数据与正文分割开。分隔符应该至少有三个 -

---

当然他也可以更长

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

独立页面¶

独立页面是一种特殊的文章。可以通过在元数据中添加 - type: page 将一篇普通文章转换为元数据。

普通文章和独立页面之间有什么区别呢？

独立页面没有 Tags
独立页面不会在归档页面和分页页面中出现
一般来说，每一页的导航部分都会有独立页面的连接

配置¶

Catsup 的配置文件是一个标准的 JSON 文件

总览¶

默认的配置文件看起来是这样的 :

{
    "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": "/{title}/",
        "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¶

这几项配置起来十分容易。

如果你要用 Google Analytics 的话，记得修改 config.analytics

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

Permalink¶

通过修改 config.permalink ，你可以轻松的自定义任何页面的永久链接。

下面这些 Post 页面的永久链接风格比较有参考价值 :

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

注意，在文章元数据中定义的永久链接会被优先使用。

比如说，在配置文件里，你自定义了 Post 页面的永久链接

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

然后在你的某篇文章中，你在元数据中自定义了一个永久链接

# About

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

-------

This is a about page

那么，这篇文章的永久链接将会是 /about-the-site .

Comment¶

Catsup 支持两种评论系统: Disqus 和多说

如果你更喜欢多说的话，可以轻松的把评论系统设置成多说

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

如果你在评论系统中有自己的站点的话，记得把 comment.shortname 改成你自己的

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

如果你不希望开启评论系统，那么就关掉它吧

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

如果你只是希望部分文章不背评论，可以在元数据中设置 - comment: disabled

Deploy & Theme¶

这几项配置起来十分容易。

如果还不太明白的话，去看看部署支持和你主题的文档吧。

主题¶

总览¶

安装一个主题

catsup install git_repo

比如，安装 Theme Clean

catsup install clean

列出所有已安装的主题

catsup themes

结构¶

Catsup 使用 Jinja2 模板引擎。如果你想要开发自己的主题，你需要先了解 Jinja 2 。

你可以看看以下几个主题来了解如何开发自己的 Catsup 主题：

一个 Catsup 主题看起来是这样的

├── 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

元数据¶

一个主题元数据文件的例子

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

一个主题元数据包括 :

name
author
homepage
post_per_page
vars

变量¶

全局变量¶

generator: Catsup 的 Generator 实例.
site: 配置文件中的 site .
author: 配置文件中的 author .
config: 配置文件中的 config .
comment: 配置文件中的 commment .
theme: 配置文件中的 theme.vars .
pages: 当前站点的所有独立页面

模板变量¶

只有几个模板有模板变量。

pagination: page.html 中特有的模板变量。
post: post.html 中特有的模板变量。

permalink: 当前页面的永久链接

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

内置函数¶

static_url¶

Static URL 返回给定静态文件的 URL

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

url_for¶

url for 返回给定对象的永久链接地址

<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.py 中的所有函数都会被注册为过滤器。 Catsup 也内置了一些过滤器：

xmldatetime

模板宏¶

Catsup 有一些强大的模板宏，可以让你更加轻松的编写模板。

render_comment(post): 为给定的文章渲染评论
meta(post): 为给定的文章渲染 meta 标签。应当在 <head> 中被调用。
analytics(): 渲染统计代码。

使用内置的模板宏的 post.html 例子

<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¶

预览服务器¶

预览服务器可以让你不用部署就看到自己的站点

catsup server
catsup server -p 8000

当

站点的源文件夹(默认是 posts ) 中发生更改的时候（比如创建新的文章，修改已有的文章）
你的主题文件夹中发生更改的时候（为 Catsup 写主题的时候会很有用）
Catsup 主程序发生变化（为 Catsup 编写代码的时候会很有用）

的时候，预览服务器会自动重新生成你的站点。

注解

当运行预览服务器的时候， Catsup 会忽视掉 site.url 并把生成的文件保存到一个临时文件夹中。

部署支持¶

可以帮助你通过 Git 或 rsync 快速部署你的站点

catsup deploy # 通过默认方式部署
catsup rsync # 通过 rsync 部署
catsup git # 通过 git 部署

Webhook¶

如果你把站点的源文件保存在 GitHub 或 Bitbucket 上， Catsup 可以在你 push 到 Git 仓库的时候自动更新、生成你的站点。

你需要把站点的 repo clone 下来并开启 Webhook 服务

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

注意

Catsup 的 webhook 功能并不会以守护进程运行，这意味着你可能需要 Supervisor 这类工具来守护 webhook

之后你需要在 GitHub 或 BitBucket 中做一些配置，这里以 GitHub 为例：

打开项目的 “Admin” 页面
点击 “Service Hooks”
在 “available service hooks” 中, 点击 “WebHook URLs“
输入 Webhook URL [1]
点击 “Update Settings”

[1]	如果你服务器的 IP 地址为 1.2.3.4 , 你应该输入 `http://1.2.3.4:12580/webhook`

之后每当你 push 到 GitHub, Catsup 都会自动更新并生成你的站点。

升级到新版本¶

Catsup 本身会处在不断的变化之中，对于大多数的变化而言，你不需要做任何改动就可以让你的站点跑在新版本的 Catsup 下。

然而，有时候会有一些变化需要你更改站点中的某些地方。

这部分文档包含了 Catsup 每次版本更新中的变化，以及怎么样做倒无痛升级。

如果你想用 easy_install 命令来升级 Catsup ，确保你加上了 -U

$ easy_install -U catsup

Version 0.2.0¶

从 0.2.0 版本开始， Catsup 加入了缓存系统。

缓存的文件保存在 .catsup-cache 文件夹中，所以如果你在用 git 管理你的站点并且希望忽略掉缓存文件的话，应该把这行加到你的 .gitignore 文件里

.catsup-cache

更新日志¶

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