Over the past month or so I've been adapting the Pelican static site generator to output Gemtext instead of HTML. I had previously created a Pelican plugin to achieve this, but that had a few disadvantages.
Gemican takes the functionality of the plugin and adds:
There's a lot of existing Pelican functionality that I didn't check, aside from the automated tests, such as the Wordpress import. If you find anything that doesn't work let me know on the issue tracker on Github.
Gemican is available on PyPI, so it should just be a matter of pip installing it:
pip install gemican
For markdown support, also install md2gemini:
pip install md2gemini
Create a new directory and run the quickstart tool to generate a directory structure, config files, and make files if necessary. It will ask you a bunch of questions about your capsule and how you want to deploy it.
mkdir capsule && cd - gemican-quickstart
Before you can run the dev server you will need to generate an X509 certificate for it to use. This command run in the root of the capsule directory should suffice to create the cert and key in the default locations:
openssl req -x509 -newkey rsa:2048 -sha256 -keyout key.pem -out cert.pem -days 365 -nodes -subj '/CN=localhost'
Once you add some content (in the content directory!), you can run a dev server to preview it on localhost port 1966 in your Gemini browser of choice.
gemican --listen --autoreload content
For more info on setting up, previewing and publishing, check out the documentation linked below.
I described the support for Markdown as "partial" above because it does not currently output good link descriptions for internal capsule links. md2gemini only seems to support using the URL or the [link text] as the description, but I think it would make more sense to use the alt text if one is provided. Since that wasn't a possibility I parked the Markdown support for now.
However, you can still pass any md2gemini configuration that you like to the Markdown reader if there are settings that work for you. To use `copy` style links which avoid this problem, for example, you could set the `MARKDOWN` settings like so in the gemicanconf.py
'MARKDOWN': {
'strip_html': True,
'plain': False,
'code_tag': "",
'links': 'copy',
},
One somewhat frivolous change I made was to add the option for an ASCII art header to the built-in themes. It's optional for a theme to use this (or any other setting), but if you define it in your gemicanconf.py it will be used if you are using one of the built-in themes.
SITEASCII = """ _______ __ | __|.-----.--------.|__|.----.---.-.-----. | | || -__| || || __| _ | | |_______||_____|__|__|__||__||____|___._|__|__| """
I adapted the documentation and it's available right here on this very capsule!
📅 Sat 02 October 2021