BottleMD is a static website generator (SSG) and content management system (CMS) for simple non-interactive websites, based on the projects Bottle and python-markdown. The idea behind developing BottleMD was to have a minimal SSG that is combined with a little web editor so I would not have to edit the website in a text editor each time.
BottleMD requires a basic Python 3 installation and on top the packages bcrypt, bottle, markdown.
They can be installed with pip via: pip install bottle markdown bcrypt
BottleMD is a single Python file.
The basic configuration of a website resides in the file bottlemd.cfg
.
If this file is not found, standard values will be used (see configuration).
Further than the configuration parameters, there is the sitemapfile
that defines the structure of the website.
sitemapfile
is a simple layered Markdown list of links that define the files to be used o
or the website.
BottleMD can be run from the shell, as a stand-alone webserver, or as a CGI script.
Requirement is always that bottlemd.cfg
is in the current working directory!
To generate a website from the shell, run the bottlemd.py
file:
./bottlemd.py
It will create the website according to the paths defined in bottlemd.cfg
bottle ships a simple webserver for development purposes that can be used to run BottleMD.
Run BottleMD with the -w
flag:
./bottlemd.py -w
This will start a webserver on your local host and tell you where to go, normally with a message like this:
Bottle v0.12.25 server starting up (using WSGIRefServer())... Listening on http://localhost:8080/ Hit Ctrl-C to quit.
The second line describes where you have to point your web browser to access the admin interface, in most cases this is http://localhost:8080/
BottleMD will run as a CGI when called from a webserver (determined by the varible QUERY_STRING
present in the environment).
Note that bottlemd.cfg
contains the salted and hashed password.
You should therefore always use the supplied .htaccess
when running in a compatible webserver or otherwise prohibit access to bottlemd.cfg
!
The configuration resides entirely in the file bottlemd.cfg
.
This filename cannot be altered.
The file consists of key-value pairs, separated by =
(space-equal-space).
The following parameters are defined:
installed
(default: False
)
When not set to True
, the web version will always drop you to the config screen so you can configure a user.
After the initially saved configuration, it will be set to True
.
sitemapfile
(default: sitemap.txt
)
The sitemap file that defines the website structure.
sourcedir
(default: www/
)
The directory in which the source files reside.
Below sourcedir
must reside the files defined in the sitemapfile
, but also the viewsdir
and according the sitetemplate
and navtemplate
.
viewsdir
(default: views/
)
The directory in which (below sourcedir
) the sitetemplate
and navtemplate
reside.
targetdir
(default: website/
)
The directory to which the website is built.
Either relative to the current working directory or absolute
sitetemplate
(default: site
)
The name of the file of the template for the overall page, residing in viewsdir
.
The name as given will have an added ending .tpl
.
E.g., for the value site
, the expected file is site.tpl
.
See Templating for details on the templating.
navtemplate
(default: nav%d
)
The name of the files for the template of the navigation, residing in viewsdir
.
The name as given will have an added ending .tpl
.
Note that this expects the argument %d
, i.e., the navigation depth.
When you have no multi-level navigation, you still have to add that value and an appropriate name, even if it always evaluates to 0
.
See Templating for details on the templating.
user
(default: `)
The user:salt+password string, as will be compared to
bcrypt.checkpw()after removing the user part.
You normally won't have to set this, as it will be set from the web interface.
The easiest way to set this in case of a lost password would be to set
installedto
False` and then re-configure the site.
The sitemap (given by the configuration parameter sitemapfile
) defines the structure of the website and the navigation.
The sitemap is a list of links that define how a file should be treated.
Any file that ends on .md
(Markdown) will be processed to HTML.
The link text is the name with which the file will be linked in the navigation.
When the link text is left empty, the file will not be linked.
An example:
* [Index](index.md)
* [Music](music.md)
* [Black Metal](blackmetal.md)
* [Death Metal](deathmetal.md)
* [Jazz](jazz.md)
* [BottleMD](bottlemd.md)
* [](bbs2000.md)
* [](empty_dreams.mp3)
* [](for_him.mp3)
This sitemap defines three first-level navigation items: Index, Music, BottleMD.
As they all end on .md
, they will be processed.
The three subitems of Music, Black Metal, Death Metal and Jazz are sub items of Music.
They will be processed as second-level navigation items, i.e., the template nav1.tpl
would be used.
The file bbs2000.md
will be transformed to HTML, but not linked in the navigation, as there is no link text.
The two files empty_dreams.mp3
and for_him.mp3
are not linked in the navigation and will not be processed, but they will be copied to targetdir
.
BottleMD uses the web framework Bottle for its templating engine. There are two main templates:
The site template (configured by sitetemplate
) should be the overall HTML template for the website.
The template must contain three strings:
{{!title}}
where the title will be inserted.{{!navigation}}
where the navigation will be inserted.{{!sitetext}}
where the text of the webpage will be inserted.The navigation template will normally be code.
It will be passed a list of tuples that consist of (link text, link target)
.
As the whole array is passed, some code will be necessary to render all the links.