• ♡ Sponsor

    Publishing Packages

    #Composer #Extension #Package

    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.


    Related

    System  ⁄
    Installing Packages — System

    Automad can be easily extended by installing custom packages. A package can be a theme or a PHP extension or a combination of both. The easiest way to install packages is to use the Packages section on the Automad dashboard. It also helps you to get an overview about available ...

    Developer Guide  ⁄
    Building Themes — Developer Guide

    Themes are an essential part of a content management system. They define the way your content is presented to the visitors of your website. Automad's flexible and intuitive template language enables also inexperienced developers or beginners to create themes and templates on ...

    Template Language  ⁄
    Using Extensions — Template Language

    Extensions provide a convenient way of turning custom PHP code into Automad statements. Besides the fact that extensions have to be called by their names including their namespace, the syntax is the same as for Toolbox or pipe functions.

    Developer Guide  ⁄
    Developing Extensions — Developer Guide

    The extension interface provides a convenient way of extending Automad's core functionality with custom PHP code while still offering Automad's template syntax. There are basically two types of template language extensions: generic extensions and custom pipe functions. Check out ...

    Developing Extensions  ⁄
    Generic Extensions — Developing Extensions

    In case you are missing any advanced feature while developing themes using Automad's template language, you are able to implement that functionality as a generic extension written in plain PHP.

    Developing Extensions  ⁄
    Custom Pipe Functions — Developing Extensions

    Automad provides already some basic string manipulation functions to be used with the pipe operator. However, in some cases it my be necessary to use a custom function to modify the content of a variable. Custom pipe functions can be written in plain PHP. Thier basic setup is ...

    Developer Guide  ⁄
    Cheat Sheets — Developer Guide

    In case you prefer to start developing a theme or extension without reading the full documention, the cheat sheets below are a good point to start. In addition to this page there is also the theme skeleton package available to help you getting started.

    Cheat Sheets  ⁄
    Plain PHP Snippets — Cheat Sheets

    In case you want to develop a new extension or use PHP in your templates, the collection of common code snippets below might help you getting started quickly.

    Cheat Sheets  ⁄
    Creating Theme Packages — Cheat Sheets

    This guide describes step by step the workflow of setting up and publish a new theme. It assumes you're familiar with Visual Code Studio and working on a system with a Bash shell or similar — like macOS or Linux.

    Packages

    Browse free Composer packages and install themes and extensions for your Automad site.

    • Automad
    • Developer Guide
    • Publishing Packages
    Discuss
    Packages
    Release Notes
    Support
    Terms of Use
      Become a Sponsor
      GitHub
      Twitter
      Facebook
      Instagram
      2013-2022 by Marc Anton Dahmen
    Released under the MIT license

    A faceless machine, creating one's portrait in the internet.
  • Automad
  • Getting Started
  • System
  • User Guide
  • Developer Guide
  • Headless Mode
  • Discuss
  • Packages
  • Building Themes →
  • Developing Extensions →
  • Publishing Packages
  • Editor Plugins
  • Cheat Sheets →
  • API Reference