PHPackages                             k-community/markdown-field - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Parsing & Serialization](/categories/parsing)
4. /
5. k-community/markdown-field

ActiveKirby-plugin[Parsing & Serialization](/categories/parsing)

k-community/markdown-field
==========================

Super-sophisticated markdown editor for Kirby 4

4.0.0(3mo ago)16627.4k↓18.8%17[1 issues](https://github.com/fabianmichael/kirby-markdown-field/issues)MITTypeScriptPHP >=8.3.0

Since Jan 16Pushed 2mo ago6 watchersCompare

[ Source](https://github.com/fabianmichael/kirby-markdown-field)[ Packagist](https://packagist.org/packages/k-community/markdown-field)[ Docs](https://github.com/fabianmichael/kirby-markdown-field)[ GitHub Sponsors](https://github.com/fabianmichael)[ RSS](/packages/k-community-markdown-field/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (5)Versions (29)Used By (0)

Markdown Field for Kirby
========================

[](#markdown-field-for-kirby)

Enhanced, extensible Markdown field for Kirby CMS. Now available in version 2 4!

**Features:**

- Sophisticated, but subtle highlighting for Markdown and Kirbytext
- Context-based format toggling (almost WYSIWYG-like)
- Smart indentation for wrapping headlines, list items, and blockquotes
- Keyboard shortcuts for most actions
- Custom toolbar buttons
- Custom syntax highlights
- Option to show whitespace characters
- Clickable URLs
- Configurable Markdown syntax (e.g. choose from `_italic_` or `*italic*`)
- Replaces Kirby’s default [Markdown block](https://getkirby.com/docs/reference/panel/blocks/markdown) with one, that also supports syntax-highlighting.
- Support for touch-based devices and great performance (thanks to [CodeMirror 6](https://codemirror.net/))
- Optionally convert all permalinks to regular URLs for all Kirbytext (opt-in)

💡 **TL;DR:** The Markdown field/editor/suite, you all have been waiting for!

[![Screenshot of the editor field](https://private-user-images.githubusercontent.com/395617/287229906-590ebc77-fe2e-46ae-98f4-e565f86fc82f.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzQ3MzQ2MjYsIm5iZiI6MTc3NDczNDMyNiwicGF0aCI6Ii8zOTU2MTcvMjg3MjI5OTA2LTU5MGViYzc3LWZlMmUtNDZhZS05OGY0LWU1NjVmODZmYzgyZi5wbmc_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjYwMzI4JTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI2MDMyOFQyMTQ1MjZaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT1jNjE0M2JkMWY2MTgwYWFmOGFmNmQ2YThiNTAxMzVlNzhjMjZjYjUyNjAzODdhZmIyZjIyMGZlMzFhYzJlOTM3JlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCJ9.d2jKPHsrF5DzrfMxoYwT2JjjoyhSlrYea7NKYki3WLI)](https://private-user-images.githubusercontent.com/395617/287229906-590ebc77-fe2e-46ae-98f4-e565f86fc82f.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzQ3MzQ2MjYsIm5iZiI6MTc3NDczNDMyNiwicGF0aCI6Ii8zOTU2MTcvMjg3MjI5OTA2LTU5MGViYzc3LWZlMmUtNDZhZS05OGY0LWU1NjVmODZmYzgyZi5wbmc_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjYwMzI4JTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI2MDMyOFQyMTQ1MjZaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT1jNjE0M2JkMWY2MTgwYWFmOGFmNmQ2YThiNTAxMzVlNzhjMjZjYjUyNjAzODdhZmIyZjIyMGZlMzFhYzJlOTM3JlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCJ9.d2jKPHsrF5DzrfMxoYwT2JjjoyhSlrYea7NKYki3WLI)

Note

This plugin is completely free and published under the MIT license. However, if you are using it in a commercial project and want to help me keep up with maintenance, please consider to **[❤️ sponsor me](https://github.com/sponsors/fabianmichael)** for securing the continued development of the plugin.

Table of Contents
-----------------

[](#table-of-contents)

- [Markdown Field for Kirby](#markdown-field-for-kirby)
    - [Table of Contents](#table-of-contents)
    - [Installation](#installation)
    - [Setup](#setup)
    - [Options](#options)
        - [Global options](#global-options)
        - [Field options](#field-options)
        - [Font settings](#font-settings)
        - [Buttons](#buttons)
            - [Simple configuration](#simple-configuration)
            - [Advanced configuration](#advanced-configuration)
        - [Keyboard Shortcuts](#keyboard-shortcuts)
            - [Block Formats](#block-formats)
            - [Inline Formats](#inline-formats)
            - [Other](#other)
            - [URLs](#urls)
        - [Size](#size)
    - [Extension API](#extension-api)
        - [Custom options for files, and uploads](#custom-options-for-files-and-uploads)
    - [Development](#development)
    - [Migration Guide](#migration-guide)
        - [From version 2/3 to 4](#from-version-23-to-4)
        - [From version 1 to 2](#from-version-1-to-2)
    - [Known Issues](#known-issues)
        - [What’s not supported (and never will be)](#whats-not-supported-and-never-will-be)
    - [License](#license)
    - [Credits](#credits)

---

Installation
------------

[](#installation)

This version of the plugin requires PHP 8.4+, Kirby 5 and your Kirby installation must have UUIDs enabled. The recommended way of installing is by using Composer:

```
$ composer require fabianmichael/kirby-markdown-field

```

Alternatively, download and copy this repository to `/site/plugins/markdown-field`

Setup
-----

[](#setup)

This field can replace any `textarea` field you have set up and works out of the box with as little config as:

```
editor:
  label: My markdown editor
  type: markdown
```

Options
-------

[](#options)

### Global options

[](#global-options)

| Option | Type | Default | Description | | `fabianmichael.markdown-field.convertPermalinks` | `bool` | `false` | Replaces all permalinks in href/src attributes in Kirbytext with the regular URL, similar to what `https://getkirby.com/docs/reference/templates/field-methods/permalinks-to-urls` does but also works for absolute URLs. |

### Field options

[](#field-options)

You have access to the very same options as [the textarea field](https://getkirby.com/docs/reference/panel/fields/textarea), and a few more:

OptionTypeRequiredDefaultDescriptionfontstring`false``monospace`Sets the font family (`sans-serif` or `monospace`)sizeString`false``small`Sets the empty height of the Markdown fieldkirbytextbool`false``true`Use Kirbytext syntax for links, images etc.### Font settings

[](#font-settings)

You can choose between monospace (`monospace`) and sans-serif (`sans`) font. The monospace font offers a more sophisticated layout with indentation for multiline list elements, headings, and blockquote – things, which would be much harder to implement (and slower to calculate) for a proportional font.

While the sans-serif might be more appealing to non-technical writers at first, the monospace should be the preferred version in most cases.

### Buttons

[](#buttons)

This field is packing the usual [textarea](https://getkirby.com/docs/reference/panel/fields/textarea) buttons and many more.

If you don't want to show any buttons, you can hide the toolbar. This will also disable the keyboard shortcuts for all formats.

```
buttons: false
```

#### Simple configuration

[](#simple-configuration)

If you just want to add the buttons without further configuration, just provide a YAML array, e.g.:

```
buttons:
  - headlines
  - divider
  - bold
  - italic
  - strikethrough
  - code
  - highlight # not supported by Kirby’s markdown parser by default
  - divider
  - link
  - file
  - divider
  - blockquote
  - hr
  - footnote # Markdown extra only
  - ul
  - ol
  - divider
  - invisibles
```

#### Advanced configuration

[](#advanced-configuration)

Some buttons may be configures with advanced options. To ensure compatibility with the Symfony YAML parser, you should only use named buttons in this case:

```
buttons:
  headlines:
    - h1 # enabled by default
    - h2 # enabled by default
    - h3 # enabled by default
    - h4
    - h5
    - h6
  divider__0: true # start at 0 and count up
  bold: true # or `**` or `__` to configure syntax
  italic: true # or `*` or `_` to configure syntax
  strikethrough: true
  code: true
  highlight: true # not supported by Kirby’s markdown parser by default
  divider__1: true
  link:
    kirbytext: null # `null` = use field’s default, `false` = markdown link, `true´ = force Kirbxtext syntax
    blank: true # add toggle for new tab (only for Kirbytext syntax)
    options:
      - url
      - page
      - file
      - email
      - tel
      - anchor
      - custom # same as `options` property for the link field
  file: true
  divider__2: true
  blockquote: true
  hr: true # `***`, or `---`/`___` to configure syntax
  footnote: true # Markdown extra only
  ul: true # `-`, `*` or`+` to configure syntax
  ol: true
  divicer__3: true
  invisibles: true
```

### Keyboard Shortcuts

[](#keyboard-shortcuts)

ℹ️ Keyboard shortcuts are only available for those buttons/heading levels enabled in the toolbar.

#### Block Formats

[](#block-formats)

FormatMac/iOSLinux/WindowsHeading 1`⌥⌃1``Alt+Shift+1`Heading 2`⌥⌃2``Alt+Shift+2`Heading 3`⌥⌃3``Alt+Shift+3`Heading 4`⌥⌃4``Alt+Shift+4`Heading 5`⌥⌃5``Alt+Shift+5`Heading 6`⌥⌃6``Alt+Shift+6`Quote`⌥⌃q``Alt+Shift+q`Bullet List`⌥⌃U``Alt+Shift+u`Ordered List`⌥⌃O``Alt+Shift+o`#### Inline Formats

[](#inline-formats)

FormatMac/iOSLinux/WindowsBold`⌘B``Ctrl+b`Italic`⌘I``Ctrl+i`Link`⌘K``Ctrl+k`Strikethrough`⌥⌃D``Alt+Shift+d`Code`⌥⌃X``Alt+Shift+x`Footnote`⌥⌃F``Alt+Shift+f`#### Other

[](#other)

FormatMac/iOSLinux/WindowsShow Whitespace`⌥⌃I``Alt+Shift+i`Open clicked URL in new tab`⌘+Click``Ctrl+Click`#### URLs

[](#urls)

- When you select some text and paste a URL, it will automatically create a link tag and use the current selection as link text.

### Size

[](#size)

You can define the height of the field when empty. The default is `two-lines`, which mimics the textarea's default empty height.

If you want the field to mimic a text field but with some markdown highlighting on top of it, set the size to `one-line` and `buttons: false`.

All predefined sizes are:

```
- one-line
- two-lines
- small (same as textarea)
- medium (same as textarea)
- large (same as textarea)
- huge (same as textarea)
```

Note that you can make the default height any height you want with some [custom panel CSS](https://getkirby.com/docs/reference/system/options/panel#custom-panel-css). First, set the `size` option to any string you'd like:

```
size: custom-size
```

Then in your `panel.css`:

```
.k-markdown-input-wrap[data-size='custom-size'] {
  --cm-min-lines: 20;
}
```

Extension API
-------------

[](#extension-api)

The API has changed from version 1, old plugins are not compatible anymore and require a few adjustments. See `extension-examples` folder.

There are two types of extensions, which allow you to extend the editor to adjust it better to your specific needs:

- **Custom buttons:** You can define your own buttons, which can be added to the editor toolbar. Buttons can define keyboard shortcuts, display dropdowns, and even show a popup.
- **Custom extensions:** You can define your own editor extensions. An example can be found in the `extension-examples/indent-with-tab` folder.
- **Custom highlights:** You can define regex-based custom highlights, which allow you to highlight any text, such as markup for custom syntax (e.g. global text snippets or Wiki-style links)

### Custom options for files, and uploads

[](#custom-options-for-files-and-uploads)

Your extension can use a special endpoint to extend the base options for pages, files, and uploads with parameters set in the button configuration. See an example in the `extension-examples/custom-pagelink` folder.

```
// special routes to read options from the button configuration
this.input.endpoints.field + '/myextension/uploads';
this.input.endpoints.field + '/myextension/files';
```

The end user can configure options for your extension as part of the button configuration:

```
text:
  type: markdown
  files: […]
  buttons:
    myextension:
      pages:
        query: site.index
        info: '{{ page.tags }}'
```

Development
-----------

[](#development)

- Clone the repo
- `cd` to your newly created folder (named `kirby-markdown-field`, or whatever you have chosen)
- `npm install` to get all the dependencies
- Then:

```
# Dev mode
npm run dev

# Build plugin + autoprefix styles
npm run build
```

> You **must** run the build process before pushing the repo, or else the hot-reload code will prevent it from working in any install.

Migration Guide
---------------

[](#migration-guide)

### From version 2/3 to 4

[](#from-version-23-to-4)

- The `pagelink` button was removed in favor of a generic `link` button that supports all link types
- The API for plugins may have some minor changes, please report issues if your plugins don’t work any longer and you don't know how to fix it
- Removed support for clickable panel URLs for now, because UUID page and file links would require more magic than what I am able to handle at the moment
- URLs are now clickable without pressing down the meta key, because that key is already used by Kirby for selecting blocks.
- URLs are now real native HTML links that support right clicks
- Since Kirby will switch from the Spyc to the Symfony YAML parser in a future release, you should review your `buttons` configuration if you want everything to stay compatible.
- `link` button option `style` has been renamed to `kirbytext` and no accepts a boolean

### From version 1 to 2

[](#from-version-1-to-2)

- Setting available **headline levels** now works a bit differently, see [3.3 Buttons](#33-buttons). This was necessary to allow for multiple, configurable dropdowns in the future/extensions.
- The `horizontal-rule` button was renamed to `hr`.
- The `modals` option has been removed. Clicking the link button will always display a modal.
- The `link` and `email` buttons have been merged into a single popup.
- The `blank` option has been moved from the global options to the link button.
- The **invisibles** option has been replaced by a button, called `invisibles`. Just add that to your toolbar setup instead.
- The API for registering custom buttons has changed. See `extension-examples` folder for examples.
- Font scaling options have been removed. Version 2 of the Markdown field only accepts `monospace` and `sans` as font options. if you need scaling of headlines, consider using Kirby’s Blocks field instead.
- The global field options have been removed. Use field presets instead. (see ).
- The `direction` option has been removed. CodeMirror 6 automatically determines the current text direction of the panel.

Known Issues
------------

[](#known-issues)

- **Kirbytags:** In some edge cases with nested parenthesis or nested Kirbytags, the highlighting can differ from how Kirby parses the markup. This shouldn’t be an issue for most daily use cases. You can also not have multiple consecutive line breaks within Kirbytags, or the highlighter will fail. This is because of the way Markdown makes a clear separation between block and inline elements.
- **Kirbytags in HTML blocks** are not highlighted, because CodeMirror uses its own HTML Parser for that, which deactivates all Markdown highlighting within these. Parsedown Extra supports the `markdown="1"` attribute on HTML block-level elements, which is not supported by CodeMirror’s Markdown parser.
- **Inline Format toggling:** The selection will sometimes behave in unexpected ways when dealing with very complex re-formatting. Solving this would need a more sophisticated selection/caret-tracking during all transformations. IMHO, it still works better than in most other Markdown editors and does not lead to data loss, so ¯\\\_(ツ)\_/¯.

### What’s not supported (and never will be)

[](#whats-not-supported-and-never-will-be)

The way Markdown is used nowadays has changed since its inception, especially since GFM ("GitHub-Flavored Markdown") became popular and added some elements to the language.

- **Setext-style headings:** If you don’t know what these are, just forget about them. There is basic highlighting, but they are neither recognized as headings by the toolbar nor respected when changing formats. Use ATX-style headings instead (e.g. `## Heading Level 2`).
- **Indended code blocks:** Use fenced code blocks instead.

License
-------

[](#license)

MIT (but you are highly encouraged to **[❤️ sponsor me](https://github.com/sponsors/fabianmichael)** if this piece of software helps you to pay your bills).

Credits
-------

[](#credits)

**Text editor:**

- [CodeMirror 6](https://codemirror.net/6/) by [Marijn Haverbeke](https://marijnhaverbeke.nl/)

**Contributors:**

@fabianmichael, @sylvainjule, @medienbaecker, @mtsknn, @nsteiner, @rasteiner, @thomasfahrland, @johannschopplich

**Inspired by:**

- [ProseMirror](https://prosemirror.net/) by [Marijn Haverbeke](https://marijnhaverbeke.nl/)
- [Visual Markdown Editor for Kirby 2](https://github.com/JonasDoebertin/kirby-visual-markdown) by [Jonas Döbertin](https://github.com/JonasDoebertin)
- [SimpleMDE for Kirby 2](https://github.com/medienbaecker/kirby-simplemde) by [Thomas Günther](https://github.com/medienbaecker)
- [Kirby’s Writer Field](https://getkirby.com/docs/reference/panel/fields/writer) by [Bastian Allgeier](https://bastianallgeier.com/)
- [tiptap – rich-text editor for Vue.js](https://tiptap.dev/)

###  Health Score

64

—

FairBetter than 99% of packages

Maintenance84

Actively maintained with recent releases

Popularity44

Moderate usage in the ecosystem

Community24

Small or concentrated contributor base

Maturity86

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 58.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~107 days

Recently: every ~238 days

Total

25

Last Release

102d ago

Major Versions

1.0.9 → 2.0.0-beta-12021-12-13

2.2.0 → 3.0.0-alpha.12023-11-29

3.0.0-alpha.2 → 4.0.02026-02-05

PHP version history (4 changes)2.0.0-beta-1PHP >=7.4.0

2.0.0-rc2PHP >=8.0.0

3.0.0-alpha.2PHP >=8.1.0

4.0.0PHP >=8.3.0

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/14079751?v=4)[Sylvain Julé](/maintainers/sylvainjule)[@sylvainjule](https://github.com/sylvainjule)

---

Top Contributors

[![fabianmichael](https://avatars.githubusercontent.com/u/395617?v=4)](https://github.com/fabianmichael "fabianmichael (280 commits)")[![sylvainjule](https://avatars.githubusercontent.com/u/14079751?v=4)](https://github.com/sylvainjule "sylvainjule (152 commits)")[![medienbaecker](https://avatars.githubusercontent.com/u/7975568?v=4)](https://github.com/medienbaecker "medienbaecker (24 commits)")[![s3ththompson](https://avatars.githubusercontent.com/u/970121?v=4)](https://github.com/s3ththompson "s3ththompson (4 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (3 commits)")[![mtsknn](https://avatars.githubusercontent.com/u/2226144?v=4)](https://github.com/mtsknn "mtsknn (3 commits)")[![johannschopplich](https://avatars.githubusercontent.com/u/27850750?v=4)](https://github.com/johannschopplich "johannschopplich (3 commits)")[![rasteiner](https://avatars.githubusercontent.com/u/6684137?v=4)](https://github.com/rasteiner "rasteiner (2 commits)")[![tobimori](https://avatars.githubusercontent.com/u/29142128?v=4)](https://github.com/tobimori "tobimori (1 commits)")[![dewey](https://avatars.githubusercontent.com/u/790262?v=4)](https://github.com/dewey "dewey (1 commits)")[![luxuryluke](https://avatars.githubusercontent.com/u/57873?v=4)](https://github.com/luxuryluke "luxuryluke (1 commits)")[![nilshoerrmann](https://avatars.githubusercontent.com/u/25466?v=4)](https://github.com/nilshoerrmann "nilshoerrmann (1 commits)")[![onezerodigits](https://avatars.githubusercontent.com/u/111835?v=4)](https://github.com/onezerodigits "onezerodigits (1 commits)")[![thomasfahrland](https://avatars.githubusercontent.com/u/24317084?v=4)](https://github.com/thomasfahrland "thomasfahrland (1 commits)")

---

Tags

codemirrorkirby-cmskirby-pluginkirby5markdown

###  Code Quality

TestsPHPUnit

Static AnalysisPsalm

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/k-community-markdown-field/health.svg)

```
[![Health](https://phpackages.com/badges/k-community-markdown-field/health.svg)](https://phpackages.com/packages/k-community-markdown-field)
```

###  Alternatives

[masterminds/html5

An HTML5 parser and serializer.

1.8k242.8M229](/packages/masterminds-html5)[sabberworm/php-css-parser

Parser for CSS Files written in PHP

1.8k191.2M65](/packages/sabberworm-php-css-parser)[jms/metadata

Class/method/property metadata management in PHP

1.8k152.8M88](/packages/jms-metadata)[jms/serializer-bundle

Allows you to easily serialize, and deserialize data of any complexity

1.8k89.3M627](/packages/jms-serializer-bundle)[meyfa/php-svg

Read, edit, write, and render SVG files with PHP

54613.9M42](/packages/meyfa-php-svg)[rybakit/msgpack

A pure PHP implementation of the MessagePack serialization format.

4068.7M74](/packages/rybakit-msgpack)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)