{"id":14986797,"url":"https://github.com/bnomei/kirby3-plopfile","last_synced_at":"2026-02-10T07:30:17.381Z","repository":{"id":53977077,"uuid":"388788213","full_name":"bnomei/kirby3-plopfile","owner":"bnomei","description":"CLI tool to generate and append to various files for Kirby3 CMS using Plop.js","archived":true,"fork":false,"pushed_at":"2024-11-23T17:26:42.000Z","size":1456,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-02-11T00:48:20.377Z","etag":null,"topics":["automate","files","generate","handlebarsjs","inquirerjs","kirby3","kirby3-cms","kirby3-plugin","plopjs","promt","workflow"],"latest_commit_sha":null,"homepage":"https://forum.getkirby.com/t/kirby3-plopfile-a-cli-tool-to-generate-and-append-to-various-files/23048","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bnomei.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"bnomei","patreon":"bnomei","open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":["https://buymeacoff.ee/bnomei","https://paypal.me/bnomei"]}},"created_at":"2021-07-23T12:05:31.000Z","updated_at":"2024-11-23T20:17:14.000Z","dependencies_parsed_at":"2024-09-19T19:01:12.757Z","dependency_job_id":"1abfb340-f94c-4f1f-858b-b8864bb08b0b","html_url":"https://github.com/bnomei/kirby3-plopfile","commit_stats":{"total_commits":95,"total_committers":2,"mean_commits":47.5,"dds":"0.12631578947368416","last_synced_commit":"00983c4a70f77e9d849172cbe696919813b44ce0"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bnomei%2Fkirby3-plopfile","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bnomei%2Fkirby3-plopfile/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bnomei%2Fkirby3-plopfile/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bnomei%2Fkirby3-plopfile/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bnomei","download_url":"https://codeload.github.com/bnomei/kirby3-plopfile/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239805935,"owners_count":19700219,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automate","files","generate","handlebarsjs","inquirerjs","kirby3","kirby3-cms","kirby3-plugin","plopjs","promt","workflow"],"created_at":"2024-09-24T14:13:34.051Z","updated_at":"2026-02-10T07:30:17.336Z","avatar_url":"https://github.com/bnomei.png","language":"JavaScript","funding_links":["https://github.com/sponsors/bnomei","https://patreon.com/bnomei","https://buymeacoff.ee/bnomei","https://paypal.me/bnomei"],"categories":[],"sub_categories":[],"readme":"# Kirby Plopfile\n\n![Release](https://flat.badgen.net/packagist/v/bnomei/kirby3-plopfile?color=ae81ff)\n![Downloads](https://flat.badgen.net/packagist/dt/bnomei/kirby3-plopfile?color=272822)\n[![Twitter](https://flat.badgen.net/badge/twitter/bnomei?color=66d9ef)](https://twitter.com/bnomei)\n\nPlopfile to generate and append to various files for Kirby3 CMS using Plop.js\n\n## What others (might have) said about this plugin\n\n\u003e 🤩\u003cbr\u003e\n\u003e \u003csmall\u003e_- K-nerd_\u003c/small\u003e\n\n\u003e Using generators is faster than grabbing and adjusting code from the official docs? Really? Awesome!\u003cbr\u003e\n\u003e \u003csmall\u003e_- Lasi Toiper_\u003c/small\u003e\n\n\u003e Finally a Kirby CLI on ploperoids with a gazzilion of appending generators.\u003cbr\u003e\n\u003e \u003csmall\u003e_- p10pa_\u003c/small\u003e\n\n\u003e I don't care how it works but it does! Unittests FTW.\u003cbr\u003e\n\u003e \u003csmall\u003e_- NewToThis_\u003c/small\u003e\n\n## Installation\n\n### Plop.js (version 2)\n\nInstall [Plop.js globally](https://plopjs.com). Plop.js is simplified just glue code between [inquirer](https://github.com/SBoudrias/Inquirer.js/) prompts and [handlebar](https://github.com/wycats/handlebars.js/) templates.\n\n```bash\nnpm install -g plop@2\n```\n\nor\n\n```bash\nyarn global add plop@2\n```\n\n\u003e NOTE: plop.js version 3 is not supported yet since all js files would need to be converted to ESM syntax.\n\n### Kirby Plugin\n\n-   unzip [master.zip](https://github.com/bnomei/kirby3-plopfile/archive/master.zip) as folder `site/plugins/kirby3-plopfile` or\n-   `git submodule add https://github.com/bnomei/kirby3-plopfile.git site/plugins/kirby3-plopfile` or\n-   `composer require bnomei/kirby3-plopfile --dev`\n\n### Plopfile for your project\n\nCopy `example.plopfile.js` from the plugin directory to your project root.\n\n```bash\ncp site/plugins/kirby3-plopfile/example.plopfile.js plopfile.js\n```\n\n### Node dependencies\n\nNo node_module dependencies are included. To use this plugin run `npm i` or `yarn` in the plugin folder.\n\n## Usage\n\n### Use Plop to generate or append to files\n\nPlop provides an interactive terminal UI. It let's you choose a generator and fill each prompt step by step.\n\n```bash\nplop\n```\n\nBut you can also trigger a generator and [bypass some prompts](https://plopjs.com/documentation/#cli-usage). You can provide all prompts or choose to be prompted for some using `_` as an value. Generators that create files need a target folder. The plugin tries its best to guess your setup using `glob`. When bypassing the `folder`-prompt you can use `$` to default to your kirby root for that specific generator (like `site/templates` for `plop template $`).\n\n```bash\n# $ = kirbys default root for that generator\nplop blueprint $ pages blogpost\nplop template $ blogpost\nplop content \"Consistency made simple!\" blog blogpost\nplop content _ blog blogpost\nplop snippet $ slideshow\n```\n\nKirby Plugins `index.php` and Config files created using `plop config`/`plop plugin` can be appended with lots of [Kirbys extensions](https://getkirby.com/docs/reference/plugins/extensions). These generators have the prefix `conf-`/`ext-`. Some of them might require you to add a file to the plugin folder first before appending a reference to that file.\n\n```bash\n\n# adding inline code to plugins\nplop plugin myname myplugin\nplop ext-collection myplugin allBlogpages\n\n# some files need to be referenced in the plugin index.php to work\nplop blueprint myplugin pages contactform\nplop ext-blueprint myplugin contactform\nplop template myplugin contactform\nplop ext-template myplugin contactform\n\n# some extensions do not have a file on their own but are inlined to index.php\nplop ext-route myplugin form/submit '' POST\n```\n\n### Usage of `config-` and `ext-` with existing files or when missing markers\n\nWhen creating files with `plop config` or `plop plugin` the generator will add markers to identify the location to append extensions. To make `config-` and `ext-` generators work with files not created by plop you have to manually add these strings to the respective files. Do not be afraid. It's very simple. The markers adhere to the following pattern:\n\n```\n[language specific comment] @PLOP_EXT_[extension name in uppercase, singular and low-dashes]\n```\n\n**example for PHP files**\n```php\n// @PLOP_EXT_HOOK\n// @PLOP_EXT_FILES_METHOD\n```\n\n**example site/config/config.php**\n```php\n\u003c?php\n\nreturn [\n    'hooks' =\u003e [\n        // Do not forget adding a `,` after existing array items\n        'page.update:after' =\u003e function () { },\n        // @PLOP_EXT_HOOK\n    ],\n];\n```\n\n### Autoloading of extensions\n\nSome extensions can be autoloaded using the [autoloader-for-kirby](https://github.com/bnomei/autoloader-for-kirby) composer package. Once required with composer you add the autoloader for each extension type you want once and it will register all files in subfolders correctly. This might save you calling the most frequently used `ext-` plop generators again and again.\n\n**/site/plugins/example/index.php**\n```php\n\u003c?php\n\nKirby::plugin('bnomei/example', [\n    'options' =\u003e [\n        // options\n    ],\n    // autoloader for two extension typs\n    'snippets' =\u003e autoloader(__DIR__)-\u003esnippets(),\n    'templates' =\u003e autoloader(__DIR__)-\u003etemplates(),\n    // other extensions\n]);\n```\n\n### Extending the plopfile\n\nYou can add custom code to your `./plopfile.js` as inline code or using files with `plop.load()`. This allows you to add your own generators.\n\n**plopfile.js**\n\n```js\nmodule.exports = function (plop) {\n    plop.load([\n        \"./site/plugins/kirby3-plopfile/plopfile.js\",\n        // add your custom files here...\n    ]);\n    // or any plop code here\n};\n```\n\n### Generators (60)\n\n-   [x] blueprint (folder, type, template, extension, import)\n-   [x] config-option (file, key, value)\n-   [x] config-hook (file, key, todo)\n-   [x] config-route (file, pattern, method, todo, [language, ])\n-   [x] config (filename, extensions, import)\n-   [x] content (title, parent, template, import, [language, slug,])\n-   [x] command (folder, file, options)\n-   [x] controller (folder, template, extension, options)\n-   [x] dockercompose (folder, type, [...])\n-   [x] ext-auth-challenge (folder, key, value)\n-   [x] ext-api-data (folder, key, params, todo)\n-   [x] ext-api-route (folder, params, pattern, method, todo)\n-   [x] ext-block-method (folder, key, params, todo)\n-   [x] ext-block-model (folder, key, value)\n-   [x] ext-blocks-method (folder, key, params, todo)\n-   [x] ext-blueprint (folder, file)\n-   [x] ext-cache-type (folder, key, value)\n-   [x] ext-class-alias (folder, key, value)\n-   [x] ext-class-loader (folder, key, value)\n-   [x] ext-collection-filter (folder, key, todo)\n-   [x] ext-collection-method (folder, key, params, todo)\n-   [x] ext-collection (folder, key, params, todo)\n-   [x] ext-command (folder, key, params, todo)\n-   [x] ext-controller (folder, file)\n-   [x] ext-field-method (folder, key, params, todo)\n-   [x] ext-field (folder, key, todo)\n-   [x] ext-file-method (folder, key, params, todo)\n-   [x] ext-files-method (folder, key, params, todo)\n-   [x] ext-hook (folder, hook, todo)\n-   [x] ext-layoutcolumn-method (folder, key, params, todo)\n-   [x] ext-layout-method (folder, key, params, todo)\n-   [x] ext-layouts-method (folder, key, params, todo)\n-   [x] ext-kirbytag (folder, key, attr, params, todo)\n-   [x] ext-option (folder, key, value)\n-   [x] ext-page-method (folder, key, params, todo)\n-   [x] ext-page-model (folder, key, value)\n-   [x] ext-pages-method (folder, key, params, todo)\n-   [x] ext-pages (folder, title, template, import)\n-   [x] ext-permission (folder, key, value)\n-   [x] ext-route (folder, pattern, method, params, todo, [language, ])\n-   [x] ext-section (folder, key, todo)\n-   [x] ext-site-method (folder, key, params, todo)\n-   [x] ext-snippet (folder, file)\n-   [x] ext-template (folder, file)\n-   [x] ext-user-method (folder, key, params, todo)\n-   [x] ext-user-model (folder, key, value)\n-   [x] ext-users-method (folder, key, params, todo)\n-   [x] ext-validator (folder, key, todo)\n-   [x] file (file, parent, template, import, [language,])\n-   [x] htaccess (folder, type)\n-   [x] indexphp (folder, type)\n-   [x] language (code, default, direction, locale, name, url, import)\n-   [x] model (folder, template, options)\n-   [x] plugin (user, repository, prefix, options)\n-   [x] robotstxt (folder)\n-   [x] setup (setup)\n-   [x] snippet (folder, file, options, import)\n-   [x] tdd (folder, options, ide)\n-   [x] template (folder, template, extension, options)\n-   [x] user (email, name, password, role, language)\n\n### Roadmap (1)\n\n-   [ ] ext-translation\n\n\u003e Please [create a new issue](https://github.com/bnomei/kirby3-plopfile/issues/new) if you want to suggest an idea or discuss existing generators.\n\n### Bypassing prompts\n\n-   Strings with whitespace need to wrapped in single quotes or double quotes.\n-   `import` can be a json string, relative or absolute path to a json or yml file. Bypassed json strings need to be wrapped in single quotes.\n-   `_` let you skip bypassing a prompt.\n-   `$` can be used on `folder` prompts to default to kirbys root. The plugin will `glob` to find the locations of your [Kirby roots](https://getkirby.com/docs/guide/configuration#custom-folder-setup) automatically, but the folders must exist.\n-   `none`/`defaults`/`all` can be used on `options` and `extensions` to select checkboxes when bypassing.\n-   `y`/`n` can be used on confirmation prompts.\n-   `file` and `folder` will be globbed and support wildcards. So you could write `*mydo*` instead of writing `config.www.mydomain.net.php`.\n\n\u003e ⚠️ If you use plop to generate files but set generator `extensions` to `none` or cherry pick them manually you might be missing some markers. I'd recommend to stick to `default` or `all` as values for these when bypassing or just press `enter` (aka default) when using the interactive dialog. You can always add the markers manually later.\n\n## Examples\n#### start interactive generator\n\n```bash\nplop\n```\n#### start blueprint generator directly\n\n```bash\nplop blueprint\n```\n#### blueprint with bypassed prompts (values forwarded from command line)\n\n```bash\nplop blueprint $ pages article .yml {}\n```\n#### content with known parent and template but prompt for title\n\n```bash\nplop content _ blog default {}\n```\n#### blueprint cloning\n\n```bash\nplop blueprint $ fields cd .yml\nplop blueprint $ fields dvd .yml cd.yml\n```\n#### config with options from escaped json string\n\n```bash\nplop config config.staging defaults '{\"debug\": true, \"home\": \"staging\" }'\n```\n#### content with fields from json/yml file\n\n```bash\nplop content \"Consistency, made easy!\" blog default n123.json\n```\n#### file with template and sorting number\n\n```bash\nplop file imgs/i456.jpg blog/consitency-made-easy hero '{\"sort\": 4}'\n```\n#### language with translations from json/yml file\n\n```bash\nplop language de n ltr de_DE Deutsch de trans_de.yml\n```\n#### plugin to add project specific extensions\n\n```bash\nplop plugin myname myplugin '' defaults defaults\n```\n#### create blueprint in plugin and \"extend\" the plugin index.php\n\n```bash\nplop blueprint myplugin pages merch .yml {}\nplop ext-blueprint myplugin pages/merch\n```\n\n#### snippet at /site/snippets with isset check for each key with fallback\n\n```bash\nplop snippet $ topnav defaults '{ \"title\": \"title fallback\", \"isOpen\": null }'\n```\n#### create snippet in plugin folder and then register it as an extension to that plugin\n\n```bash\nplop snippet myplugin slideshow defaults {}\nplop ext-snippet myplugin slideshow\n```\n#### template for laravel blade rendering\n\n```bash\nplop template $ booking .blade.php defaults\n```\n#### hook in plugin with todo comment\n\n```bash\nplop ext-hook myplugin page.changeStatus:after \"if a blogpost is published make kirby send an email to client\"\n```\n\n## .env File\n\nYou can add variables to your `.env` file to customize the plugins behaviour.\n\n### clipboard\n\n```\n# Code.exe' on Windows, 'code' on OSX\nPLOP_CLIPBOARD=\"Code.exe {{filepath}}:{{line}}:{{char}}\"\n\n# Sublime Text on OSX\nPLOP_CLIPBOARD=\"subl {{filepath}}:{{line}}:{{char}}\"\n\n# PHPStorm\nPLOP_CLIPBOARD=\"phpstorm --line {{line}} --column {{char}} {{filepath}}\"\n\n# disable copying to clipboard at end of generator\nPLOP_CLIPBOARD=false\n```\n\n### Kirby Roots\n\nIf you renamed a [root](https://getkirby.com/docs/guide/configuration#custom-folder-setup) the generator will not find it unless you set it in your `.env` file.\n\n```\n# PLOP_ROOT_[uppercase version of original root name]\nPLOP_ROOT_TEMPLATES=\"different\"\n# instead of \"templates\"\n```\n\n## Scaffolding: Generating new projects with composer and plop\n\nKirby offers various [installation methods](https://getkirby.com/docs/guide/quickstart#requirements__alternative-ways-to-install-kirby) from basic zip download to gitsubmodule and composer. Here is a new one using composer and plop.\n\n### generator-based composer project for public-storage setup\n\nRun the following commands in your project root. Create composer.json file, alter it with [jq](https://github.com/stedolan/jq), install Kirby and this plugin plus copying the plopfile to your project root folder.\n\n```bash\nyarn init\ncomposer init\njq -r '. + { config: { \"optimize-autoloader\": true } }' composer.json\ncomposer require php:\"\u003e=8.0 \u003c8.2.0\" getkirby/cms:^3.8 bnomei/kirby3-plopfile:^1.2\ncp site/plugins/kirby3-plopfile/example.plopfile.js plopfile.js\n```\n\n\u003e Since I will be using tailwind and laravel mix in most of my projects I am calling `yarn init` as well. The `setup` generator will then automatically exclude the `node_modules` folder via the created `.gitignore` file based on the existence of the `package.json` file. But you could always add stuff like this later manually.\n\nThen create the basic folder structure and core website files using generators.\n\n```bash\nplop setup public-storage\nplop indexphp public public-storage\nplop htaccess $\nplop robotstxt $\n```\n\nOptionally you could add php libraries with default config files for **Test Driven Development** (TDD) or use a customizable `docker-compose.yml` to serve your project locally.\n\n```bash\nplop tdd $ all sublime\n# then use ctr-v + enter to install composer dev-requirements\n\nplop dockercompose $ webdevops\ndocker-compose up\n```\n\n## Major dependencies\n\n-   [plop.js](https://github.com/plopjs/plop)\n-   [inquirer.js](https://github.com/SBoudrias/Inquirer.js)\n-   [handlebars.js](https://github.com/handlebars-lang/handlebars.js)\n-   [fast-glob](https://github.com/mrmlnc/fast-glob)\n-   [js-yaml](https://github.com/nodeca/js-yaml)\n-   [clipboardy](https://github.com/sindresorhus/clipboardy)\n\nNo node_module dependencies are included. To use this plugin run `npm i` or `yarn` in the plugin folder.\n\n## Disclaimer\n\nThis plugin is provided \"as is\" with no guarantee. Use it at your own risk and always test it yourself before using it in a production environment. If you find any issues, please [create a new issue](https://github.com/bnomei/kirby3-plopfile/issues/new).\n\n## License\n\n[MIT](https://opensource.org/licenses/MIT)\n\nIt is discouraged to use this plugin in any project that promotes racism, sexism, homophobia, animal abuse, violence or any other form of hate speech.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbnomei%2Fkirby3-plopfile","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbnomei%2Fkirby3-plopfile","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbnomei%2Fkirby3-plopfile/lists"}