Markdown Details Markdown Editor

Latest Stable Version Latest Unstable Version Total Downloads Monthly Downloads Daily Downloads
Thankful to Krajee!
to get more out of us.

NOTE: This extension depends on the kartik-v/yii2-krajee-base extension which in turn depends on the yiisoft/yii2-bootstrap extension. Check the composer.json for this extension's requirements and dependencies that may be updated by composer.

This is an advanced markdown input widget to edit and preview Markdown content with configurable options. It is styled using Bootstrap 3.0. The key features available with this widget are:
  1. Configurable toolbar and buttons for formatting content
  2. Live preview of Markdown formatted text as HTML
  3. Maximize editor for full screen editing
  4. Implements PHP Markdown Extra and PHP SmartyPantsTypographer functionality as provided by the MarkdownConverter.
  5. Uses Bootstrap 3.0 styling wherever possible
  6. Allows saving/exporting of the text-editor contents as Text or HTML
  7. Configurable header, footer, and input options.
  8. Supports localization and customization of messages and content.
View a complete demo.

You can use the following settings to control the editor toolbar:
  1. BTN constants: array the header toolbar configuration. These will be used in setting up the toolbar.

    • BTN_BOLD = 1: Bold font format

    • BTN_ITALIC = 2: Italics font format

    • BTN_PARAGRAPH = 3: Add paragraph

    • BTN_NEW_LINE = 4: Add new line at the end

    • BTN_HEADING = 100: Add headings 1 to 6. Available dropdown items:

      • BTN_H1 = 101: Heading 1

      • BTN_H2 = 102: Heading 2

      • BTN_H3 = 103: Heading 3

      • BTN_H4 = 104: Heading 4

      • BTN_H5 = 105: Heading 5

      • BTN_H6 = 106: Heading 6

    • BTN_LINK = 5: Add a hyperlink

    • BTN_IMAGE = 6: Add an image link

    • BTN_INDENT_L = 7: Indent text

    • BTN_INDENT_R = 8: Unindent text

    • BTN_UL = 9: Unordered list

    • BTN_OL = 10: Ordered/Numbered list

    • BTN_DL = 11: Definition List

    • BTN_FOOTNOTE = 12: Add footnotes

    • BTN_QUOTE = 13: Add blockquote

    • BTN_CODE = 14: Inline code

    • BTN_CODE_BLOCK = 15: Code block

    • BTN_HR = 16: Horizontal Line

    • BTN_MAXIMIZE = 17: Maximize Editor

    • BTN_PREVIEW = 50 Preview Converted Text

    • BTN_EXPORT = 51 Export converted text. Available dropdown items:

      • BTN_EXPORT1 = 52 Save as Text

      • BTN_EXPORT2 = 53 Save as HTML

  2. toolbar: array the header toolbar configuration. List of button groups to be setup for a Bootstrap styled toolbar. Each button group is an array, which requires the following parameters:

    • buttons: array of buttons to be setup.

      • Array key is the button identifier. Should be one of the BTN constants.

      • Array values contain these special attributes

        • icon: string the name of the glyphicon to be embedded before the label

        • label: string the label for the button. By default is HTML encoded and supports localization.

        • encodeLabel: boolean whether the label is HTML encoded (if not set will use the global [[encodeLabels]] setting. If set to false will use the raw label as is.

        • items: array for dropdown list of links for each button. Configuration is similar to buttons array.

        • options: array HTML attributes for each button. If not set will use the global buttonOptions

    • options: HTML attributes for the button group

  3. footer: string the template to display the footer. The following special variables will be replaced:

    • {buttons}: array the configuration for footer toolbar buttons (see setDefaultFooter())

    • {message}: string the footer help message displayed (see footerMessage)

    Defaults to:

    <div class = "btn-toolbar pull-right">
        {buttons}
    </div>
    <div class="kv-md-hint">
        {message}
    </div>
    <div class="clearfix"></div>
  4. footerMessage: string help message displayed in footer

  5. footerButtons: array the footer toolbar configuration. Configuration is similar to header toolbar discussed above.

  6. showExport: boolean whether to show the Export button on the footer. Defaults to true.

  7. showPreview: boolean whether to show the Preview button on the footer. Defaults to true.

View a complete demo of the widget in operation
// add this in your view
use kartik\markdown\MarkdownEditor;

$customToolbar = [
    [
        'buttons' => [
            MarkdownEditor::BTN_BOLD => ['icon'=>'bold', 'title' => 'Bold'],
            MarkdownEditor::BTN_ITALIC => ['icon'=>'italic', 'title' => 'Italic'],
        ]
    ],
    [
        'buttons' => [
            // use a custom icon image
            MarkdownEditor::BTN_LINK => [
                'icon' => '',
                'label' => '<img src="/images/link.png">',
                'encodeLabel'=>false,
                'title' => 'URL/Link'
            ],
            // use another icon framewrok
            MarkdownEditor::BTN_IMAGE => [
                'icon' => '',
                'label' => '<span class="icon icon-image"></span>',
                'encodeLabel'=>false,
                'title' => 'Image'
            ],
        ],
    ],
];

// usage with model and a custom toolbar
echo MarkdownEditor::widget([
    'model' => $model, 
    'attribute' => 'markdown',
    'toolbar' => $customToolbar
]);

You can control various options for the Markdown Editor:

  • height: int the default height of the textarea input in px. Defaults to 260 px

  • encodeLabels: boolean whether to encode the button labels. If not encoded, it will use localized converted text for the label. Defaults to true

  • disabled: boolean whether the editor is to be entirely disabled. Defaults to false.

  • readonly: boolean whether the editor is to be entirely readonly. Defaults to false.

  • options: array the HTML attributes for the container holding the header, input, and footer. Defaults to ['class' => 'kv-md-editor']

  • headerOptions: array the HTML attributes for the header. Defaults to ['class' => 'kv-md-header btn-toolbar']

  • inputOptions: array the HTML attributes for the textarea input. Defaults to ['class' => 'kv-md-input']

  • footerOptions: array the HTML attributes for the footer. Defaults to ['class' => 'kv-md-footer']

  • previewOptions: array the HTML attributes for the preview container which will display the converted HTML text. Defaults to ['class' => 'kv-md-preview']

  • buttonOptions: array the HTML attributes for all toolbar buttons used in the header and footer. Defaults to ['class' => 'btn btn-sm btn-default']

  • buttonGroupOptions: array the HTML attributes for all toolbar button groups used in the header and footer. Defaults to ['class' => 'btn-group']

  • containerOptions: array the HTML attributes for the container holding all elements together. Defaults to ['class' => 'kv-md-container']

  • emptyPreview: string message displayed if preview is empty

  • previewProgress: string the content shown in preview window while loading / processing the preview

  • exportTextAlert: string alert message displayed before saving output as Text

  • exportHtmlAlert: string alert message displayed before saving output as HTML

  • exportHeader: string the header message appended at the beginning of the exported converted output

  • exportFileName: string the export file name for download. Defaults to markdown-export

  • exportMeta: string the export meta content to be appended at the beginning of the exported converted output (applicable only for HTML exporeted content). Defaults to:

    <!DOCTYPE html>
    <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
    <meta http-equiv="X-UA-Compatible" content="IE=edge;chrome=1"/>
    
  • exportCss: string the CSS applied to the exported converted output

  • bootstrapCssFile: string the bootstrap CSS file on CDN which will be used to format the exported HTML

View a complete demo of the widget in operation
Usage with Active Form
Markdown editor inside a modal
// add this in your view
use kartik\markdown\MarkdownEditor;

// usage with Active Form 
echo $form->field($model, 'markdown')->widget(
    MarkdownEditor::classname(), 
    ['height' => 300, 'encodeLabels' => false]
);

// usage inside a Modal window
use kartik\markdown\MarkdownEditor;
use yii\bootstrap\Modal;
Modal::begin([
    'id' => 'markdown-modal',
    'toggleButton' => ['label' => 'Show Modal', 'class' => 'btn btn-lg btn-primary'],
    'header' => '<h4 style="margin:0; padding:0">Markdown Editor Inside Modal</h4>',
    'size' => Modal::SIZE_LARGE,
    'clientOptions' => [
        'modal' => true,
        'autoOpen' => false,
    ],
]);
echo MarkdownEditor::widget([
    'name' => 'markdown',
    'value' => $value
]);
Modal::end();
?>

The editor has three modes of operation:

  1. Editing Mode: This is the default mode. The textarea input part of the editor is available for plain text entry. The toolbar buttons are enabled for markdown syntax formatting.

  2. Preview Mode: Mode for previewing the input markdown text as formatted HTML. The Preview button by default is located at the footer bottom right. The textarea input part of the editor is not available for editing when you are in preview mode. All toolbar formatting buttons are disabled, until the editor is toggled back to editing mode, by clicking the preview button again.

  3. Maximize Mode: The mode is activated by clicking the Maximize button located by default on the top right of the header. The editor and textarea are maximized within a modal window that fits the screen for easy editing. The editor can be toggled back to normal mode by clicking the Maximize button again.

Other editing notes:

  • You can undo or redo the last operation by pressing CTRL-Z or CTRL-Y keys respectively when in editing mode in the textarea. These are supported natively by most browsers

  • Alternatively, you can also undo/redo most toolbar button actions by clicking it again. Certain actions cannot be undone from the toolbar button like the Footnote insertion.

View a complete demo of the widget in operation
// add this in your view
use kartik\markdown\MarkdownEditor;

// usage with Active Form 
echo $form->field($model, 'markdown')->widget(
    MarkdownEditor::classname(), 
    ['height' => 300, 'encodeLabels' => false]
);

// usage inside a Modal window
use kartik\markdown\MarkdownEditor;
use yii\bootstrap\Modal;
Modal::begin([
    'id' => 'markdown-modal',
    'toggleButton' => ['label' => 'Show Modal', 'class' => 'btn btn-lg btn-primary'],
    'header' => '<h4 style="margin:0; padding:0">Markdown Editor Inside Modal</h4>',
    'size' => Modal::SIZE_LARGE,
    'clientOptions' => [
        'modal' => true,
        'autoOpen' => false,
    ],
]);
echo MarkdownEditor::widget([
    'name' => 'markdown',
    'value' => $value
]);
Modal::end();
?>