The Perl Advent Calendar is a series of articles that begins on December 1 each year.
Raise an issue suggesting your topic.
Fork the repo and start a new article. This prompts you for a few things and creates a new file for you under YEAR/incoming/.
make new-articleIt writes to the current calendar year by default. Override that (or any other field) with a make variable:
make new-article YEAR=2026(The underlying script is perl script/new_article; run it directly if you
prefer, e.g. perl script/new_article --year 2026.)
Edit your article, and test it as you work:
perl t/article_pod.t 2023/incoming/your-article.podTo see your article rendered with the real calendar styling, preview just that one file and open the URL it prints:
make preview ARTICLE=2026/incoming/your-article.pod(Run make init once first to fetch the build submodules. Serving the
preview needs http_this: install it once with cpm install -g App::HTTPThis.
No local Perl? make preview-docker ARTICLE=... does the same in Docker. To
share the preview with others on your tailnet, use make preview-tailnet
instead. make help lists every build target.)
When you are satisfied, create a pull request. You can keep working on the article and pushing updates to your fork; the pull request will automatically see the updates.
Most build and preview tasks are wrapped in the Makefile — run make help
to list every target and its overridable variables. The common ones:
make site— build the whole site intoout/(all years)make preview ARTICLE=2026/incoming/foo.pod— render and serve a single article
Run make init once in a fresh checkout to fetch the build submodules. The
build scripts run the forked advcal from inc/, which the site needs; to run
advcal by hand, first source script/use-forks.sh (bash, from the repo
root). The steps below are older manual commands, kept for reference; they use
the stock CPAN advcal, so their output won't match the deployed site.
Using Docker? See DOCKER.md for containerized build and preview instructions.
Currently this needs to be run manually once per year, in the new year.
./year2yaml $(perl -MTime::Piece -le 'print localtime->year - 1')To create some root files from archives.yaml:
archives.html- list of advent calendarsarchives-AZ.html- list of modulesarchives-Yd.html- list of articles
Execute the following script:
perl mkarchives .cpm install -g WWW::AdventCalendar App::HTTPThisThen build all recent calendars
for year in $(seq 2011 2026); do cd $year && advcal -c advent.ini -o `pwd` && cd ..; doneStart HTTP webserver in one line:
http_this --autoindex .You can visit http://127.0.0.1:7007/
For notes on the editing process, please refer to EDITING.md