Script to generate tag, category and post archives for a Gemini gemlog in place from the post files themselves, rather than building from an external site.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Kelson Vibber f63ed87c7e update README 4 months ago
LICENSE Add MIT license 5 months ago update README 4 months ago Update README with directions for latest post list, bump to 0.4 4 months ago


Takes a collection of gemlog (Gemini log) posts and builds archives in-place (not with a source folder and a target folder) for time, tags and categories.

In case you're not familiar with it, Gemini is a a lightweight protocol that can be thought of as a more flexible Gopher or a vastly simplified web.

Project Gemini

Design goals

  • Simple as possible! (This is for Gemini, after all.) Though it is kind of drifting from that goal.
  • Use the standard format for gemlogs so that every tag, category or archive page can be subscribed to. Subscribing to Gemini Pages
  • Minimize templating and external configs. The posts themselves are the configuration.
  • Only change the tag/category/etc files by default, avoiding any risk of clobbering the posts themselves.
  • Only change the home page or post files if navigation has actually changed on that file, minimizing risk of clobbering.
  • Use a programming language that's already installed on most *nix systems. This is part of why I chose Perl instead of something newer like Rust or Go. (The other was that I already had an old site index generator that I could strip down and use as a basis for it.)

How to use

Use the 2021-01-15-filename.gmi naming convention for post files. The date will be extracted from the filename.

Put them all in one folder.

The titles, tags, and categories will be extracted from the post files. To add a new tag or category to the gemlog, just add it to the posts and the script will find it the next time it's run.

  • The site title is the first top-level heading in index.gmi.
  • The post title is the first top-level heading in the post.
  • Links in each post to files in the "tag" or "category" subfolders will be used to build the tag/category lists and archives.
  • Links in each post labeled "Next:..." or "Previous:..." will optionally be updated using date order.
  • The first list of links on the index page after the Latest Posts heading will be updated with the new latest posts.
  • All the navigation folders and labels can be configured in gemloginplace.config.

For example, the following markup will be a post with the title "Trying out Gemini". It will create a Gemini tag and a Technology category, and it will create archive files at tag/gemini.gmi and category/tech.gmi containing links back to this post.

# Trying out Gemini

Hey, look, I have a post!

=> tag/gemini.gmi Gemini
=> category/tech.gmi Technology

=> ./ Previous
=> ./ Next

Yeah, you can put stuff after the tag/category links, too.

And the following markup in index.gmi will set the site title "My Awesome Gemlog" and replace the first list of links with the latest posts.

# My Awesome Gemlog

Yeah, I have a gemlog now! cool, huh?

## Latest Posts
Want to know what's new? The links below here will be replaced every time I update the gemlog.

=> placeholder1.gmi
=> placeholder2.gmi

=> about.gmi About Me (this link will not be replaced)

Next/Previous links and the latest posts list are only updated in the posts if you specify --update-nav on the command-line or set ALLOW_WRITING_TO_POSTS in the config file. Again, this is to minimize the risk of clobbering your actual posts and home page.

Grab a copy of from Codeberg: gemloginplace

Run in the folder that contains your posts!


The script will run without configuration, but you can put a gemloginplace.config file in the log directory containing any of the following:


SITENAME: Your Site Name (if it should be different from the title in index.gmi)
HOME: Back to (SITENAME) (label for links back to the main page from the tags and category pages)



CATEGORY_PAGE_TITLE: Posts in ___ Category at (SITENAME)
TAG_PAGE_TITLE: Posts Tagged ___ at (SITENAME)
(The underscores will be replaced by the category or tag name)

Files and Folders

TAG_INDEX: tags.gmi
CATEGORY_INDEX: categories.gmi
POST_INDEX: posts.gmi

Other Options

LATEST_HEADING: ## Latest Posts

ALLOW_WRITING_TO_POSTS: 1 (to ALWAYS update next/previous links)
DEBUG: 1 (to turn on debugging output)


  • Code cleanup. (It's gotten kind of messy.)
  • Improve documentation and comments.
  • Auto-generate mailto link for each post.


2022-03-06 Version 0.4: Auto-Update Latest Posts!

  • The index will now update with latest posts when --update-nav is specified.

2022-03-05 Version 0.3: Configuration!

  • Formerly hard-coded labels and folders are now configurable through gemloginplace.config for phrasing or language.
  • Cleaner script output (with a DEBUG option to bring it all back).

2021-03-21 Version 0.2: Navigation

  • Update Next/Previous links if present in posts, but only if --update-nav is specified.
  • Get site name from index.
  • Use a configuration file.
  • Create tag and category subfolders if they don't already exist.

2021-03-04 Version 0.1: Initial release


Kelson Vibber,