Publishing Packages

Automad uses Composer as dependency manager. Therefore packages can be made public by submitting them as Composer packages to the Packagist website. Published Automad packages also automatically appear in the package browser. The process of releasing a package is basically the same as for all other Composer packages out there. However, there are certain properties in a package's composer.json file which have to be set correctly to make it work with Automad. Find more detailled information about publishing themes and extensions below.

Check out this cheat sheet for creating theme packages!

Theme Packages

In order to be published on Packagist and to appear in Automad's package browser, a theme package has to meet the requirements listed below.

Note that there is also a basic theme skeleton including all required files to get started quickly with a new theme and understand the basic structure of a package.

1. A composer.json file with the following content:

   {
       "name": "vendor/theme-name",
       "description": "Your description ...",
       "type": "automad-package",
       "keywords": ["theme", "..."],
       "license": "MIT",
       "require": {
           "automad/package-installer": "^1.1"
       }
   }
   

   Obviously the name and description fields should be changed to match your theme. The type and keyword fields are required. The type has always to be automad-package in order to be able to use the dashboard for installation. The keywords must contain theme but may contain other keywords as well. The automad/package-installer package is required as well and must not be removed from the list of required packages but you may add other dependencies of course.

2. A README.md file with a description of your theme and instructions for using it. Make sure you also link some preview images into the file to quickly give people an idea of the look and feel of your design. Please check out the Style Guide below to make sure your package looks pretty in the package browser.
3. A public repository on GitHub or Bitbucket registered on Packagist.

Extension Packages

Releasing an extension can be a bit more tricky than a theme. Please be aware that Automad supports Composer autoloading which is the recommended way of integrating extensions. This documentation assumes that you are familiar with Composer and its development workflow.

Check out the extension skeleton package including all required files to get started quickly with a new extension and a more detailled workflow documentation.

The basic requirements for an extension package are:

1. A composer.json file with the following content:

   {
       "name": "vendor/extension-name",
       "description": "The extension description ...",
       "type": "automad-package",
       "keywords": ["extension", "..."],
       "license": "MIT",
       "require": {
         "automad/package-installer": "^1.1"
       },
       "autoload": {
           "classmap": [""]
       }
   }
   

   As with themes, the name and description fields should be changed to match your theme. The type and keyword fields are required. The type has always to be automad-package in order to be able to use the dashboard for installation. The keywords must contain extension but may contain other keywords as well. The automad/package-installer package is required as well and must not be removed from the list of required packages but you may add other dependencies of course. Please also note that the composer.json above includes an autoload field. Read more about autoloading with Composer here.

2. A README.md file with a description of your extension and instructions for using it. Please check out the Style Guide below to make sure your package looks pretty in the package browser.
3. A public repository on GitHub or Bitbucket registered on Packagist.

Style Guide

To make sure that your package looks good in the package browser it is important to structure your README.md file using Markdown and add some artwork or preview images. Images can simply be linked in your package's README.md using the Markdown image tag.

![](http://domain.com/image.jpg)

Note that you will have to host the images somewhere in order to be able to link them. You could for example include them into your repository on GitHub or Bitbucket and link to their raw version.

Preview Cards

The package browser generates preview cards for each registered Automad package on the landing page. Along with the package name and the description taken from the composer.json file, the first image linked in the README.md file is used as a preview image. Note that the aspect ratio of that first image should be exactly 4:3 to look good in the browser. A good example for a pretty package is dahmen/automad-bulma.