GemPress is a framework to streamline publishing a Gemini Capsule, while also making it available as a common static website, for a broader audience.
At it's core, there's a simple
gemini-to-html tool, as well as an
atom feed generator, both of which written in C but intended to be executed as scripts using Sugar-C.
Sugar-Cis a tcc flavour (fork), that compiles C code on the fly 'as if' a scripting language out of the box and leans on
<sugar.h>library for doing simple text file procedures.
The code should be easy enough for others to customize to their needs, and contributions are also welcome. Some effort was put into trying to keep it simple and well documented.
Install Sugar-C from the GitHub repository, like:
git clone https://github.com/antonioprates/sugar.git
Note: you might have to use
sudo ./install.shdepending on your user permissions.
Alternative: use another C compiler see alternative setup section.
Then, just clone this repo:
git clone https://git.sr.ht/~aprates/gempress
Done, you should be good to go!
These are the standard markup conversions currently supported by
gmi-to-html (the core tool):
>, html escaped codes
=> internal links, converts path to *.html
=> external links, keeps original URL
# heading, also sets the page title
* list item
pre-formatted block enclosed in triple backtick (```)
See Solderpunk's Gemini Specifications, section 5 for
text/gemini media type reference.
GemPress offers 2 extra markup conversions (non-standard for Gemini), but those need to be explicitly enabled via configuration flag:
--- horizontal rule
code enclosed in backtick (`) - see limitations section
You can automatically append
gemini contents on all your pages. See
web-footer.gmi files under
There is a simple
style.css included under
template folder. Out of the box, it is provided as a dark-blue theme, but can be edited to tweak the outputted website look and feel.
You can create a capsule folder structure with a
capsule.conf auto-magically by using the wizard script, for example:
The wizard will ask for:
About the OAuth token see publish with SourceHut section. You may jump directly to
./publish auto if you have answered all the wizard's four questions, and have your page online.
From the project root create a copy of
capsule.conf and edit the parameters accordingly.
cp capsule-example.conf capsule.conf
Note: you can copy the template folder elsewhere and customize it or just set directly to the
templatefolder provided with this project.
Your configured contents
localBaseDir is expected to have the following structure:
├── index.gmi # Home
├── index.gmi # Archive (links to the posts)
Also, your configured
templateDir should be of the following structure:
├── gmi-footer.gmi # Appends to Gemini Capsule only
├── web-footer.gmi # Appends to Website only
publish script adds the first 5 links of the Capsule Archive to your Capsule Home, then the footer is appended afterwards. So your Home should end with something like:
## Capsule Feed
Here are my most recent posts:
For the publish action there are currently two modes supported.
Then, you get your Capsule built at
./capsule and a HTML Website clone under
Note: the script will overwrite
./websitefolder, so it's not recommended to edit HTML output. Rather the best solution would be to tweak the scripts.
You can also clean up those folders with:
capsule.confto add your
Once all is set, provided you have already done
publish local, run:
You can also
build local files + publish to srht + clean in one step:
Patches and questions? Send to my public inbox: ~email@example.com
For clarity, here INDEX means
log/index.gmi, the Archive's index, of which the feed is generated, and not the file on the root dir (Home).
The following steps describe the main
publish local process:
https atom feed from INDEX
web-footer.gmi to all files, except INDEX
back-to-Home-link to INDEX
gmi files to
gemini atom feed from INDEX
gmi-footer.gmi to all files, except INDEX
back-to-Home-link to INDEX
Note that, you should end up with two folders
./capsule ready to be published.
Also note that, the included
atom feed generator is a bit of a primitive tool and it expects the Archive's
log/index.gmi file to contain the list of links (=>), like:
=> /log/some-title.gmi YYYY-MM-DD Heading Of The Post
See the Gemini simple feed specification for
/log/index.gmi structure reference. Make sure that the URLs contain the date as the initial part of the description, as date is extracted from there. You may add normal gemini contents above, below or in-between, as any content not in that exact format will be ignored. The generator only cares about the links with description starting as YYYY-MM-DD when building the feed.
Unless backtick is the first or last character on the line, inline formatting of
code expects a blank space before the opening markup and a blank space after the closing. And this might not be the expected behavior for most people used to markdown text, therefore you CAN'T pre-pend or append those immediately with punctuation
Yet this helps to keep a straightforward and clean implementation. When writing your markdown, you can overcome this shortcoming of the underlying
gemini-to-html tool by simply adding an extra blank space where needed.
There is also a tag bleeding risk if you forget to close your backticks. The tool does a futile attempt to prevent the bleeding, by checking if the number of backticks is even in each line. But this provides no real guarantee that the
code tag won't bleed on the html source. You could check outputted HTML for validity if you are a bit paranoid, after each time you edit.
I might add config support for this feature in the future, but for now, if you want to turn it off, just comment out the
inline code implementation on the
lineToHTML function in case this is causing you any troubles.
You should be able to skip Sugar-C install if you prefer, but you will need to build the core tools from the C sources using whatever C compiler you have or prefer, by including sugar.h to this project.
Note: the bash scripts, internally calls Sugar-C to run the C scripts, so it assumes you have Sugar-C configured in your system. If not, you will have to manually update the bash scripts.
After compiling all
.c sources, update bash scripts to use the binaries instead of C scripting where applicable, like, for example:
< sugar src/gmi-to-html.c $filePaths
> bin/gmi-to-html $filePaths