ShoujoA的使用说明

虽然基本算是多余,但是这里还是提供一份ShoujoA的使用说明。ShoujoA是您现在所见的这个博客的生成引擎,无数据库,使用Github flavor Markdown,只需要遵照几条简单的规则,就可以很容易地在本地通过vim/emacs等编辑器进行文本的写作。项目地址(我是不是说过了?)ShoujoA,有兴趣的话请务必围观(我是不是也说过了?)。对了,补充说明,ShoujoA只支持*nix系系统,并不支持windows。当然您可以把代码托管到一台linux的vps上,本地写好后上传到服务器上,在服务器上转换,就像我现在这个博客这样。最后,ShoujoA是纯命令行的程序,没有GUI……这样。

顺便说明,项目名字ShoujoA,如果我的渣日语没弄错的话,我本意是指少女A这个意思的。原因是很久以前我被某张叫做少年A的图坑过,印象深刻……项目中的主要部分的那个代码文件,是苹果蛋奶酥(apple souffle)。嘛,这倒是些无关紧要的细节……

目前的进度是,一般博客的功能是基本全做过了,虽然不排除有bug的可能性,但是我想就一般使用而言,bug应该不会太多,而且您如果反馈的话,我这里也会较快给出答复或者修改—-毕竟快暑假了?

于是下面是分点说明

  1. 安装

  2. 配置

  3. 书写规则

  4. 支持命令


安装

首先您需要通过git clone,在本地生成一份拷贝。git的话……应该不需要我再说明?总之是这个命令git clone git@github.com:SeavantUUz/ShoujoA.git。然后切到拷贝的ShoujoA文件夹,安装virtualenv,不过一般的linux发行版都是有这个东西的。请确定您有这个命令,最好通过tab补全来判断。如果没有的话,通过下面的命令来安装:

$ curl -O https://pypi.python.org/packages/source/v/virtualenv/virtualenv-X.X.tar.gz
$ tar xvfz virtualenv-X.X.tar.gz
$ cd virtualenv-X.X
$ [sudo] python setup.py install

安装好了之后,确定您在ShoujoA这个文件夹中,然后运行 virtualenv env 来建立一个叫做*env*的虚拟环境。请务必叫这个名字,否则您需要改源文件applesouffle.py中第一行的路径,虽然并不麻烦,但是毕竟是多余的步骤。然后运行 source env/bin/activate 来激活虚拟环境。virtualenv的虚拟环境中,都是自带了pip的,安装依赖相当方便。我已经在requirement里面写好了依赖,直接通过 pip install -r requirement.txt 安装依赖就好了。

看看您的shoujo.py的权限吧,如果不是740的话,改到740吧,当然您喜欢777也是可以的。

到此为止安装部分结束,如果没出现什么错误,那应该就是没问题的,不过应该也不可能出现什么错误吧?

配置

注意到您的文件夹中的那个config.yaml那个文件么?那个就是所有的配置设定。一点一点说吧。这里注意的是,由于配置这里我修改得相当频繁,所以有可能会出现错误,如果出现了任何一点bug,请务必向我告知。axdiaoqi220@gmail.com

  • 第一行叫做MAIN_PATH。这个总应该是一个绝对路径,它是所有文件的根目录,后面的outdir,backup_dir等文件夹都在这个路径下。而且如果配置到服务器上,这个路径也就是服务器的根路径。不需要在实际位置有这个文件夹,只需要填写就好了,文件夹会自动生成的。

  • 第二行叫做OUTDIR。未来生成的各种pages都是在这个文件夹里面的。其中page_0.html,archive.html,tags.html等都在这个文件夹下,然后所有的博文(posts),都在posts这个子文件夹下面。

  • 第三行叫做BACKUP_DIR,ShoujoA默认的,会对每个转换的文件进行备份,而这个文件夹,就是备份文件的位置。

  • 第四行是THEME_DIR,未来如果有更多主题的话,这个就可以指定使用的主题,但是目前就只有default这一个主题……哈,如果有谁愿意做主题的话,也请发邮件吧……当然默默地自用也随意。

  • 第五行NAME是您的网站的名字,没什么好说的。

  • 第六行ARCHIVE_TITLE是当您切换到archive之后,标题栏上显示的名字。

  • 第七行TAGS_TITLE和上一行差不多,不过是标签栏上显示的名字。

  • AUTHORHOMEPAGE我想您是不需要改的……当然您喜欢也随意。这个和最下面那个copyright显示相关。嘛,站在我的角度,是不希望您去改的……

  • DISQUS_SHORT_NAME是您如果希望的话,可以启动disqus的评论。这行需要填写的那个,是disqus给您的短链接,您需要首先有disqus的帐号才可以的。当然我自己后面是用了多说,因为disqus载入很慢。多说很快,但是不支持google帐号……自己斟酌斟酌吧。听说google也有一个评论组件,您喜欢的话,也可以使用。只需要用通用代码替换掉theme中template文件夹里面的post.html中最后的那几行javascript代码就好了。一般这样的社会性评论平台上文档都会写的。更新完了不要忘记使用 ./shoujo.py --updateTheme 去更新您的模板哦。忘记了这个,您怎么在模板中修改都是没用的……关于这个命令,我会在最后一部分说明的。

  • VERSION没什么用,您喜欢的话,改到100都无所谓。但是后面的POSTS_NUM可是有用的,它规定了每一页上能出现博文的数目。

  • DESCRIPTION是您网站的描述,这个会在生成的时候,自动变成您网站的meta的一部分。

于是配置讲解部分到此为止。

书写规则

为了能直接在本地进行博文的书写,我定义了几条特殊的规则。

您可能会疑问:我本来以为就是普通的markdown文法呢?

您是对的,实际上,博文内容的书写的确就是普通的markdown,但是可惜,一篇标准的博文可不仅仅有内容。比如标签,归档,摘要等,都需要通过某些手法实现。于是这就是下面几条规则的由来。请注意,如果没有严格按照写法来写,shoujo会毫不犹豫地抛出参数数目不足的异常。真是不温柔的少女呢。

  1. 每篇文章的第一行,会被视为这篇博文的标题。也就是说,博文的标题和它的文件名没什么必然的关系。

  2. 文章的第二行,是这篇文章的归档分类(archive),中英不限。特殊的,如果直接回车留空,或者键入几个空格之后回车留空,分类名会自动归为未命名

  3. 文章的第三行,是这篇文章的标签(tags)。每篇文章可能有多个标签,用,分割。中文和英文的逗号都可以。同样的,留白会自动归为未命名

  4. 文章的第四行,请直接回车留空。一方面,这样隔离了博文主题和配置,思路很清晰;另一方面,这一行可以辅助检测上面各行是否有错误。

  5. 四行之后会被认为是博文部分。这里也有一条规则:这部分出现的第一个空行,空行之上会被认为是摘要,也就是在page部分显示的那个。然后整体会作为博客的正文—-当然摘要和主体之间的空行会被删除的,不用担心。

于是以上就是书写规则部分。这里做一个小例子吧。

这是标题
归档分类
标签

摘要部分

正文部分

还是很简单的不是么?

支持命令

请注意,以下命令请切到ShoujoA文件夹去执行。

  1. ./shoujo.py --init 初始化命令,会根据配置文件初始化文件结构,通常安装好之后执行的第一条命令总是它。

  2. ./shoujo.py --post filename 最核心的提交文章命令,写好的文章通过这个就可以转换到html了。需要注意的是,其实这个命令支持多个文件的提交。也就是说 ./shoujo.py --post filename1 filename2 也是可行的。不过如果是一个文件夹的话,请使用下面提到的postAll命令。

  3. ./shoujo.py --postAll dirname 这个命令可以直接提交一个文件夹,值得注意的是,这个命令可以不带参数 ./shoujo.py --postAll 也是可行的。这样写的话,shoujo会把backup_dir作为输入的目录,这个其实挺有用的。

  4. ./shoujo.py --show 查看提交的博文,显示顺序是和网上显示顺序相同的。

  5. ./shoujo.py --remove index 通常和上一条命令配合用,删除一条记录,注意是彻底删除,也就是说,连备份文件夹中的这个记录都会被删掉的。

  6. ./shoujo.py --insert filename index 把一个文件插入到记录中,实质上包含了post这个命令了的。当然,filename可以是已经在记录中的文件名,也可以是不在记录中的文件名。如果需要改变显示的顺序,用这个命令吧。

  7. ./shoujo.py --updateTheme 更新您的主题文件,通常,一旦您更改了您的主题,都需要执行这条语句去确定更改。如果修改了主题却发现效果没有出现,联系我之前请先确认您执行过这条语句了吧……更新完了之后,通过 ./shoujo.py --postAll来批量重建吧。

于是上面就是支持的命令部分了,了解了么?


基本上,合理利用上面的命令,您就能解决大多数问题了。如果觉得效果有缺失,请联系我吧。

当然,您如果兴致勃勃地提交了一条博文,然后在本地打开生成的html(一切顺利的话),您可能会失望地发现:咦,为什么没有样式呢?没有样式,当然是样式表没正确载入啦,至于为什么我的路径是那样的,是因为本来路径就是为了nginx服务器所写的。下一篇会简单地讲到服务器和发布的问题~~

于是就这样了,阅读到这里的您辛苦了~~