Installation of Advent Calendar

  1. Download the latest version from GitHub. (You can also clone the repository to more easily retrieve updates.)
  2. Unzip the downloaded file to your web server directory, and navigate to the folder you created. (You can change the name of the folder, it has no impact).
  3. Now go to the private folder. This contains the configuration, and this is where we will store the files.
    • Duplicate the settings.example.json file to settings.json. Edit this new file to replace the title with the one you want, and set the correct calendar year.
    • Store the images or pictures in this folder. They should be named from 1 to 24, and be in JPEG, PNG or GIF format.
      For example 1.jpeg, 2.jpg, 3.png, etc.
  4. From there on, it’s all good!

Advanced configuration

It’s possible to configure your calendar in a more advanced way. You can find all the available options in the guide. I have also put online a configuration file generator.

Let’s have a look at three options that may be useful.

Add a password

To protect access to your calendar, for example so that only your family or friends can access it, you can add a password.

Login form to access the private advent calendar.
Private advent calendar: login with a password.

You need to add the following line to the settings.json configuration file:

"passkey": "My top secret password!"


By specifying in the settings.json configuration file the start day, end day and month, in addition to the year, the advent calendar becomes a countdown.

"year": 2022,
"month": 12,
"first_day": 1,
"last_day": 24

For now, it’s not possible to make a countdown between two different calendar months.

Add title, caption and description

You can customise the title of each day, as well as add a caption under each photo and a description. It’s also possible to add a link to which the image and the caption redirect.

You need to create a new file called calendar.json which has the following structure for each day to be customised:

  "6": {
    "title": "Saint Nicolas",
    "legend": "Strasbourg, Dec. 2008",
    "text": "Lorem ipsum dolor sit amet, […].",
    "link": ""
  "8": {
    "legend": "Paris, July 2021",

I advise you to use the online calendar generator to make it easier for you to create the file.

Feel free to leave a comment or open an issue on the GitHub project if you come across a bug, or to share ideas for improvements and new features.