biisan

biisan是一个可以编写reStructuredText文档的静态站点生成器。

特性

• 将reStructuredText的结构转换为对象结构，并使用jinja2模板输出到html，每个reStructuredText的指令都对应一个结构
• 默认模板已附上，支持biisan的指令，但如果在配置中设置了搜索目的地，则可以替换要使用的模板
• 指令到对象的转换处理器也可以通过设置来替换任何处理器
• 不支持指令的处理也可以通过相同的替换机制实现
• 轻松定义新指令
• 将reStructuredText结构转换为对象的处理过程在多进程中并行执行

快速开始

安装

可以使用pip进行安装。由于依赖库也同时安装，如果您希望能够干净地删除它们，您可能需要使用venv创建和安装虚拟环境。

$ pip install biisan

初始化

生成biisan的基本结构和配置文件。在你运行的文件夹下有一个名为biisan_data的文件夹。

根据要求回答博客标题、基本URL和语言代码。你可以在配置文件中稍后更改这些设置。

$ python -m biisan.main
? What's your blog title  blog title
? input your blog base url. like https://www.tsuyukimakoto.com  http:localhost
? input your blog language like ja  en

        Always set environment variable BIISAN_SETTINGS_MODULE to biisan_local_settings like bellow.

        $ export BIISAN_SETTINGS_MODULE=biisan_local_settings

最后，输出在始终使用biisan时所需的全部环境变量。这是一个在始终使用biisan时始终需要的环境变量。

这是glueplate的设置框架设置。

第一篇条目

让我们检查生成的文件夹内容。

$ cd biisan_data
$ tree
.
├── data
│   ├── biisan_local_settings.py
│   ├── blog
│   ├── extra
│   │   └── about.rst
│   └── templates
└── out

在biisan_data文件夹中，有两个文件夹，data和out。

• data

  • biisan_local_settings.py

    设置文件。它已经添加到或覆盖了在原始文件设置中的设置。

  • blog

    将reStructuredText文件放在这里。创建一个文件夹以便于组织是个好主意。博客文件夹中的文件夹结构不影响输出URL的路径。

  • extra

    如果你想从基于日期的条目创建单独的页面，请放置文件。默认设置为about。当新添加时，请在设置文件（data/biisan_local_settings.py）中添加GLUE_PLATE_PLUS_BEFORE_extra的定义。

    例如，如果你放置了imusing.rst文件，请在data/biisan_local_settings.py中按如下方式定义GLUE_PLATE_PLUS_BEFORE_extra。

    # Omitted
    
    settings = _(
        # 省略
        multiprocess = 8,
        GLUE_PLATE_PLUS_BEFORE_extra = [
            'imusing',
        ],
    )
    

    这是glueplate的工作方式，在原始文件设置文件中extra设置之前的imusing被添加。

    另请参阅实际设置。

  • templates

    放置你想覆盖的模板。像GLUE_PLATE_PLUS_BEFORE_extra一样，GLUE_PLATE_PLUS_BEFORE_template_dirs在配置文件中定义，因此我们首先将在这个文件夹中查找模板文件。

• out

  Html is output statically in this folder.
  

这是第一条条目

如下所示，在data/blog中将它保存为my_first_entry.rst。文件名可以是任何没有文件扩展名的内容，只要扩展名是.rst即可。

Is the first entry
=========================================================

:slug: my_first_biisan_entry
:date: 2019-05-05 13:00
:author: Your name

Hello! world!

构建

操作在data目录（在biisan_data/data中）进行。

$ python -m biisan.generate

如果你得到以下错误，是因为你没有设置初始化时显示的环境变量。

Traceback (most recent call last):
(Omitted)
KeyError: 'BIISAN_SETTINGS_MODULE'

如果你没有设置环境变量，请再次设置并再次执行命令。

$ export BIISAN_SETTINGS_MODULE=biisan_local_settings
$ python -m biisan.generate

如果你得到以下错误，是因为你执行命令的文件夹不正确。让我们在biisan_data/data中执行。

Traceback (most recent call last):
(Omitted)
ModuleNotFoundError: No module named 'biisan_local_settings'

如果一切顺利，输出如下，让我们在浏览器中打开它。

$ python -m biisan.generate
BIISAN 0.3.0
INFO:__main__:Write:(omitted)/biisan_data/out/blog/2019/05/05/my_first_biisan_entry/index.html
INFO:__main__:Write:(omitted)/biisan_data/out/about/index.html

URL由条目中描述的date和slug组成。此时，数据文件夹和输出文件夹如下。

.
├── data
│   ├── __pycache__
│   │   └── biisan_local_settings.cpython-37.pyc
│   ├── biisan_local_settings.py
│   ├── blog
│   │   └── my_first_entry.rst
│   ├── extra
│   │   └── about.rst
│   └── templates
└── out
    ├── about
    │   └── index.html
    ├── api
    │   ├── feed
    │   │   └── index.xml
    │   └── google_sitemaps
    │       └── index.xml
    ├── blog
    │   ├── 2019
    │   │   └── 05
    │   │       ├── 05
    │   │       │   └── my_first_biisan_entry
    │   │       │       └── index.html
    │   │       └── index.html
    │   └── index.html
    └── index.html

尽管文件名为index.html，但假设通过指定Web服务器的目录索引可以省略。

例如，https://www.tsuyukimakoto.com/about/应该设置为当省略文件名时返回index.html。

条目路径基于条目rst文件中描述的slug和date创建。

:slug: my_first_biisan_entry
:date: 2019-05-05 13:00

模板

为每个指令提供了一个模板。如果你想更改样式等，请将模板放在模板文件夹中。

默认模板和实际项目模板。

部署

将out的内容部署到适当的服务器。别忘了指定目录索引。