davep

md2gemtext - A library for converting Markdown to Gemtext

2026-08-16T14:43:04+01:00

Following on from html2gemtext, the inevitable has happened: I couldn't let the Markdown side of things remain unaddressed. While Rogallo v1.8.0 added some extra rendering of Markdown to make it look more "pretty", I felt it really needed to be handled so it had more utility. Being fully navigable, even by keyboard, seems more important than pretty tables.

So md2gemtext now exists as a library on PyPI. I have two plans for this. While I fully intend to shake up the Markdown support in Rogallo -- either replacing the use of the Textual Markdown widget to display it, or at least giving the user a configuration option to decide how Markdown is displayed -- I also want to pay some attention to my (currently rather simple) Gemini-based log and use this library to build a tool that will convert my blog's Markdown content into Gemtext that looks just how I want it.

As with html2gemtext, this is an early version of this library, and I'm sure there will be edge cases I'll have missed and will want to tidy up. But at the moment the results are looking promising.

I'm once again in a place where I'm actually half-seriously thinking that much of what Hike does could be built into Rogallo, if I were to simply add http(s) support there.

BagOfStuff v1.3.0

2026-08-16T09:05:47+01:00

For a wee while now I've been trying to nail down a weirdness with the navigation history in Rogallo. I never felt it was a difficult issue to deal with, but it was also one of those issues that I could never obviously recreate at will, and it only seemed to happen while I was busy working on something else.

Yesterday evening I finally managed to come up with a way to always recreate it and, having done so, the solution seems pretty straightforward¹. In order to implement the tweak I want, I need to be able to truncate the navigation history, and of course do so in a non-destructive way.

So the history classes in BagOfStuff v1.3.0 have grown clone and truncate methods. This will allow me to duplicate a history, truncate it at its current location, then save it, without affecting the working copy.

Why do I feel like I'll regret saying that? ↩

Port1900 - An async Python client library for the Nex protocol

2026-08-14T19:21:42+01:00

It's that time again. Time to add another small web protocol to Rogallo. This time it's one I stumbled across a few days ago: the Nex protocol. This one is very simple and straightforward and it seemed like a shame not to support it.

So, as I have with Gemini, Spartan, Gopher and Finger, I've added a dedicated library for dealing with the associated URI, and to provide a client for talking to the server.

The documentation can be found on the dedicated site.

GopherMap v1.0.0

2026-08-12T15:55:27+01:00

When I first created GopherMap, I made it pretty strict about what it did and didn't consider a valid map. Unsurprisingly, reality did what reality does and, pretty quickly, Rogallo met maps that didn't fit with this strict approach. So I relaxed things, accepting pretty much anything that even vaguely looked like a Gopher map. This solved the problem.

However, earlier today, I ran into a page that was obviously supposed to be plain text, but was being displayed in part like a map. The problem was my attempt at detecting a reply from a Gopher server that looked like it might be an error. This very relaxed approach to "this is likely some Gopher stuff, let's accept it as such" meant that a text file that had a 3 anywhere in the first column was tripping off the "this is likely some Gopher stuff and it looks like there's an error in there" check. The result? Treated like a Gopher map, converted into Gemtext, and displayed in the wrong way.

So... v1.0.0 has been released which adds some code to help out with this. The default parsing still works as before, but there's now a strict mode which will raise exceptions if some sort of significant problem is found. On top of this are a couple of helper class methods which check if some text is likely a valid map, and check if some text is likely a valid map containing an error.

With these in place, I can update Rogallo so that it's still pretty easy-going when it comes to showing Gopher maps, but isn't quite so laid-back when it comes to finding errors coming back from Gopher servers, and so incorrectly rendering the result.

html2gemtext - A simple library for converting HTML to Gemtext

2026-08-11T20:24:39+01:00

Yesterday evening, while tinkering with Rogallo, I managed to nerd-snipe myself pretty well. I was playing around with the idea of better presentation of some forms of text/* content. While, of course, Rogallo handles text/gemtext just fine, there are lots of other MIME types that it will show too (pretty much all within text/*). Already, if it can work out an appropriate language, the viewer will do syntax highlighting, and this includes Markdown files. However, Rogallo has a full Markdown widget built right in so I was experimenting with using that as the way to show Markdown content.

Nothing that clever really, all pretty obvious.

But then I got to thinking... In OldNews I heavily rely on html-to-markdown. Given I have a Markdown viewer to hand, if the user ends up trying to look at some text/html, why not convert it over to Markdown and render it that way? That's... doable.

There are, however, some problems with this idea:

As useful as html-to-markdown has been for OldNews, I've found it quite unreliable at times, with the occasional breaking change. I don't mention this as a negative about the project, but I don't want another one of my projects sitting on top of a moving target like that.
Dragging in a reasonably large dependency for what's likely to be a niche requirement doesn't quite feel right.
Textual's Markdown viewer has, to this day, one massive design flaw: links can't be navigated with the keyboard¹. I'm doing my absolute best to ensure that Rogallo is keyboard-first. Leaning on this widget for viewing Markdown is one thing, but leaning on the widget for other content types starts to erode that aim.

I did consider the idea of having this feature as an install option, so you'd be able to install rogallo and have it work as normal, or install rogallo[html] (or similar) and it would drag in the ability to render some HTML using this pipeline.

Then I realised: why target Markdown at all? I already have the code for rendering Gemtext, and that solves the keyboard navigation of links problem. How hard could it be to write something to convert HTML to Gemtext?

Turns out, at least for the requirements I have right now, not that hard!

html2gemtext is still in its infancy, but it's doing a passable job of turning most of the HTML I throw at it into reasonable Gemtext. I don't doubt for a moment that there are lots of pages out there that won't turn out right -- for varied values of right -- but so far the results are readable and navigable. The plan now is to keep improving as I run into new cases that could be handled better.

While I've not built this into Rogallo just yet, I think I will make use of it. I'm also giving serious thought to using it for my capsule. Over there I'm adding some posts from this blog and html2gemtext could form the basis of a tool to help automate some of that.

Right now I'm using a script I've written that wraps lowdown to do the Markdown to Gemtext conversion, but the result -- as good as it is -- isn't quite what I'd like. I'm thinking I could tailor the results exactly as I want if I go from this blog's HTML via html2gemtext.

Or, of course, given my blog is written in Markdown, I could next tackle my own just-how-I-need-it Markdown to Gemtext converter...

As for how this new library will go into Rogallo... Using it to render HTML that might be found kicking about in Geminispace or Gopherspace makes sense, I think. That should be enough. It's not like I really need to turn it into an http(s) browser too. Right? Right?!?

This mouse-only problem is a recurring theme in Textual. ↩

Sybaritic - A Spartan protocol library for Python

2026-08-07T19:27:00+01:00

Now that Rogallo supports multiple protocols, it's tempting to add one or two more. As of the time of writing, alongside Gemini, both Gopher and Finger are supported. While wandering the small web, I stumbled on the Spartan protocol. Given its similarity to Gemini and the fact it uses Gemtext as its main document type, adding it to Rogallo seemed like an obvious thing to do.

In aid of this, I've created Sybaritic. It is, in effect, a sibling library to Wasat, Port70 and Port79. As with the others, it is async-all-the-way and is designed to have a similar API.

With this in place, I can now extend Rogallo to handle spartan:// URIs as first-class citizens.

Gemtext v1.1.0

2026-08-07T16:33:03+01:00

I've released a small update to Gemtext. At the moment, I'm working on adding Spartan protocol support to Rogallo, and to do this I need to handle a small extension it makes to Gemtext.

While Spartan is quite different from Gemini in the underlying protocol, it uses Gemtext as the default/standard markup language, but with one small difference. To allow uploaded data that is initiated by the markup, rather than by the server, there is a =: line type. In some respects, this is similar to type 7 items in Gopher maps.

Rather than spin up a whole new library just to support this one small difference, and rather than do some special-case nonsense in Rogallo itself, I've added optional (and turned on by default) support for =:. When encountered, this results in a SpartanPrompt object, which simply inherits from a Link.

Any code that doesn't require this feature can turn it off with the with_spartan_support parameter.

Wasat v1.3.0

2026-07-30T16:04:09+01:00

A quick bump of Wasat to v1.3.0. This follows on from the work started in v1.2.0, improving how hybrid mode works and also making host certificate verification information available in the response object.

The main improvement to hybrid mode is that it's now a little more discerning about when to fall back on TOFU mode. Only if the CA route fails due to an untrusted root or a self-signed certificate does it then fall back to TOFU; otherwise, an exception is raised.

I've also added verification information -- such as the method used and the fingerprint -- to the response object. This will be useful in Rogallo if I want to show in the display how the current server was verified.

As a handy diagnostic tool, I've also added the verification method and the fingerprint to the verbose output of the library's CLI command.

$ wasat --verify-mode=hybrid -v gemini://astrobotany.mozz.us/ | head -7
--- Gemini Response ---
URI: gemini://astrobotany.mozz.us/
Verification Method: ca
Certificate Fingerprint: sha256:dafe13d51b1aff133dd153c6d66a1a15761020017daa69378aef6e0eefb75474
Status: 20 (SUCCESS)
Meta: text/gemini
-----------------------

$ wasat --verify-mode=hybrid -v gemini://tilde.team/~davep/ | head -7
--- Gemini Response ---
URI: gemini://tilde.team/~davep/
Verification Method: tofu
Certificate Fingerprint: sha256:239f2642895698fbd16bd6fc59f2361caf6b7449a37d861d86936978c175bf78
Status: 20 (SUCCESS)
Meta: text/gemini; lang=en
-----------------------

With these changes in place, I think I'm set for making some improvements to Rogallo relating to host certificates.

Wasat v1.2.0

2026-07-30T08:45:09+01:00

I've just released Wasat v1.2.0. This release aims to help out with a change I want to make in Rogallo in relation to certificate verification.

The issue is that, until now, Wasat offered either ca or tofu as verification modes. Meanwhile Rogallo was using tofu. Long story short: this meant that sometimes some sites looked like they were changing fingerprint way more often than you'd expect. The obvious solution here is to first check if a site can be validated via the ca route and, if not, fall back to the tofu route. This sort of change could have been made in Rogallo itself, but it would have been inelegant. Rogallo maintains a single Gemini client object, and the verification mode is baked in when the object is created. To move to this "try one way then the other" approach would have meant either maintaining two instances of the object, or tearing it down and making another each time we connected to a capsule.

Nah.

So the verify_mode of the Client has grown a new option: hybrid. When set to hybrid, the client will do the dance mentioned above: it will try and see if ca will work and, if it does, it will take that approach. If it fails, it will then fall back on pure tofu.

Out of the box, the defaults for the client are the same (it uses ca by default), and for the moment Rogallo is still hard-baked to tofu; given this, there should be no change in how things work when Wasat is updated. Now that this is up on PyPI, I'm going to pin Rogallo's use of wasat to >=1.2.0 and then, in an update, I'll swap over to hybrid. Hopefully this will result in a smoother journey when using sites like AstroBotany and Station.

ℹ️ Note

While writing this, I've noticed that there's one change I still need to make to this hybrid flow. I realised that, at the moment, any kind of CA failure will result in a fallback to TOFU. That's not ideal and needs refining. All part of the learning process.

PS: If you're wondering what happened to v1.1.0 of Wasat... there wasn't one. While preparing this release, I was also fighting with the fact that my MX Mechanical Mini keyboard seemed to be dying (and its battery does seem to be dying) and, because of that, managed to bump the version from v1.0.1 to v1.2.0. Oh well...

GopherMap v0.2.0

2026-07-28T16:48:01+01:00

A quick little update to GopherMap. v0.2.0 greatly relaxes the validation of incoming lines, being a lot less fussy about missing tab characters and also about fully empty lines.

In the first take on this I was being pretty strict but, unsurprisingly, there are sites out there with likely-malformed maps that should otherwise work if you're chill about their mistakes.

I've got no desire for Rogallo to be harsh in this respect, so here's a much more relaxed version of GopherMap.

As of right now, the exceptions that are defined in the library are never raised. I've left them in for the moment because there's a window of time between this version being pushed to PyPI and Rogallo being updated (it does use the exceptions), where failure to supply them would cause Rogallo to crash under normal circumstances (nobody wants an unnecessary ImportError). Once I've updated Rogallo to pin a new lower bound, and removed use of the exceptions, I'll remove them from GopherMap.

GopherMap - A simple library for parsing Gopher responses

2026-07-27T19:20:30+01:00

Having spun up Port70 as a support library for my effort to add gopher support to Rogallo, the next thing I needed was some code to parse the "gopher map" responses that you get back from Gopher servers. While this could have been some code in Rogallo itself, much like with Gemtext, it seemed sensible to put it in its own library so it could be useful elsewhere.

So... GopherMap v0.1.0 is a thing. Its main provision is a class called GopherMap, which is used to parse some text you give it. Its items property is then a tuple of GopherItem objects. Each one of those objects has a type property which can be used to check the type of the resource.

Because Rogallo heavily relies on MIME types to make decisions about what to do with content, each ItemType has a best-efforts-guess mime_type associated with it. This will make it pretty straightforward for me to decide if a resource from a Gopher server is something Rogallo can display.

All of this has prompted me to have a go at creating my own little Gopher site to help with testing. As with my wee Gemini capsule, this is all thanks to tilde.team.

Port70 - A Gopher protocol library for Python

2026-07-26T11:32:33+01:00

It was, of course, inevitable that this would happen. After spinning up Port79 so that I could add finger support to Rogallo, it made sense that I start to think about Gopher support too. So here we go: Port70, a similar library for async interaction with Gopher servers.

This is going to be a bit of an adventure for me. While I'm long familiar with the existence of Gopher, and I'm fairly certain I used a client once or twice back in the 90s, I've never really had dealings with the protocol so know very little about it. Which is a good thing: something new (old?) to learn.

My plan with this is to add the GopherURI class to the list of URI types that Rogallo understands and handles and then provide a method of displaying and navigating the result. I think the cleanest and easiest way of doing this will be to add some code that transforms a menu response into gemtext and then just let the viewer widget display it as normal; each of the links in the menu being turned into gopher:// URIs.

This should be fun to play with. I'm looking forward to pulling it all together.

Port79 v1.0.0

2026-07-25T14:25:04+01:00

I've just bumped Port79 to v1.0.0. There's no significant change in this release, other than the addition of the usual dunder-based metadata that is common in Python libraries; somehow I'd managed to leave it out in the last couple of releases.

Now that I've successfully added finger support to Rogallo, and the library is working out well, there didn't seem much point in letting it hang around in zero-point-whatever-land.

Port79 v0.2.0

2026-07-23T11:04:54+01:00

A quick update to Port79. When I kicked this off I'd set up the FingerURI class so that it was pretty permissive in what it would accept. So, for example, you could do any of:

>>> FingerURI("davep")
FingerURI('finger://davep/')
>>> FingerURI("davep@example.com")
FingerURI('finger://example.com/davep')
>>> FingerURI("finger://example.com/davep")
FingerURI('finger://example.com/davep')

Nice and handy, right? Accept pretty much any input and turn it into a finger URI. However, once I started to add finger support to Rogallo, I realised that this wasn't as helpful as I'd like as it meant I couldn't use it to actually check for a valid URI. It would be more useful to have the class be strict about only being passed finger: URIs.

So now, the first two examples give an error.

>>> FingerURI("davep")
port79.exceptions.URIError: Invalid URI scheme: ''. Expected 'finger'
>>> FingerURI("davep@example.com")
port79.exceptions.URIError: Invalid URI scheme: ''. Expected 'finger'

Instead, if you want the more relaxed approach, you should use the from_string method.

>>> FingerURI.from_string("davep")
FingerURI('finger://davep/')
>>> FingerURI.from_string("davep@example.com")
FingerURI('finger://example.com/davep')

With this change I can confidently use FingerURI to test if any given input is an actual finger URI, and this also makes it work in a similar way to GeminiURI in Wasat.

Wasat v1.0.0

2026-07-21T19:10:21+01:00

While I'm having a moment of calling code stable, I've bumped Wasat to v1.0.0 as well. There's no actual difference here when compared to the last release, other than the development status classifier in the PyPI metadata and the version number.

The library feels pretty stable at this point. I've been using Rogallo every day for a wee while now and I've seen no surprising problems.

Port79 - A finger protocol library for Python

2026-07-21T16:19:20+01:00

Now that Rogallo is starting to settle down somewhat, with all the main Gemini Protocol work falling into place, I've been thinking about adding one or two adjacent protocols. The two most common and obvious ones are Finger and Gopher. While I'm still undecided about adding the latter, the former seems like a fun one to include (if only because I've had an account on plan.cat for around four years now).

With that in mind, much like I did with Wasat, I wrote a spec for what I wanted and pointed Antigravity at it. The result is Port79. As well as providing a library, there's also a small finger clone CLI, which can be run with python -m port79 (if it's installed as a library) or with port79 (if installed along with any command scripts).

$ port79 davep@tilde.team

hello [removed],

Project:
  Rogallo: https://rogallo.davep.dev/

Plan:
  Currently building gemini://tilde.team/~davep/

Pronouns: he/him

$ port79 davep@plan.cat
Login: davep                            Name: Dave Pearson
Directory: /home/davep                 Shell: /bin/plan.cat
Last login Mon Jul 20 19:06:33 2026 UTC
No Mail.
Plan:
Rogallo v0.12.0, with some more QoL changes:
https://blog.davep.org/2026/07/20/rogallo-v0-12-0.html

To be clear: this isn't intended to be a serious finger command (like, why would anyone even need that?), it's just a tool within the library that can be used to do some testing within a development (v)environment.

At some point soon I'll be adding port79 as a dependency of Rogallo and adding finger as a "native protocol".

Wasat v0.8.0

2026-07-18T10:23:11+01:00

Wasat v0.8.0 is now available. This provides a small update to the GeminiURI class, adding three utility properties for extra URI manipulation.

without_query - gives the URI minus any attached query
parent - gives the parent path of the current URI (also minus the query)
root - gives the root path for the current URI (also minus the query)

In each case, the result is a fresh GeminiURI instance.

These are added because I'm aiming to add "go to parent" and "go to root" commands to Rogallo.

Wasat v0.7.0

2026-07-16T17:07:52+01:00

The Gemini Protocol makes it clear that the maximum length of a URI, when making a request, is 1024 bytes. This has implications for how large a user's input can be when responding to a 1x response. Because of this, I'd like to update Rogallo so that it lets the user know how much space they have left as they type in their input.

With this in mind I've released v0.7.0 of Wasat. This adds the following to GeminiURI:

GeminiURI.MAXIMUM_LENGTH -- a constant for the maximum length of a Gemini URI (as mentioned above: 1024).
len() support -- if you ask for the len of an instance of GeminiURI it will return the length of the full URI.
GeminiURI.bytes_left is a property that tells you how many bytes are left until the limit, given the current URI.
GeminiURI.too_long is a boolean property that flags if the current URI is too long to send to a Gemini capsule.

This should give me all I need to add some guardrails to the user input dialog in Rogallo.

Gemtext v1.0.0

2026-07-16T08:58:50+01:00

I've bumped Gemtext to v1.0.0. I've gone from "this is test code" to "this is stable code" mostly because the library is so simple and I'm unlikely to add any radically new features to it¹.

This bump also has one small addition: I've added an alt_text property to the PreFormatted class. This exists to capture and make available any text that comes after the pre-formatted text marker. For example, this text:

```python
print("Hello, World!")
```

will now result in:

PreFormatted(content='print("Hello, World!")', alt_text='python')

If/when I add syntax highlighting of pre-formatted text blocks to Rogallo, this new property will make that possible.

I was thinking about adding a Gemtext builder class at some point, but I can't see a use for it any time soon. Perhaps v2.0.0. ↩

Wasat v0.6.0

2026-07-14T12:14:35+01:00

Wasat v0.6.0 is now available. This is another quick update that fixes a small typing issue and also adds a handy new method I've been meaning to add to GeminiURI.

The typing issue is a simple enough one. The __init__ method for GeminiURI can take either a string or another GeminiURI as its argument. However, the type was actually specified as str | Self. In Rogallo, I want to have a sub-class of GeminiURI for one particular purpose, which will be passed an instance of GeminiURI. Something like this:

class KnownHost(GeminiURI):
    """A known host."""

From this, I want to be able to do:

[KnownHost(host) for host in self.known_hosts]

where known_hosts is typed as list[GeminiURI]. At this point, the type checker complains:

Argument 1 to "KnownHost" has incompatible type "GeminiURI"; expected "str | KnownHost"  [arg-type]

The error is correct, because the use of Self is saying "this needs to be an instance of my class". There's no reason why it needs to work this way, so I've relaxed the type to str | GeminiURI. In my example above, KnownHost is a subclass of GeminiURI, so the type checker will be happy again.

The new method I've added is GeminiURI.with_default_scheme. This is a class method that acts as a more relaxed "constructor" for a GeminiURI. Again, in Rogallo, there are a few places where I'm taking some input, assuming it's going to be a gemini:// URI, checking if it's missing the scheme prefix, and then prefixing the string with gemini:// before creating a GeminiURI¹. This means that Rogallo contains a few instances of this sort of code:

if ...: # ...we should treat some text as a URI but it isn't prefixed with "gemini://"
    uri = GeminiURI(f"{GEMINI_PREFIX}{text}")

It's a small difference, but from now on I'll be able to:

uri = GeminiURI.with_default_scheme(text)

This removes the need to check if there's a scheme already and it saves me having to import GEMINI_PREFIX, etc.

GeminiURI will deliberately raise an exception if the scheme isn't gemini. ↩