Man page
gresiblos — a simple private blogging system.
Synopsis
gresiblos [-d DESTINATION] [-t TEMPLATE] [-e EXTENSION]
[-s STATE] [--index-output INDEX_OUTPUT]
[--chrono-output CHRONO_OUTPUT] [--alpha-output ALPHA_OUTPUT]
[--to-html] [--markdown] [--degrotesque]
[--topic-format TOPIC_FORMAT] [--index-indent INDEX_INDENT]
[--date-format DATE_FORMAT] [--rss-output RSS_OUTPUT]
[--atom-output ATOM_OUTPUT] [--feed-title FEED_TITLE]
[--feed-site FEED_SITE] [--feed-description FEED_DESCRIPTION]
[--feed-editor-email FEED_EDITOR_EMAIL]
[--feed-editor-name FEED_EDITOR_NAME]
[--feed-language FEED_LANGUAGE]
[--feed-copyright FEED_COPYRIGHT] [--feed-utz FEED_UTZ]
[--version]
input
gresiblos -c FILE input
gresiblos [-c FILE] [-d DESTINATION] [-t TEMPLATE] [-e EXTENSION]
[-s STATE] [--index-output INDEX_OUTPUT]
[--chrono-output CHRONO_OUTPUT] [--alpha-output ALPHA_OUTPUT]
[--to-html] [--markdown] [--degrotesque]
[--topic-format TOPIC_FORMAT] [--index-indent INDEX_INDENT]
[--date-format DATE_FORMAT] [--rss-output RSS_OUTPUT]
[--atom-output ATOM_OUTPUT] [--feed-title FEED_TITLE]
[--feed-site FEED_SITE] [--feed-description FEED_DESCRIPTION]
[--feed-editor-email FEED_EDITOR_EMAIL]
[--feed-editor-name FEED_EDITOR_NAME]
[--feed-language FEED_LANGUAGE]
[--feed-copyright FEED_COPYRIGHT] [--feed-utz FEED_UTZ]
[--version]
[input]
gresiblos --help
gresiblos --version
Description
gresiblos is implemented in Python. It is started on the command line.
gresiblos reads one or multiple text files and embeds them into a template. The entry/entries to process are a mandatory argument. Multiple entries can be given divided by a ‘,’. Wildcards are accepted as well, so giving ./entries/*.txt will process all files with the extension .txt within the folder entries.
The template file to use is defined using the option --template <TEMPLATE> / -t <TEMPLATE>. If not given, the default template is used.
Generated pages are saved as .html-files per default. You may change it (e.g. to php) using the option --extension <EXTENSION> / -e <EXTENSION>.
The path to store the generated pages into can be defined using the option --destination <PATH> / -d <PATH>. The default is ./.
Besides the generated entries, gresiblos may generate a JSON-index file that lists the entries with some meta-information. The option --index-output <FILE> will generate the index and save it under the given file name. The index is usually stored as plain JSON in a single line. For a prettier output, the indentation can be changed using the option --index-indent <INT>.
In addition, files containing the list of converted files can be generated. The lists are embedded into the content section of the template file. Use the option --chrono-output <FILE> to generate a file with the entries sorted in chronological order and/or the option --alpha-output <FILE> with the entries sorted alphabetically.
To perform a basic conversion of the contents to HTML, use the option --to-html. This will embed lines into <p>-tags and embed links into <a>-tags. Markdown files can be converted using the option --markdown. When set, the content, the title, and the abstract will be converted. Use the option --degrotesque to apply the degrotesque type setter on the contents before embedding them. Please note that you need to install markdown and/or degrotesque by yourself.
When embedding the meta-information of single blog entries into the template, the topics are split and rendered individually before being embedded. To allow for using them as links, the rendering format can be set using the option --topic-format <TOPIC_FORMAT>. Please note that this string should include something like “[[:topic:]]”, what is replaced by the topic itself. The date meta information is assumed to be in ISO-format (e.g. 2025-01-08 19:26:00), but may be adapted using the option --date-format <DATE_FORMAT>.
The entries may include the meta-information state. You may filter entries to process by setting the option --state <STATE> / -s <STATE> to the one that shall be processed.
gresiblos generates an RSS 2.0 feed if the option --rss-output <FILE> is set and writes it into <FILE>. It generates an Atom feed if the option --atom-output <FILE> is set and writes it into <FILE>.
Further options should be set when generating feeds for supplying needed information. --feed-title <STRING> sets the title of the feed, --feed-site <STRING> the URL of the feed (without the file name which is generated from ), --feed-description <STRING> sets the feed description, --feed-editor-email <STRING> sets the editor's e-mail address and --feed-editor-name <STRING> the editor's name. --feed-language <STRING> sets the feed's language, --feed-copyright <STRING> sets the copyright information about the feed, and --feed-utz <STRING> sets the feed's time zone. The defined language must match the ISO 639 specification.
The options can be stored in a configuration file which can be passed to gresiblos using the option --config <CONFIGURATION> / -c <CONFIGURATION>. Options given on the command line will overwrite the options set in the configuration file.
Arguments and options
gresiblos requires one parameter:
- input: The files (entries) to read, separated by ‘,’; accepts wildcards as well
gresiblos can be started with the following options:
- --config <CFG_FILE> / -c <CFG_FILE>: Reads the named configuration file
- --destination <PATH> / -d <PATH>: The path to store the generated file(s) into
- --template <TEMPLATE_FILE> / -t <TEMPLATE_FILE>: Defines the template file to use
- --extension <EXTENSION> / -e <EXTENSION>: The extension of the built file(s)
- --state <STATE> / -s <STATE>: The state the entries must have for being processed
- --index-output <FILE>: Writes the index to the named file
- --chrono-output <FILE>: Writes the named file with entries in chronological order
- --alpha-output <FILE>: Writes the named file with entries in alphabetical order
- --to-html: If set, basic HTML tags are added
- --markdown: If set, markdown is applied on the contents
- --degrotesque: If set, degrotesque is applied on the contents, the abstract, and the title
- --topic-format <TOPIC_FORMAT>: Defines how each of the topics is rendered
- --index-indent <INT>: Defines the indent used for the index file
- --date-format <DATE_FORMAT>: Defines the time format used
- --rss-output <FILE>: Writes an RSS 2.0 feed to the named file
- --atom-output <FILE>: Writes an Atom feed to the named file
- --feed-title <STRING>:Title to use for the feed
- --feed-site <STRING>: Base URL used to prefix entry filenames in the feed
- --feed-description <STRING>: The feed description
- --feed-editor-email <STRING>: The email of the feed editor
- --feed-editor-name <STRING>: The name of the feed editor
- --feed-language <STRING>: The language of the feed
- --feed-copyright <STRING>: The copyright information about the feed
- --feed-utz <STRING>: The feed's time zone
- --help / -h: Show a help message
- --version: Show the version information
Examples
gresiblos ./entries/*
Generates pages using the default template ./data/template.html and the blog entries located in entries and writes them to ./gresiblos_out.
gresiblos ./entries/* -d ./my_blog/
Generates pages using the default template ./data/template.html and the blog entries located in entries and writes them to ./my_blog.
gresiblos --template mytemplate.html --state release ./entries/*
Generates pages using the template mytemplate.html and the blog entries located in entries and writes them to ./gresiblos_out. Processes only entries with state=release.
gresiblos ./entries/* --rss-output atom.xml --rss-output atom.xml
Generates pages using the default template ./data/template.html and the blog entries located in entries and writes them to ./gresiblos_out. Generates an RSS 2.0 and an Atom feed containing the read entries. Please note that the options starting with --feed should be set for obtaining complete and valid feeds.
gresiblos -c my_blog.cfg
Reads settings from the configuration file my_blog.cfg and processes as defined therein.
Files
gresiblos comes with a default template.
As well, gresiblos uses templates for generating the feeds. For both, RSS and Atom, files that contain the feed's head and tail, as well as files for the entries are used, respectively.
All files are located in the folder ./data/ which is located in the same folder as ./gresiblos.py/.
Diagnostics
gresiblos uses the following exit codes:
- 0: no issues / finished successfully
- 1: at least two of the read entries have the same output name
- 2: one of the set options is not valid
- 3: the given template is broken; check whether all opening / closing tags match
Errors are reported on the command line.
Bugs and caveats
- When setting --date-format <DATE_FORMAT>, all entries must use this date format.