Simple CPAN module web sites with GitHub Pages

Gabor asks if it's a good idea for CPAN modules to have their own web sites apart from their listings on MetaCPAN. I think that anything which increases the amount of up-to-date Perl content on the web is a good idea, so I wholeheartedly agree with this idea. I started to wonder about the simplest way to get something like that online. And (as in so many cases when I'm wondering about the easiest way to build a web site) the answer seems to be GitHub Pages.

Every account on GitHub gets a web site on GitHub pages. The default address is https://<account>.github.io/ and you can control what is displayed on that page by creating a repo called "<account>.github.io" (for example, mine is called davorg.github.io) and editing the content in there.

On top of that, you get another site for each repo in your account. The default address for the site is https://<account>.github.io/<reponame> and the content is stored in the repo itself. There are a few ways to store the content in the repo - I'm going to look at the method I've been using for some of my repos. It'll take less than five minutes to get a basic site up and running.

As an aside, in the previous paragraph, I talked about "the default address" for these sites. That's because it's very easy to set up a custom domain for either your account site or an individual repo site. For example, my account site uses the custom domain https://davorg.dev/.

So let's create a simple web page for one of my CPAN modules. I've chosen MooX::Role::JSON_LD. Its repo is at https://github.com/davorg/moox-role-json_ld.

We start by going to the settings for the repo. Towards the bottom of the options page, you'll find a "GitHub Pages" section that looks like this:

I find it easiest to keep the web page in the same branch as the actual code, so I choose "master" as the branch ("main" for newer repos) and then "/docs" as the directory. Once you hit "Save", you'll see a few more options:

"Custom Domain" is where you'll add a custom domain if that how you want to run the site (this will have the effect of creating a file called CNAME containing the domain name). And you'll definitely want to turn on "Enforce HTTPS" because we all want to promote a secure internet, don't we?

And then there's "Choose Theme". This allows you to control the basic look and feel of the new site. I usually choose "Minimal" because, well, I'm a bit of a minimalist.

Once you've selected the theme you'll find yourself on a page where you can edit the content of the new index.md file that will define the main page of your new web site. For now, let's just commit the initial version.

That's all you need to do to get a basic site up and running. Once the new file is committed, I can go to https://davorg.dev/moox-role-json_ld/ and see my new site. Obviously, it's a bit bare-bones for now. You'll want to edit the big bit in the middle where the actual content goes - but it's there and it works.

The default way that these sites work is by using a static site generator called Jekyll. That powers a lot of GitHub Pages, but you don't have to use it if you don't want to. Anything that is in the /docs directory will be published to your web site. So you can use whatever site generation tool you are most comfortable with. In fact I recently wrote about how I use GitHub Actions in conjunction with GitHub Pages to generate "semi-static" web sites. For a site like the ones we're talking about here, you'll probably only need to regenerate the site when new commits are made (rather than regularly during the day).

I like Gabor's idea of encouraging more CPAN modules to have web sites. So, I'm thinking that over the next few weeks, I'll spend some time building tools that can automatically pull in interesting and useful content about the module (links to CPAN, test results and stuff like that). I plan to start by turning the module Pod into Markdown files so that the site can automatically contain all of the documentation. I'll let you know how it goes.

I'm interested to hear what you think? Would you use a tool that automatically built a web site for your CPAN modules? What things would you like to see on such a site?