biisan

biisan is a static site generator that can write documents in reStructuredText.

Feature

• Convert the structure of reStructuredText to the structure of object, and output to html with jinja2 template for each Directives of reStructuredText
• The default template is attached for the directives supported by biisan, but the template to be used can be replaced if the search destination is set in the configuration
• The conversion processor from directive to object can also replace any processor by setting
• The processing of the directive which is not supported is also possible by the same mechanism as replacement.
• Easy definition of new directives
• The process of converting the structure of reStructuredText to an object is performed in parallel in multiprocessing

quick start

Installation

It can be installed with pip. Since dependent libraries are also installed at the same time, you may want to create and install a virtual environment using venv if you want to be able to erase them cleanly.

$ pip install biisan

Initialize

Generate the basic structure of biisan and configuration file. There is a folder called biisan_data under the folder you have run.

Answer blog title, base URL, language code as it is asked. You can change it later in the configuration file.

$ 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

Finally, the environment variables required whenever using biisan are output. It is an environment variable that is always required when using biisan.

It is a setting framework setting of glueplate.

First Entry

Let's check the contents of the generated folder.

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

Inside the biisan_data folder there are two folders, data and out.

• data

  • biisan_local_settings.py

    setting file. It has been added to or overwritten in the Original file settings settings.

  • blog

    Put the reStructuredText file in this. It is good to make a folder so that it is easy to organize. The folder structure in the blog folder has nothing to do with the path of the output URL.

  • extra

    Put the file if you want to create a separate page from the date based entry. about is set by default. When newly added, add the definition of GLUE_PLATE_PLUS_BEFORE_extra to the setting file (data/biisan_local_settings.py).

    For example, if you put the file imusing.rst, define GLUE_PLATE_PLUS_BEFORE_extra in data/biisan_local_settings.py as follows.

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

    This is how glueplate works, ['imusing' before the extra setting in the original file settings file ',] Is added.

    See also Actual setting.

  • templates

    Put the template you want to overwrite. Like GLUE_PLATE_PLUS_BEFORE_extra, GLUE_PLATE_PLUS_BEFORE_template_dirs is defined in the configuration file, so first we will start looking for template files in this folder.

• out

  Html is output statically in this folder.
  

This is the first entry

Let's save as my_first_entry.rst in data/blog as follows. The file name may be anything before the file extension, as long as the extension is .rst.

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

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

Hello! world!

Build

The operation is done in the data directory (in biisan_data/data).

$ python -m biisan.generate

If you get an error like the following, it is because you have not set the environment variable displayed at the time of initialization.

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

If you have not set the environment variable, try setting again and executing the command again.

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

If you get the following error, the folder where you are executing the command is wrong. Let's execute it in biisan_data/data.

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

If it works, the output is as follows, so let's open it in a browser.

$ 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

The URL is composed of date and slug described in the entry. At this point, the data folder and the out folder are as follows.

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

Although the file name is index.html, it is assumed that it can be omitted by specifying the directory index of the Web server.

For example, https://www.tsuyukimakoto.com/about/ should be set to return index.html if the file name is omitted.

The entry path is created based on slug and date described in the entry rst file.

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

template

A template is provided for each directive. Put templates in the templates folder if you want to change the style etc.

Default template and real project template.

Deploy

Deploy the contents of out to an appropriate server. Don't forget to specify the directory index.