README

Frequently used data structures for Kirby CMS.

Requirements

Kirby CMS (>=4.0)
PHP (>= 8.3)

Installation

Composer

composer require hksagentur/kirby-schema

Download

Download the project archive and copy the files to the plugin directory of your kirby installation. By default this directory is located at /site/plugins.

Usage

All blueprints provided by the plugin are registered within a custom namespace (@hksagentur/schema). You have to reference or extend these blueprints to take advantage of the provided data structures.

A simple exampe would be to use the navigation blueprint for the site:

# site/blueprints/site.yml
tabs:
  content:
    label: Content
    fields: []
  settings:
    label: Settings
    fields:
      navigation: @hksagentur/schema/fields/navigation

Instead of referencing the provided blueprints directly you can use them as a base and start customizing:

# site/blueprints/site.yml
tabs:
  content:
    label: Content
    fields: []
  settings:
    label: Settings
    fields:
      navigation:
        extends: @hksagentur/schema/fields/navigation
        fields:
          classNames:
            type: text
            label: HTML Classes
          target: false
          rel: false

This applies to all blueprints regardless of their type.

If you only want to use a blueprint without extending it, you can let the plugin generate aliases for you:

<?php

// site/config/config.php
return [
  'hksagentur.schema.aliases' => [
    'files/image',
    'files/video',
  ],
];

This would make the image and video blueprints available without the namespace as files/image or files/video. You can also provide a custom name, if you like:

<?php

// site/config/config.php
return [
  'hksagentur.schema.aliases' => [
    'files/image' => 'files/gallery-image',
    'files/video' => 'files/gallery-video',
  ],
];

Available Blueprints

Below is an overview of all available blueprints provided by this plugin. Each entry lists the readable name, the ID (for reference/extension), and a short description.

Block Blueprints

Name	ID	Description
Accordion	`@hksagentur/schema/blocks/accordion`	Collapsible group of contents.
Billboard	`@hksagentur/schema/blocks/billboard`	Promotional banner showcasing key messages or visuals.
Cards	`@hksagentur/schema/blocks/cards`	Present related content in concise, self-containing blocks.
Collection	`@hksagentur/schema/blocks/collection`	Customizable list of related pages.
Disclosure	`@hksagentur/schema/blocks/disclosure`	Expandable and collapsible content section.
Gallery	`@hksagentur/schema/blocks/gallery`	Group related images in a gallery.
Heading	`@hksagentur/schema/blocks/heading`	Define the documents hierarchy using headings.
Hero	`@hksagentur/schema/blocks/hero`	Prominent section highlighting main message.
Image	`@hksagentur/schema/blocks/image`	Embed images from internal or external sources.
Media Text	`@hksagentur/schema/blocks/media-text`	Combine media with descriptive text.
Tabs	`@hksagentur/schema/blocks/tabs`	Spread related contents across multiple tabs.
Video	`@hksagentur/schema/blocks/video`	Play embedded media content.

Field Blueprints

Name	ID	Description
Actions	`@hksagentur/schema/fields/actions`	Group of links.
Address	`@hksagentur/schema/fields/address`	Postal address fields.
Align Content	`@hksagentur/schema/fields/align-content`	Vertical alignment of content items.
Author	`@hksagentur/schema/fields/author`	Assign a user as content author.
Blocks	`@hksagentur/schema/fields/blocks`	Flexible content builder using Kirby blocks.
Caption	`@hksagentur/schema/fields/caption`	Short description for images or figures.
Category	`@hksagentur/schema/fields/category`	Category selection with autocompletion.
Channels	`@hksagentur/schema/fields/channels`	Link to related social media channels.
Content Layout	`@hksagentur/schema/fields/content-layout`	Arrange content blocks in a layout.
Coordinates	`@hksagentur/schema/fields/coordinates`	Geographic coordinates of a place.
Cover	`@hksagentur/schema/fields/cover`	Preview image of a page or entity.
Created	`@hksagentur/schema/fields/created`	Automatically populated creation date.
Currency	`@hksagentur/schema/fields/currency`	Select the currency for prices or amounts.
Email	`@hksagentur/schema/fields/email`	Email address of a person or organization.
Eyebrow	`@hksagentur/schema/fields/eyebrow`	Small text above a headline.
Fax	`@hksagentur/schema/fields/fax`	Fax number of a person or organization.
Featured	`@hksagentur/schema/fields/featured`	Mark content as featured.
Gallery	`@hksagentur/schema/fields/gallery`	Group related images in a gallery.
Heading Level	`@hksagentur/schema/fields/heading-level`	HTML heading level to choose from.
Heading	`@hksagentur/schema/fields/heading`	Text input for headlines or titles.
Hours	`@hksagentur/schema/fields/hours`	Opening hours of a store or local business.
Image	`@hksagentur/schema/fields/image`	File picker for image files.
Inline Text	`@hksagentur/schema/fields/inline-text`	Formatted inline text elements.
Justify Content	`@hksagentur/schema/fields/justify-content`	Horizontal alignment of content items.
License	`@hksagentur/schema/fields/license`	A license document applied to an item.
Limit	`@hksagentur/schema/fields/limit`	Specify a maximum value or amount.
Link	`@hksagentur/schema/fields/link`	Reference an internal or external document.
Logo	`@hksagentur/schema/fields/logo`	File picker for a logo.
Markdown	`@hksagentur/schema/fields/markdown`	Markdown editor for formatted text.
Name	`@hksagentur/schema/fields/name`	Separate fields for the individual parts of a name.
Navigation	`@hksagentur/schema/fields/navigation`	Hierarchical navigation structure.
Occupation	`@hksagentur/schema/fields/occupation`	Assign one or more occupations to a person.
Offset	`@hksagentur/schema/fields/offset`	Display offset for lists or queries.
Open	`@hksagentur/schema/fields/open`	Toggle open/closed state of blocks.
Organization	`@hksagentur/schema/fields/organization`	Organization details with address and contact info.
Person	`@hksagentur/schema/fields/person`	Contact details for a person.
Price	`@hksagentur/schema/fields/price`	The offer price of a product.
Published	`@hksagentur/schema/fields/published`	Date when the page was first published.
Ratio	`@hksagentur/schema/fields/ratio`	Selection of common aspect ratios.
Responsibilities	`@hksagentur/schema/fields/responsibilities`	Assign one or more responsibilities to a person.
Reverse	`@hksagentur/schema/fields/reverse`	Reverse the order of a sequence.
Rich Text	`@hksagentur/schema/fields/rich-text`	Editor for formatted, rich content.
Source	`@hksagentur/schema/fields/source`	Source and license information of a file.
Tags	`@hksagentur/schema/fields/tags`	Associate an entity with tags.
Telephone	`@hksagentur/schema/fields/telephone`	Telephone number of a person or organization.
Updated	`@hksagentur/schema/fields/updated`	Last modification date of a page.
Video	`@hksagentur/schema/fields/video`	File picker for videos files.
Website	`@hksagentur/schema/fields/website`	URL to an external website.

File Blueprints

Name	ID	Description
Document	`@hksagentur/schema/files/document`	Complementary documents such as PDFs or compressed archives.
Image	`@hksagentur/schema/files/image`	Generic image with alternative text and caption.
Logo	`@hksagentur/schema/files/logo`	Visual identity of a brand or institution.
Video	`@hksagentur/schema/files/video`	Video file with poster and caption.

Page Blueprints

Name	ID	Description
Article	`@hksagentur/schema/pages/article`	Short publication like a news article or blog post.
Page	`@hksagentur/schema/pages/default`	Generic page using the Kirby block builder.
Employee	`@hksagentur/schema/pages/employee`	Personal profile of an employee.

License

ISC License. Please see License File for more information.

hksagentur / kirby-schema

Maintainers

Details