Example: Plugin Blueprint

A Plugin's blueprint gives Grav insight into what a plugin is, its source, support and author information, dependencies, and form fields used to administer the plugin in the Grav Admin.

As an example, here's the Blueprint for a plugin:

name: Assets
slug: assets
type: plugin
version: 1.0.4
description: "This plugin provides a convenient way to add CSS and JS assets directly from your pages."
icon: list-alt
author:
  name: Team Grav
  email: [email protected]
  url: https://getgrav.org
homepage: https://github.com/getgrav/grav-plugin-assets
demo: https://learn.getgrav.org
keywords: assets, javascript, css, inline
bugs: https://github.com/getgrav/grav-plugin-assets/issues
license: MIT

dependencies:
  - { name: afterburner2 }
  - { name: github }
  - { name: email, version: '~2.0' }

There are different properties that you can use to give your resource an identity. Some are required, others are optional.

property description
name* This is the name of the resource. Avoid appending Plugin or Theme, there is no need for that.
slug* This is the unique identifier for the resource, it's also used to determine the name of the folder where the resource is stored, e.g. user/plugins/__slug__
type* This is the type of the resource, it should be either plugin or theme
version* The version of the resource. This value should always change on each release, incrementally. You should follow the semver standard, too.
description* The description of your resource. Please don't exceed 200 characters. A description should be short and straight to the point. You can use markdown syntax if needed. It's also a good idea to wrap your description in quotation marks.
icon* Icon is what will be used on getgrav.org. At this stage, we are using Font Awesome icons library, so if you are developing a new plugin or theme, it should be your job to ensure the icon you picked is not already used. Otherwise we will have to change it for you.
screenshot (optional) Screenshot is only ever evaluated for Themes and completely ignored for Plugins. For Themes, this would be the filename of the screenshot that comes with the theme (default: screenshot.jpg). If you have a screenshot.jpg image at the root of your theme, then you can avoid using this property. Our repository will automatically pick it up.
author.name* The developer full name
author.email (optional) The developer email.
author.url (optional) The developer homepage.
homepage (optional) If you have a dedicated homepage for your resource, this would be the place for it.
docs (optional) If you have written documentation for your resource, you can link them here.
demo (optional) If you have a demo up and running about your resource, link it here.
guide (optional) If you have tutorials or how-to guides for your resource, link it here.
keywords (optional) Although there is no real use of keywords yet, you can list keywords relative to your resource here, comma separated.
bugs (optional) The URL where bugs can be reported, usually this would be the GitHub issues link.
license (optional) The type of license your resource is (MIT, GPL, etc). It is advised that you always provide a LICENSE file with your resource.
dependencies (optional) A list of dependencies that the plugin/theme requires. The default process is to use GPM to install them, however, if an optional GIT repository URL is provided, installing direct from the repository will be an option also. Also if you use an array, you can define a name and a version explicitly using Composer-style package versions
gpm (optional) Whether to get updates from the GPM. Set to false to disable GPM updates for non-GPM resources.

Here is an example of the identity portion of the GitHub plugin blueprints:

name: GitHub
slug: github
type: plugin
version: 1.0.1
description: "This plugin wraps the [GitHub v3 API](https://developer.github.com/v3/) and uses the [php-github-api](https://github.com/KnpLabs/php-github-api/) library to add a nice GitHub touch to your Grav pages."
icon: github
author:
  name: Team Grav
  email: [email protected]
  url: https://getgrav.org
homepage: https://github.com/getgrav/grav-plugin-github
keywords: github, plugin, api
bugs: https://github.com/getgrav/grav-plugin-github/issues
license: MIT

Theme blueprints work in very much the same way as plugins.

Found errors? Think you can improve this documentation? Simply click the Edit link at the top of the page, and then the icon on Github to make your changes.

Results