Total Pageviews

Sunday, 29 November 2015

基于python的静态博客生成器-gude

厌倦了Wordpress越来越庞杂却无用的功能,想让网站回归单纯,Octopress本是个不错的选择,但在OS X下总有这样那样的问题,自己对Ruby也不了解,于是就在Python下折腾出了这个Gude。

    基于Python2.7
    使用GIT进行管理和发布
    使用Markdown或HTML撰写文章
    支持分类、标签
    支持文章模板、站点皮肤
    评论系统Disgus,统计系统Google Analytucs
    支持发布到Github或任意的FTP服务器1
    简单的插件支持

Project on GitHub
安装
1. 准备

  必须安装:
    Python 2.7.3 Gude使用的开发语言
    Git 分布式版本管理 Gude用于站点的备份发布等

  另外最好对以下的语言有所了解:

    Markdown 轻量级的标记语言,易读易写,Gude中用于书写文章内容
    YAML 一种对人阅读友好的标记语言,可存储多种数据格式,Gude中用于配置文件
    mako Gude使用的模板系统,如果希望自定义网站,就必须掌握它

2. 下载

    从GitHub clone到本地 推荐
    直接下载

3. 安装

  git clone git://github.com/JinnLynn/gude.git && cd gude && python setup.py install

  系统必须有pip,安装gude时也将安装一些依赖的第三方库。
使用
1. 概述

  基本的命令格式:gude [-h] [-v] {serve,add,publish,init,build,backup} ...

  各子命令作用:

init
在当前工作目录下初始化一个新的网站;

add
添加新的文章;

build
生成网站内容;

serve
在本地启动一个简单的网页服务器;

publish
发布网站到服务器,服务器的相关信息需在配置文件中配置;

backup
备份

2. 初始化

  命令:gude init [-h] [-f]

  在任意目录下执行gude init可初始化一个新的站点,如果该目录下已存在文件则需要参数-f或--force强制清空目录并初始化。

  若初始化成功将会产生如下的目录结构:
目录或文件
  
content
   
存放原始文章文件;

deploy

存放生成的文件;

static
 
一些需要在生成站点时拷贝到deploy目录的文件;

theme
   
皮肤;

site.yaml
   
网站配置文件 该文件会被GIT跟踪;

privacy.yaml
   
私用配置文件 该文件不会被GIT跟踪 且优先级高于site.yaml;

README.md
   
github说明文件;

4Git版本管理文件 .git .gitignore
3. 配置

  配置文件有两个:site.yaml、privacy.yaml,其中privacy.yaml的优先级高于site.yaml,且进行网站版本管理时不会被跟踪,主要用于存储一些私有的信息,如FTP服务器地址密码等。

  比较主要的键值参考如下:

键名
   

默认值
   

说明

domain
       

域名

subdirectory
   

/
   

子目录

title
       

网站名称

author
       

作者

category
   

[Other]
   

文章分类

num_per_page
   

5
   
每页显示的文章数;

num_in_feed
   

10
   

FEED显示的文章数

num_in_archive
   

50
   

存档页显示的文章数

theme
   

default
   

皮肤风格

default_layout
   

post
   

默认文章模板

header_menu
       

页面头部菜单

comment_service
   

duoshuo
   

评论系统类型 可选值: duoshuo disgus

comment_service
       

评论系统disqus或多说的shortname

google_analytics_track_id
       

Google Analytucs跟踪ID

feed_url
       

使用第三方FEED服务时的地址

content_filter
   

[Shortcode, CenterElement]
   

文章内容处理插件 见这里

designated
       

指定生成的文件地址

file_copy
       

拷贝文件到生成目录

local_domain
   

http://localhost:8910
   

用于调试的本地模式地址

local_subdirectory
   

/
   

用于调试的本地模式子目录

publish_type
       

在privacy.yaml 发布模式 可选值 git、gitftp、rsync,其中git只能发布到GitHub

ftp_server
       

在privacy.yaml FTP服务器

ftp_subdirectory
       

在privacy.yaml FTP服务器子目录

ftp_usr
       

在privacy.yaml FTP用户名

ftp_pwd
       

在privacy.yaml FTP密码

github_project_page
   

no
   

在privacy.yaml 使用git发布时是否是github的项目页面

git_remote
       

在privacy.yaml GIT远程路径

rsync_server
       

rsync服务器地址

rsync_subdirectory
       

rsync同步目录

rsync_usr
       

rsync用户名

rsync_sshkey
       

rsync用户密钥
4. 写文章
文章命名规则

    文章必须存放在content目录下,但也可以在content下另建文件夹存储
        直接在content目录下的,发布的文件将在article目录下,以类似http://YOUR-DOMAIN.COM/article/...的地址访问
        在content下其它文件夹的,发布文件将在其对应的目录下,以类似http://YOUR-DOMAIN.COM/DIR—NAME/...的地址访问
        自建文件夹不限嵌套层数,但顶层(即在content下)不允许如下命名:tag, tags, category, archive, article, assets, page
    文章必须以日期为前缀,形如2013-01-01-FILENAME.md,但生成的发布文件不会包括日期信息
    文章文件名后缀支持md markdown html,Gude将通过后缀名决定处理方式
    文章字符编码UTF-8
    默认情况下,Gude按照一定的规则生成文件,但你也可以指定生成文件路径,见这里

文章配置

  文章配置使用YAML书写,位于文章开始位置并被<!-- -->所包围,可配置的信息如下:

键名
   

默认值
   

说明

title
       

文章标题

date
   

文章文件生成时间
   

形如2013-01-02 14:23:21

catrgory
   

~
   

文章分类,必须使用站点配置category中存在的分类名,否则将被忽略

tag
   

~
   

文章标签

author
   

站点配置author的值
   

作者

modify
   

文章文件的最后修改时间
   

修改时间

layout
   

站点配置default_layout的值
   

文章模板布局

unlisted
   

[]
   

不罗列的页面 序列类型数据 支持home sitemap archives feed

status
   

public
   

文章状态 public sticky draft

custom
   

~
   

自定义信息,映射类型的数据
命令行生成新文章

  命令:gude add [-h] [--html] [--layout LAYOUT] [--status STATUS] [-f FILENAME] [-t TITLE]

参数
   

说明

-h
   

帮助

-t
   

文章标题 不指定默认 Untitled

-f
   

文件名称,不指定则是文章标题,支持设置目录, 规则见这里。

--html
   

默认生成.md文件,指定该参数则生成.html文件

--layout
   

不指定使用配置文件键值default_layout所设定

--status
   

文章状态 可选public、sticky、draft 默认public
手动生成新文章

  在content下自行手动创建符合命名规则的文本文件。
5. 生成网站

  命令:gude build [-h] [-i] [-l] [-p]

参数
   

说明

-h
   

帮助

-l
   

生成本地文件,即站点地址使用 local_domain

-i
   

输出详细信息

-p
   

生成后启动服务器预览

  注意,在生成网站前,Gude会把deploy目录下的所有文件删除,如果你有某些文件需要存在于最终发布的网址中,请参考这里操作。
6. 本地服务器查看

  命令:gude serve [-h] [-p PORT]

参数
   

说明

-h
   

帮助

-p
   

端口 默认 8910

  启动一个本地服务器访问网站,建议使用gude build -lp生成一个本地版本用于查看效果。
7. 发布

  命令:gude publish [-h] [-b] [-f] [-c]

参数
   

说明

-h
   

帮助

-b
   

发布前重新生成网站

-c
   

清理

-f
   

强制,清空服务器上旧内容,如果发布失败可使用该参数,另:第一次发布时必须加该参数

  发布网站到预置的服务器。
8. 备份

  命令:gude backup [-h] [-f] [--remote] [-c]

参数
   

说明

-h
   

帮助

-c
   

清理

-f
   

强制

--remote
   

推送到远程,目前仅支持GitHub,参考这里。
进阶
1. 皮肤

  Gude支持皮肤,使用的模板系统是Mako,皮肤名即其所在的文件夹名,Gude将自动搜索站点所在目录和Gude目录下的theme文件夹。

  若你想设计自己的皮肤请参考默认皮肤default。
2. 文章内容处理插件

  Gude支持一些简单的对文章内容处理的插件,文件位于plugin。默认已有Shortcode、CenterElement,具体作用参考源代码。   
3. 指定生成的发布文件路径

  正常情况下,Gudu按照一定的规则生成发布文件,但如果需要也可以自定义生成的发布文件路径,在site.yaml中配置参数designated即可。比如

designated:
    - src:      2000-01-01-projects.md
      dst:      projects/index.html
    - src:      2000-01-01-about.html
      dst:      about/index.html

  其中src为文章路径(相对content目录),dst为生成的发布文件(相对deploy目录)。
4. 生成时拷贝文件到发布目录

  在每次执行gude build生成站点时,Gude将删除deploy目录下的所有文件,因此如果你的网站需要一些额外的文件(如自己上传的文件)则在site.yaml中配置参数file_copy,如

file_copy:
    - src:      static/htaccess
      dst:      .htaccess
    - src:      static/favicon.ico
      dst:      assets/images/favicon.ico

  其中src为源文件路径(相对static目录),dst为生成的发布文件(相对deploy目录)。
5. GIT

  Gude的站点目录下有两个git版本库,一个位于站点根目录下,另一个在deploy目录下,前者用于管理站点源文件,后者用于管理发布文件,当你使用Github作为你的网站空间并使用gude backup --remote将站点备份到github上时有需要注意:

    用github的个人page时,站点提交到source分支,deploy提交到master分支
    用github的项目page时,站点提交到master分支,deploy提交到gh-page分支

6. 从Wordpress迁移

  tools目录下有wordpress-export.php可导出Wordpress日志到Gude,将其拷贝到Wordpress目录后浏览器中访问该文件即可,一些设置见源文件。
其它

    Gude中使用的第三方库: commando、mako、PyYAML、feedgenerator、python-markdown2
    感谢最好的版本管理系统Git和代码托管服务GitHub,
    建议写一篇新文章的操作流程
        添加新文章并撰写 gude add
        生成本地版本并预览 gude build -lp
        生成最终版本并发布 gude publish -b
        FTP发布需GIT-FTP支持.      from  http://jeeker.net/projects/gude/

    Gude is a simple static site generator, written in Python.
        Simple, very easy to use
        Work with GIT & GitHub
        Completely static output

    Gude
    Installation

    git clone git://github.com/JinnLynn/gude.git && cd gude && python setup.py install

    USAGE
    create a new gude site

    gude init [-h|-f]

    configuring gude site

    edit site.yaml for public settings and privacy.yaml for private settings, here are example: site-example.yaml privacy-example.yaml
    add new article

    gude add -t "TITLE" -f "FILENAME" [--status "STATUS"] [--layout "LAYOUT"] [--html]

    build site

    gude build [-l|--local] [-p|--preview] [--less] [--less-compress] [-i|--info]

    serve site

    gude serve [-p PORT|--port PORT] [-s|--silent]

    publish site

    gude [-c|--clean] [-f|--force] [-b|--build]

    backup site

    gude [-c|--clean] [-f|--clean] [-r|--remote]

    from https://github.com/JinnLynn/gude

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

    我的补充说明:假设你现在在/root/下。

    easy_install virtualenv ( 安装virtualenv)

    virtualenv dev (此命令会在当前目录下,生成dev目录)

    cd ~/dev/

    source bin/activate (激活python的虚拟环境)

    git clone https://github.com/JinnLynn/gude

    cd gude

    python setup.py install (这样,gude安装完毕)

    mkdir gude-dir

    cd gude-dir

    gude init (这是初始化gude的网站架构的命令。运行之后,在当前目录下会生成一些文件夹和文件)

    root@AR:~/gude/gude-dir# ls

    content  deploy  privacy.yaml  README.md  site.yaml  static  theme

    root@AR:~/gude/gude-dir#

    root@AR:~/gude/gude-dir# gude -h

    usage: gude [-h] [-v] {serve,add,publish,init,build,backup} ...

    Gude - a simple python static website generator

    positional arguments:

      {serve,add,publish,init,build,backup}

        serve               Serve the website

        add                 Add new article

        publish             Publish the website

        init                Create a new site.

        build               build a new site.

        backup              Backup site with GIT

    optional arguments:

      -h, --help            show this help message and exit

      -v                    show program's version number and exit

    Use gude {command} -h to get help on individual commands

    root@AR:~/gude/gude-dir# gude add -h

    usage: gude add [-h] [-t TITLE] [-f FILENAME] [--status STATUS]

                    [--layout LAYOUT] [--html]

    optional arguments:

      -h, --help       show this help message and exit

      -t TITLE         article title

      -f FILENAME      article filename, no extension

      --status STATUS  article status

      --layout LAYOUT

      --html           Use HTML type, default is Markdown
    root@AR:~/gude/gude-dir# gude add -t 测试3 -f test3
(此即新建源帖的命令)
    article 'content/2016-07-07-test3.md' created.
    root@AR:~/gude/gude-dir# nano content/2016-07-07-test3.md
(在header部分下方空一行,写正文或html code)
     root@AR:~/gude/gude-dir# gude build (这个就是生成/更新静态网站的命令)
    Start building...
    Site build success.
    root@AR:~/gude/gude-dir# cd deploy
    root@AR:~/gude/gude-dir/deploy# ls
    404.html  article  atom.xml    README.md
    archives  assets   index.html  sitemap.xml
    root@AR:~/gude/gude-dir/deploy#
    (deploy目录里有index.html文件,可见deploy目录就是静态博客网站的根目录.你可绑定你的域名到该目录)

    root@AR:~/gude/gude-dir/deploy# nohup Rwebserver 8900 > /dev/null &

    (然后访问http://ur-vps-ip:8900,即可看到网站效果)

    root@AR:~/gude/gude-dir/deploy# cd ..

    root@AR:~/gude/gude-dir#

    root@AR:~/gude/gude-dir# ls

    content  deploy  privacy.yaml  README.md  site.yaml  static  theme

    root@AR:~/gude/gude-dir# nano site.yaml

    (把网站的配置文件site.yaml里的yourdomain.com改为你要绑定的域名,我把它改为了

    gd.bright.biz.st)

    root@AR:~/gude/gude-dir# gude build (更新一下网站)

    演示站点: http://gd.bright.biz.st

    项目地址: https://github.com/JinnLynn/gude

    root@AR# mv ~/gude/ /usr/local/

    root@AR# cd /usr/local/gude/

    root@AR:/usr/local/gude# ls

    build  dist  docs  gude  gude-dir  Gude.egg-info  LICENSE  README.md  setup.py

    root@AR:/usr/share/gude# cd gude-dir

    root@AR:/usr/share/gude/gude-dir# ls content  deploy  privacy.yaml  README.md  site.yaml  static  theme

    root@AR:/usr/share/gude/gude-dir# cd deploy

    root@AR:/usr/share/gude/gude-dir/deploy# ls 404.html  article  atom.xml    page      sitemap.xml archives  assets   index.html  README.md root@AR:/usr/share/gude/gude-dir/deploy#

        如果你安装了nginx,则编辑nginx的配置文件nginx.conf(如果是用包管理器安装的,则nginx的配置文件为/etc/nginx/sites-enabled/default),在

    nginx的配置文件的最下面加上:
    server {  

    listen       80;  

    server_name  gd.smt.biz.st;     

    index index.html index.htm;     

    root   /usr/local/gude/gude-dir/deploy/;

    }
    然后重启nginx.以上,可看出,我绑定了域名gd.smt.biz.st到静态网站的根目录/usr/local/gude/gude-dir/deploy/,访问http://gd.smt.biz.st即可看到静态网站的效果。

    注意:nginx对权限管理较严格。如果你的网站目录是建立在/root/目录下,比如/root/gude/gude-dir/deploy/,那么绑定域名到该/root/下的目录,访问域名,会显示403 Forbidden.解决办法就是把该/root/下的目录复制或移动到其他目录,比如/usr/目录。