This is a work in progress. This documentation should reflect the current state of development, but may be incomplete.

If you need a pair programming buddy who knows the tech stack used in this project, you may want to ask the custom GPT custom GPT “Web developer for MvLKSS based projects” (ChatGPT account required).

The following must be installed on your machine.

• Everything listed in the PHP section of the Kirby CMS Requirements
  Please note that for development purposes, you do not require any of the web servers listed in the requirements. Instead, utilize PHP’s built-in server when developing. However, one of the listed “real” webservers is essential when deploying the website.
• On your development machine: Composer, a dependency manager for PHP
  Make sure all platform requirements are met by running the command composer check-platform-reqs after successfully installing Composer.
• On your development machine: Node.js and npm
  All packages and dependencies in this repository are regularly updated to their latest versions.

The following requirements are optional on both your development machine and the production server. Proper fallbacks are in place if these optional requirements are not met.

• ImageMagick in its latest version
  ImageMagick is a better choice than the GD library for server-side image processing. It is especially needed for creating AVIF files. If ImageMagick cannot be used, the GD library is automatically used as a fallback.
• APC User Cache as PHP module
  It is recommended to use the apcu page cache driver if available. If the APC user cache is not available, the default file system cache driver is automatically used as a fallback.
  Note: Typically, page cache should be disabled during development and is therefore disabled in config.localhost.php.

Use the cloning method you like best.

npm install

This is only required on development machines. Once the build script has been run at least once, all essential assets are present and can be transferred to the production server. No npm or npm modules are necessary on the production server.

If you want to use AI-powered development tools like the Context7 MCP server with Claude Code, you'll need to set up your environment variables:

1. Copy the .env.example file to create your own .env file:

   cp .env.example .env

2. Open the .env file and add your Context7 API key:

   CONTEXT7_API_KEY=your-actual-api-key-here
   

3. Get your API key from context7.com

Note: The .env file is git-ignored and should never be committed to the repository. The Context7 MCP server provides up-to-date library documentation and code examples for AI assistants, enhancing AI-assisted development capabilities.

Perform all updates and upgrades exclusively on a development machine and then commit them to the repository. By doing so, deployment becomes more efficient since there is no need to execute any update, installation, or script commands on the production server.

For the sake of ease of deployment, the subdirectories /kirby/*, /site/plugins/*, and /vendor/* are committed to the repository despite the use of Composer.

The package.json includes two useful scripts that conveniently facilitate the process of checking and updating both Composer packages and npm packages.

The utility-dependencies-update-check script checks for new updates of your installed Composer and npm packages and displays the available information. It does not affect any of your files.

npm run utility-dependencies-update-check

The utility-dependencies-update script installs all available updates to your installed Composer and npm packages, based on the information in your composer.json and package.json files.

npm run utility-dependencies-update

Open a terminal and start PHP’s built-in server and all necessary build tools for Tailwind CSS, bundling, and transpiling your frontend JavaScript in watch mode by using this command:

npm run dev-server

Open http://localhost:8000 in your browser to browse the website.¹

Since there is no need for PHP’s built-in server in this case, simply start all the build tools (for Tailwind CSS as well as for bundling and transpiling your frontend JavaScript) in watch mode using this command:

npm run dev

Remember, in order to develop remotely, you’ll need to have Node.js and npm on your web space or web server. However, it’s important to note that Node.js and npm are not required on your production web server.

Open the website in your browser as usual.¹

When development is complete, utilize the following command to generate streamlined and optimized CSS and JS files:

npm run build

This project features a Node.js script aimed at simplifying the task of deleting local Git branches. The script automatically eliminates branches that have been merged and deleted from the remote repository, effectively ensuring that the local development environment stays neat and tidy.

You can use this command to easily run the script:

npm run utility-git-branches-clean-up

Always make sure you're on the main branch (or any other branch that should not be removed) when running this script.

Customization: If your main branch has a different name than main, modify the file .git-branches-clean-up.js in the root directory accordingly by replacing the branch names in the exclusion condition.

The easiest way to deploy the website from a central remote repository to a production or staging server is to use GitHub Actions. You can find a sample workflow in /utilities/deploy-and-sync/github-workflow-deploy-to-uberspace.yml. This sample workflow reacts to changes in a configured branch. Further configuration notes can be found in the YAML file itself.

If the Kirby Panel is used on a staging or production server to edit website content, you may wish to synchronise these changes back to the central remote repository. To do this you can use the shell script /utilities/deploy-and-sync/sync-server-to-central-repo.sh. You will probably want to use a cronjob to run this script on a regular basis. Further configuration notes can be found in the script file itself.

Caddy Web Server (Recommended)

If you use Caddy, add this snippet to your Caddyfile's snippets section:

# Kirby-specific configuration snippet
(kirby_config) {
    # PHP setup (adjust socket path as needed)
    php_fastcgi unix//run/php/php8.4-fpm.sock {
        # Pass Authorization header to PHP (required for API auth)
        env HTTP_AUTHORIZATION {http.request.header.Authorization}
    }

    # Block access to Kirby core directories
    @kirby_blocked path /kirby/* /site/* /content/*
    respond @kirby_blocked 404

    # Enable directory indexes (handled by index.php)
    try_files {path} {path}/ /index.php?{query}
}

Then use it in your site configuration:

example.com, www.example.com {
    root * /var/www/example.com
    # ... other imports like www_to_naked, security_headers, etc.
    import kirby_config  # Add this line
    file_server

    # Optional: Cache static assets
    header /fonts/* Cache-Control "public, max-age=31536000"
    header /images/* Cache-Control "public, max-age=31536000"
}

Apache Web Server

The included .htaccess file is production-ready and provides all necessary configuration including URL rewriting, security headers, compression, and caching. No modifications are needed for most deployments.

Especially pages created with the Page Builder of the Kirby Panel benefit enormously from server-side caching. A page is cached when it is visited for the first time – with the disadvantage, of course, that the "first visitor" to a page (after its cache information has been cleared, e.g. because the page content has been updated) has to wait longer. However, this usually works well.

But there are situations where you might want to preload the page cache for all pages at once. Consider the following scenario as an example: You have to present a newly built website to the client. There were a lot of last-minute changes, so the page cache is more or less empty. Since you know that your pages are quite complex and therefore take a lot longer to load without the page cache, you probably don't want your customer to be the "first page visitor" for every single page – because you can already hear them saying that the new site feels damn slow.

Of course, you could sit down a few hours before the meeting and manually click through all the pages, which is tedious and time-consuming if there are more than a dozen. Not only that, but you would have to do it multiple times because you would have to visit each page with different viewport sizes. Otherwise, the server-side generated images for the different image sizes will not be created, which is necessary due to the responsive image implementation.

In such a situation, the included page cache prefill script comes in handy:

1. Customize the configuration settings in the /utilities/kirby-cache-prefill.js file according to the details of your website project.

2. Run the script on your development machine (which, of course, must be connected to the Internet):

   npm run utility-kirby-cache-prefill

3. Grab some coffee and wait. The script fetches the URLs of all pages from your XML sitemaps and visits each URL using Playwright with different viewports. This results in the visited pages being added to Kirby’s page cache, as well as any server-side generated images being generated in all the required sizes.

Warning: The script has an artificial delay (of a random time between about one and five seconds) between two page visits built in to appear a little less robotic. However, you should make sure beforehand that the cache prefill script does not inadvertently trigger any security mechanisms your web hosting provider may have in place.

If you're using Claude Code as your AI-powered development assistant, this project includes custom slash commands that can pull in up-to-date documentation from Context7 to help with particularly difficult tasks.

Prerequisites: Make sure you have configured your Context7 API key in the .env file (see "Step 3: Configure Environment Variables for AI Development Tools" above).

Pulls official Kirby CMS documentation from Context7 to assist with Kirby-specific development tasks.

Examples:

/context7:kirby
/context7:kirby blueprints
/context7:kirby routing and controllers

Best used for:

• Implementing Kirby blueprints, templates, controllers, or models
• Working with Kirby's routing system
• Configuring Kirby fields and blocks
• Understanding Kirby panel customization

Pulls official Tailwind CSS documentation from Context7 to assist with Tailwind-specific styling tasks.

Examples:

/context7:tailwindcss
/context7:tailwindcss responsive design
/context7:tailwindcss custom colors and themes

Best used for:

• Configuring Tailwind CSS (tailwind.config.js customization)
• Working with Tailwind's utility classes and breakpoints
• Setting up custom colors, fonts, and spacing
• Implementing dark mode or working with Tailwind plugins

Pulls both Kirby CMS and Tailwind CSS documentation from Context7 for comprehensive context when working on features that span both systems.

Examples:

/context7:full
/context7:full styling and theming
/context7:full page builder with custom styles

Best used for:

• Building Kirby templates with complex Tailwind styling
• Implementing page builders with custom Tailwind components
• Setting up brand colors that work across both systems
• Troubleshooting integration issues between Kirby and Tailwind

These slash commands use the Context7 MCP (Model Context Protocol) server to fetch up-to-date documentation and code examples directly from the official Kirby CMS and Tailwind CSS documentation. This provides Claude Code with current, authoritative information to help solve complex problems.

The optional [topic] parameter allows you to narrow the scope of the documentation fetched, which can provide more focused and relevant information for specific tasks.

See Kirby’s comprehensive documentation.

The input file for Tailwind CSS can be found at /src/css/main.css.

After using the mentioned build tools, the output will be located in /assets/css/main.css. It is essential to link this CSS file to your Kirby templates.

Please note: The input CSS file needs to be imported into a JavaScript file so that Webpack can process it. This is accomplished with the file /src/js/maincss.js. Do not delete this file. Otherwise, the output CSS file based on the tailwind CSS classes in your templates will not be generated by Webpack.

To keep things organized and simple, separate your frontend scripts into partials stored in the /src/js/main-partials/ folder.

Then, import them into /src/js/main.js, which Webpack will use as the entry point to bundle everything (including imported Node.js modules) and create the output file assets/js/main.js. This is the file that needs to be linked in your Kirby templates.

Here's how to set up a brand color palette for the website and give editors access to specific brand colors (such as in background color selection fields):

1. Unless you exclusively utilize the default Tailwind CSS colors as your brand colors for website design, you should incorporate your custom colors in the tailwind.config.js file. For more information on adding supplementary colors to the Tailwind CSS setup, refer to the Tailwind CSS documentation.
2. Specify the colors you wish to offer for selection by website editors in Kirby’s /site/config/config.php file, utilizing the relevant Tailwind CSS utility classes.
3. Note that the idea is to define various Tailwind CSS utility classes for each color option that can be selected to accommodate both light and dark modes while also defining corresponding contrast colors. These contrast colors are employed, for instance, to guarantee that any text shown over the designated brand color background remains legible at all times.
   Define all Tailwind CSS utility classes you wish to use for a brand color separately, as each utility class must be present as a complete string in a PHP file to ensure accurate identification during the build process. Refer to the comment within the appropriate section of the /site/config/config.php file for specific examples and further details.
4. To add unique contrast colors beyond black and white, simply include additional color schemes for the Tailwind CSS typography plugin. To do so, copy the prose-black and prose-white utility class examples in tailwind.config.js and use them to add your own typography colors. For further details, refer to the “Adding custom color themes” section within the Tailwind CSS typography plugin documentation.

• Kirby
• Kirby plugins:
  • Clear Cache
  • Date Extended
  • Grid Block
  • Hashed Assets
  • Kirby Highlighter
  • Kirby Language Selector
  • Minify HTML
  • Retour
  • Robots.txt
  • Snippet Controller
• PostCSS
• PostCSS plugins:
  • Tailwind CSS (including the forms plugin, the aspect ration plugin and the typography plugin)
  • Autoprefixer
  • cssnano
• Babel
• webpack
• webpack plugins:
  • copy-webpack-plugin
  • mini-css-extract-plugin
• Composer plugins:
  • composer-normalize
• Playwright
• Axios
• node-xml2js

• Accessible hamburger buttons without JavaScript
• Responsive images (in image blocks)
• Image modal (i. e. lightbox)