Sometimes you design a system. And sometimes you make a series of vaguely related decisions over five years and eventually realise that, quite by accident, you’ve designed a system.

I think I’ve just done the latter.

Back in February 2021, Gabor Szabo wrote an article called Perl modules with their own web sites. He pointed out that a number of the larger Perl projects had websites of their own, in addition to their pages on MetaCPAN, and wondered whether this was something that more CPAN modules could benefit from.

I liked the idea. In fact, I liked it enough that later the same day I wrote Simple CPAN module web sites with GitHub Pages.

My argument was basically that GitHub Pages made this almost embarrassingly easy. If your CPAN distribution was already on GitHub, then you already had almost everything you needed. Turn on GitHub Pages, put some content in the repository, and a few minutes later your module could have a website.

At the time I wrote:

I think that anything which increases the amount of up-to-date Perl content on the web is a good idea.

Five years later, I still think that’s true.

Attempt one: automate everything

Of course, being a programmer, I immediately decided that something which took less than five minutes clearly needed automating.

A few months later I released App::CPANModuleSite, which attempted to generate a useful website for a CPAN distribution. I wrote about it in Easier web sites for CPAN modules.

It worked.

Nobody used it.

That’s fine. Not every experiment needs to become an indispensable part of the Perl ecosystem. App::CPANModuleSite is one of those projects that seemed like a good idea at the time but didn’t really go anywhere.

But the underlying idea never quite went away.

Meanwhile, the modules moved house

A couple of years later I made another, apparently unrelated, change.

For years, the Git repositories for my CPAN distributions had lived alongside everything else in my personal GitHub account. In 2023 I decided that wasn’t particularly useful, so I created a GitHub organisation called davorg-cpan and started moving my CPAN repositories there.

I wrote about the reasons for doing that in GitHub Organisations.

It separated my CPAN work from all the other random things in my GitHub account and gave the distributions a useful identity of their own.

And, importantly for what happened later, GitHub organisations get GitHub Pages sites just like users do.

So I created one.

Eventually I gave the organisation site a custom domain: it lives at cpan.perlhacks.com

I didn’t do very much with it. It existed. It listed some modules. That was about it.

But one useful piece of infrastructure was now in place.

Your README is already a website

Earlier this year I returned to another idea I’d been playing with: for many small software projects, the README already contains almost everything you would want on a simple project website.

So why maintain both?

I wrote a GitHub Action called readme-to-index. I described the idea in Your README is Already a Website.

It takes a repository’s README, runs it through Pandoc, adds Simple.css and publishes the result as a very simple single-page website using GitHub Pages.

There’s deliberately not much to it. No Jekyll configuration. No theme to maintain. No second copy of the documentation. The README remains the source of truth. Push a change to the README and the website changes with it.

I’ve now used it on several of my CPAN distributions, including App::HTTPThis, MooX::Role::SEOTags and WebServer::DirIndex.

And that’s when I noticed something rather pleasing.

The bit I hadn’t planned

A GitHub organisation Pages site normally lives at:

https://organisation.github.io/

A project site within that organisation lives underneath it:

https://organisation.github.io/project/

But GitHub Pages also lets the organisation site have a custom domain.

Mine is:

https://cpan.perlhacks.com/

And the individual project sites don’t have their own CNAME files. That means they simply inherit the organisation site’s domain. So the module sites automatically appear at addresses like:

https://cpan.perlhacks.com/app-httpthis/

https://cpan.perlhacks.com/moox-role-seotags/

https://cpan.perlhacks.com/webserver-dirindex/

No additional DNS configuration. No new domains. No CNAME management for individual projects. Move a CPAN distribution into the organisation, add the readme-to-index workflow, enable GitHub Pages, and it becomes another part of the same family of sites.

And suddenly I realised I’d accidentally built almost exactly the thing I was looking for in 2021.

A CPAN neighbourhood

MetaCPAN remains the canonical place to find information about my distributions. I’m certainly not trying to replace it.

But MetaCPAN has to present every distribution in approximately the same way. That’s one of its strengths.

A project’s own site serves a slightly different purpose. It’s somewhere I can send someone who just wants to know what this thing is and how to use it. It can emphasise examples and introductions rather than package metadata. And, perhaps most importantly, it gives the project a URL that looks like it belongs to the project rather than to a hosting service.

What I particularly like about the current arrangement is that the individual sites also clearly belong together.

They’re not a collection of unrelated domains. They’re a little CPAN neighbourhood: cpan.perlhacks.com with each distribution living underneath it.

The organisation provides the namespace and domain. GitHub provides the hosting and deployment infrastructure. readme-to-index turns documentation I’m already maintaining into the website.

There’s very little left to maintain.

Five years of accidental architecture

None of this was planned.

In 2021, I experimented with GitHub Pages because Gabor suggested that more CPAN modules should have websites.

Then I wrote a tool to automate that and discovered that nobody particularly wanted it.

In 2023, for largely unrelated reasons, I moved my CPAN repositories into a GitHub organisation.

Then I created an organisation Pages site.

Then I attached a custom domain to it.

Then, earlier this year, I wrote a GitHub Action for turning READMEs into tiny project websites.

Each decision made sense on its own.

Put them together and I now have a system where adding a website to one of my CPAN distributions is almost trivial, and every new site automatically becomes part of a consistent collection under cpan.perlhacks.com.

Sometimes architecture comes from diagrams, planning meetings and carefully written requirements. And sometimes you look back at five years of tinkering and discover that you’ve accidentally built something useful.

So over the next few weeks I’m going to start adding readme-to-index to more of the distributions in the davorg-cpan organisation and putting a bit more effort into the organisation site itself.

But perhaps you could do the same thing.

I bet your CPAN distribution already has a README. It might even be written in Markdown. If so, why not spend fifteen minutes turning it into a website?

You don’t need to design anything. You don’t need to maintain another copy of your documentation. And you don’t even need to pay for hosting.

Your README is already a website.

You just need to publish it.