Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Advent Calendar is a light web application to show a picture and its legend per day before Christmas, or any other event.
It’s written in PHP, use last web technologies—and proud to not support obsolete versions of IE.

See a demo.

Home of Advent Calendar

You are in a hurry?

OK, let's do it quickly!

git clone advent
cd advent/private
cp settings.example.json settings.json

Then edit the settings.json file to configure the application and set the year — or generate settings file and put it in the private folder.

To finish, just put your image files in the private folder; images named with the number of the day (such as 1.jpeg, 2.jpg, 3.png).
Supported formats are: JPG/JPEG, PNG, GIF.


Get the source

Download the last version on the releases page.

Or clone the repository

If you have git on your server, you can also just clone the repository with:

git clone advent


Basic configuration

Copy the settings.example.json file on folder private to settings.json and edit it to configure the application.

The minimum required configuration file must contains:

  "title": "Advent Calendar · 2021",
  "year": 2021

Transform AdventCalendar into CountDownCalendar

If you want, you can also customize month, first day and last day which are used to display the period of days, but it's not really an AdventCalendar anymore ;-)

Just change the period with those 3 options:

  "month": 3,
  "first_day": 8,
  "last_day": 31

It will make a countdown calendar for March from the 8th to the 31th.

Full available options

Feel free to use the online settings file generator to easily build your settings.json file, and then put it into the private folder.

Property Type Description
title string Required Set the title of your AdventCalendar.
year integer Required Set the year to be used for the calendar and the cutdown.
month integer Specific month to turn on a countdown calendar. Default is 12.
first_day integer Specific first day to turn on a countdown calendar. Default is 1.
last_day integer Specific last day to turn on a countdown calendar. Default is 24.
lang string Supported languages are en (default), fr, de.
background string Set to alternate to use the alternative background, otherwise set the URL of your custom background image.
passkey string If filled out, visitors need to enter a password to access the private AdventCalendar.
disqus_shortname string Set a Disqus account to enable comments for day pages.
google_analytics object Set a Google Analytics account with a child object containing the two properties tracking_id and domain.
piwik object Set a Piwik account with a child object containing the two properties piwik_url and site_id.
plausible object Set a Plausible account with a child object containing the property domain for data-domain, and if you use a CNAME custom domain the property custom_src with the full URL in the Plausible src configuration.
copyright string Set a copyright notice; not displayed if empty (default).
url_rewriting boolean Set to true to enable rewriting URL and uncomment lines in the root .htaccess file. Default is false.

This is an example with all options:

  "title": "Advent Calendar · 2020",
  "year": 2020,
  "month": 12,
  "first_day": 1,
  "last_day": 24,
  "lang": "en",
  "background": "alternate",
  "passkey": "My top secret password!",
  "disqus_shortname": "myDisqusName",
  "google_analytics": {
    "tracking_id": "UC-12345",
    "domain": "domain.tld"
  "piwik": {
    "piwik_url": "piwik.domain.tld",
    "site_id": "12345"
  "plausible": {
    "domain": "domain.tld",
    "custom_src": "https://cname.domain.tld/js/index.js"
  "copyright": "All content is under Creative Commons BY-NC 3.0 licence.",
  "url_rewriting": false

Picture per days

Add pictures

Put your photos in the private folder, and name them with the number of the day you want to illustrate. For example, for the 1st December, call your file 1.jpg or 1.jpeg.

Supported formats are: JPG/JPEG, PNG, GIF.

Be sure that the access to private folder is forbidden when browsing it!
For Apache configuration, be sure that a .htaccess file with the directive Require all denied is in and read.

Customize legend and title

Feel free to use the online calendar file generator to easily build your calendar.json file, and then put it into the private folder.

To add a title, a legend or a text on a day page, just rename calendar.example.json in folder private in calendar.json and add what you want to display.

For example:

  "6": {
    "title": "Saint Nicholas Day",
    "legend": "Berlin, March 2013",
    "text": "Lorem ipsum dolor sit amet, […]."

Add a link

If you want that the image and legend point to a link, add the property link to the calendar.json:

  "8": {
    "legend": "Screnshot of Advent Calendar",
    "link": ""

A day with title, legend and text

Oups, problems?

  • All days are shown before Christmas: Check the syntax in settings.json or update the year.
  • Photo is not displayed: Be sure your photo is correctly named, like 3.jpg or 12.jpeg with the supported formats.
  • Title, legend or text are not displayed: Check the syntax of your calendar.json file.
  • Day is shown in late or advance: Configure the timezone of your server.

Want to contribute?

Source code is developed by Nicolas Devenet and hosted on GitHub. Feel free to fork it and to improve the application!

Let me know if you use Advent Calendar by sending me an e-mail, I will be happy ;-)

Special thanks to

  • @fscholdei for the German translation
  • @Thaoh for the Norwegian translation and the URL custom background feature