Dave CrossA few months ago, Gabor asked if more CPAN modules should have their own web sites. I replied, saying thought it was a good idea and pointing out how easy it was to create project web sites on GitHub Pages.
But since then, I've been wondering if could be made even easier. Perhaps we could make it easy enough that there was really no reason not to have a web site for your CPAN module.
And today I've released App::CPANModuleSite that does just that.
The default usage is pretty easy.
- Install the module
- In your repo checkout run
mksite <distribution-name> - Run
git add docsto add your new website directory to your repo - Commit the changes and push the commit
- Configure your repo to support GitHub pages (I covered that in my earlier blog post)
And you'll have a basic web site for your module at the web address https://<github-user>.github.io/<repo-name>.
The default site is pretty basic. And it has a big banner across the page saying that you haven't put any effort into the site yet. But that's simple enough to fix. Just add a file called tt_lib/intro.tt to your repo that contains a bit of HTML which explains more about what your module does. The next time you rebuild the site, that text will replace the default paragraph.
Other than that, the default site contains:
- The documentation for all of the modules in your distribution
- Links to other standard pages about your module (CPAN, CPAN testers, CPANTS, things like that)
- Links to your code repo and issue tracker (if they are defined in your CPAN metadata)
It's also simple to add more pages to your site. Just add files in a site_src directory in your repo. Any file in that directory whose name ends in .tt will be processed by the Template Toolkit and the output will be stored in the /docs directory (with the .tt stripped from the name). Any files without a .tt extension will just be copied into /docs. If you're adding pages, then you'll almost certainly also want to edit the navbar on the page to contain links to your new pages.
Default versions of various template files in /site_src and /tt_lib are installed as part of App::CPANModuleSite's installation. To edit them, you just copy them into the same directory in your repo and edit the copied versions. Any files found inside your repo will take precedence over the versions in the default directories.
Any templates that you write (or existing ones that you edit) will have access to a few template variables:
- distribution is a MetaCPAN::Client::Distribution object containing details of your distribution
- release is a MetaCPAN::Client::Release object containing details of the latest release of your distribution
- modules is an array reference, where each element of the array is a MetaCPAN::Client::Module object containing details of one module in your distribution
This is all pretty experimental currently. I'm very happy to add more information to the default pages, more variables to the template engine and make pretty much any other changes that any users suggest. Let's work together to make this a useful and powerful web site generation tool.
I have a couple of thoughts for things I want to do next:
- I've already started work on creating a GitHub Action, so that you can automatically regenerate the site, for example, whenever you check in a change to your code
- The whole point of this is that more CPAN web sites mean better SEO for Perl. So I plan to think of ways that make the default sites as SEO-friendly as possible
Please let me know what you think. Do you think this is a good idea? Will you use the module?
Oh, and the site that App::CPANModuleSite generated for itself is at https://davorg.dev/app-cpanmodulesite/.
