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?
Top comments (6)
When reading the docs of a distribution I often find myself jump from module to module looking for the solution.
It might be a good idea to create a single-page version of all the documentation that is in a distribution combining the POD from all the modules in that distribution.
OTOH I also often find that I'd like to limit my search to only a section of the documentation. It would be nice to support that too.
Nice!
I would love to see a nicely parsed and displayed version of the whole Changes file. It might even become an RSS feed for the site.
Also some of the projects have a examples/ or eg/ directory. Displaying the content of it might be nice.
This is a great idea to create a beautiful website for a CPAN module. In R community they have
pkgdownwhich makes creating website for a module/package painless.pkgdown.r-lib.org/
how about a dzil plugin to make a site out of your POD? that would be fun
MetaCPAN already has all of the Pod. So I'm not sure what you'd gain from doing that. I'm thinking this needs to be more unstructured content - examples, tutorials, FAQs, things like that.
But if you want to build the Dzil plugin, go for it :-)
This is excellent.