Skip to content
master
Switch branches/tags
Code

Kirby – Markdown field

Enhanced markdown editor for Kirby 3, community built.

screenshot


Overview

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 making a donation of your choice or purchasing your license(s) through my affiliate link.


1. Installation

Download and copy this repository to /site/plugins/markdown-field

Alternatively, you can install it with composer: composer require k-community/markdown-field


2. 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

3. Options

3.1. Available options

You have access to the very same options as the textarea field, and a few more:

Option Type Required Default Description
font Object false see below Sets the font options of the Markdown field. See below the available options
modals Boolean false true If set to false, link and email tags will be added without opening a modal
blank Boolean / String false false If set to true, editors will be presented an option to add the target: _blank option to link tags. If set to always, the option will be activated by default
invisibles Boolean false false If set to true, the invisibles button will be displayed in the toolbar, allowing you to show / hide hidden characters and whitespaces
direction Boolean false false If set to true, the current translation direction will be checked on init. Improves compatibility with rtl languages
query Object false see below Sets a custom query for the page selector dialog
size String false small Sets the empty height of the Markdown field

3.2. Font settings

You can set the desired font settings:

Option Type Required Default Description
family String false monospace Sets the font family. Available options: monospace, sans-serif
size String false regular Sets the font size. Available options: regular, small
scaling Boolean false false (monospace) / true (sans-serif) Whether headings should scale from 30px to 16px, or simply turn bold without any scaling

Note that you can choose to override only one or two of these options on a per-field basis, you don't have to explicitely set them all.

font:
  family: monospace
  scaling: false
  size: regular

3.3. Buttons

This field is packing the usual textarea buttons, and some more.

headlines can contain the whole range of headings from h1 to h6, and therefore accepts a sub-array (default is ['h1', 'h2', 'h3']):

buttons:
  - headlines
    - h1
    - h2
    - h3
    - h4
    - h5
    - h6

You also have access to 6 additional buttons:

buttons:
  - blockquote
  - horizontal-rule
  - strikethrough
  - pagelink
  - footnote

If you don't need it, you can also hide the toolbar:

buttons: false

The full list of available buttons:

buttons:
  - headlines
      - h1
      - h2
      - h3
      - h4
      - h5
      - h6
  - bold
  - italic
  - ul
  - ol
  - link
  - email
  - blockquote
  - horizontal-rule
  - strikethrough
  - pagelink
  - file
  - footnote

3.4. Query

You can limit the options shown in the Pagelink dialog, by setting a pagelink query (if unset, you'll be able to browse the entire website tree)

query:
  pagelink: kirby.page('my-page').children

3.5. Size

You can define the height of the field when empty. 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. First, set the size option to any string you'd like:

size: custom-size

Then in your panel.css:

.k-markdown-input-wrapper[data-size="custom-size"] .cm-s-default,
.k-markdown-input-wrapper[data-size="custom-size"] .CodeMirror-scroll {
    min-height: 15rem;
}

3.6. Default options

You can globally override the default options, instead of setting them on a per-field basis. In your site/config/config.php:

return [
  'community.markdown-field.size'       => 'small',
  'community.markdown-field.buttons'    => ['headlines', 'bold', 'italic', 'divider', 'link', 'email', 'file', 'code', 'divider', 'ul', 'ol'],
  'community.markdown-field.font'       => [
    'family'  => 'monospace',
    'scaling' => false,
    'size'    => 'regular',
  ],
  'community.markdown-field.query'      => [
    'pagelink' => null,
  ],
  'community.markdown-field.modals'     => true,
  'community.markdown-field.blank'      => false,
  'community.markdown-field.invisibles' => false,
  'community.markdown-field.direction' => false,
];

4. Custom buttons

Since 1.0.8 you can register your own buttons. This functionnality has a dedicated guide.


5. 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, else the hot-reload code will prevent it to work in any install.


6. License

MIT


7. Credits

Text editor:

Contributors:

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

Inspirations / K2 fields: