中文 English

基于 Flask 的简易 Python 博客框架，要求 Python 版本 3.x（下面所有命令中的 python 可能需要换成 python3），Demo：http://demo.blog-a.r-c.im。

pip install -r requirements.txt

在 config.py 文件中修改网站配置信息。

使用 Markdown 书写 Post，放在 posts 目录，Post 文件名为 yyyy-MM-dd-post-name.md 或 yyyy-MM-dd-post-name.markdown，如 2016-03-02-my-first-post.md。

Markdown 文件开头使用 YAML 标记文章信息，可被识别的信息如下：

title: My Post Title (默认从文件名获取, 如: "2016-03-02-my-first-post.md" 的默认 title 为 "My First Post")
layout: post (默认为 "post", 暂不支持其他 layout)
url: (默认为 "root_url/year/month/day/title")
categories: [category1, category2] (默认为空)
tags: [tag1, tag2, tag3] (默认为空)
date: YYYY-MM-DD HH:MM:SS (默认从文件名获取)
updated: YYYY-MM-DD HH:MM:SS (默认为空)
author: Richard Chien (默认为 config.py 文件中设置的 author)
email: richardchienthebest@gmail.com (默认为 config.py 文件中设置的 email)

YAML 标记部分和正文 Markdown 部分用 \n\n 分隔，如：

title: My Post Title
tags: [tag1, tag2]
date: 2016-03-02 20:48

## Title
This is my first post.

建议使用 RealFaviconGenerator 在线生成 Favicon，并覆盖 static 目录下的 favicons 目录。

当然你也可以自行修改 /templates/head.html 文件中设置 Favicon 的部分。

可以直接运行动态 Web App：

python app.py

也可通过 generate 子命令生成纯静态网站：

python app.py generate

生成的静态文件在 _deploy 目录中。

支持自动部署到 GitHub Pages。

首先在 GitHub 创建一个名为 username.github.io 空仓库（username 换成你的 GitHub 用户名），然后运行：

python app.py setup_github_pages

根据提示完成配置，此命令只需在第一次使用时运行。

每次添加了 Post 之后，运行下面命令来生成静态页面：

python app.py generate

并运行：

python app.py deploy

将网站的变动部署到 GitHub Pages。

模板使用 Jinja2 引擎，语法参考 Template Designer Documentation，模板文件放在 templates 目录，运行时程序要求确保 templates 目录下有名为 index.html、post.html、tag.html、category.html、404.html 的几个文件，这些模板文件与 URL 的对应关系如下：

/                           -> index.html
/page/2                     -> index.html
/post/2016/03/03/some-title -> post.html
/tag/some-tag               -> tag.html
/category/some-category     -> category.html

渲染 HTML 时传入的变量为 site 和 page。site 中保存网站信息，即 config.py 中的配置；page 中保存页面相关的信息，具体内容如下：

# 传入 index.html 的 page 的属性
has_newer: 有更新的 Post
newer_url: 更新的 Post 列表, 如在 "/page/3" 时, 此属性值为 "/page/2"
has_older: 有更早的 Post
older_url: 更早的 Post 列表
entries: 当前页面需要显示的所有 Post 条目列表，其中每一个列表项的属性即为 Post 文件开头的 YAML 标记的信息, 以及 "body", 保存已解析成 HTML 的 Markdown 正文内容

# 传入 post.html 的 page 的属性
# 除了 Post 文件开头的 YAML 标记的信息以及 "body" 外, 还包括下面两个:
id_key: 代表该 Post 的唯一值, 用于 Disqus 之类评论框
absolute_url: 链接到该 Post 的绝对路径, 用于 Disqus 之类评论框

# 传入 tag.html 的 page 的属性
tag: Tag 名称
entries: 与传入 index.html 的 page 中的 entries 相同

# 传入 category.html 的 page 的属性
category: Category 名称
entries: 与传入 index.html 的 page 中的 entries 相同

• 支持除 post 以外的 layout
• 安装第三方模板

This is a simple blog app based on Flask, requiring Python 3.x (you may need to use python3 instead of python in all commands below). Demo: http://demo.blog-a.r-c.im.

pip install -r requirements.txt

Configure the blog site in config.py.

Posts should be written in Markdown and placed in posts directory. Names of post files are supposed to be in format yyyy-MM-dd-post-name.md or yyyy-MM-dd-post-name.markdown, for example, 2016-03-02-my-first-post.md.

Extra properties of a post could be placed at the beginning of the markdown file, using the YAML language. The properties which can be identified by the default template are listed below:

title: My Post Title (derived from post file name by default, for example, default title of "2016-03-02-my-first-post.md" is "My First Post")
layout: post (default value is "post" and currently other layouts are not supported)
url: (default value is "root_url/year/month/day/title")
categories: [category1, category2] (default value is none)
tags: [tag1, tag2, tag3] (default value is none)
date: YYYY-MM-DD HH:MM:SS (derived from post file name by default)
updated: YYYY-MM-DD HH:MM:SS (default value is none)
author: Richard Chien (default value is the author in config.py)
email: richardchienthebest@gmail.com (default value is the email in config.py)

\n\n is used to separate YAML and Markdown parts, like:

title: My Post Title
tags: [tag1, tag2]
date: 2016-03-02 20:48

## Title
This is my first post.

It is recommanded to use RealFaviconGenerator to automatically generate favicon online and replace the /static/favicons directory with the generated one.

Alternatively, you can edit /templates/head.html to set favicon by yourself.

You can run dynamic web app use the command below:

python app.py

You can use generate subcommand to generate static site as well:

python app.py generate

The generated files are in _deploy directory.

Deploying to GitHub Pages is supported.

Create an empty repository named username.github.io (change username to your GitHub username) on GitHub, and then run:

python app.py setup_github_pages

Follow the instructions and set it up. This command is only needed for the first time.

Each time you added a new post, run the command below to generate static pages.

python app.py generate

Then deploy the changes to GitHub Pages:

python app.py deploy

Jinja2 engine is used to render templates (see template syntax in Template Designer Documentation). Template files are placed in templates directory. Key files and relations between these files and relative URLs are listed below.

/                           -> index.html
/page/2                     -> index.html
/post/2016/03/03/some-title -> post.html
/tag/some-tag               -> tag.html
/category/some-category     -> category.html

The files above should be seen in templates directory, otherwise the app may not work properly.

Two variables site and page are sent to the template files while rendering them. site stores all configurations in config.py; page stores information about the current page, and here is the details:

# properties in "page" sent to index.html
has_newer: there are newer posts besides the current page or not
newer_url: link of newer posts, for example, value of this property is "/page/2" when the current page is "/page/3"
has_older: there are older posts besides the current page or not
older_url: link of older posts
entries: list of entries, each of which contains all properties marked at the beginning of the correspond post file and a "body" property that stores HTML strings rendered from Markdown body

# properties in "page" sent to post.html
# Besides all properties marked at the beginning of the correspond post file and the "body", it contains the following two:
id_key: the unique key of the post
absolute_url: the absolute url of the post

# properties in "page" sent to tag.html
tag: tag name
entries: same as the "page" sent to index.html

# properties in "page" sent to category.html
category: category name
entries: same as the "page" sent to index.html

• Support layout other than "post"
• Install third-party templates