Hotline

1. Overview

This document outlines the design of the WordPress plugin that provides a seamless Markdown editing experience within the standard block editor (Gutenberg). The plugin’s primary interface is a split-view “Markdown” editor with buttons in the markdown editor’s header, which provides access to all core functionalities: editing, importing, and exporting Markdown. The editing experience features a real-time, split-view interface similar to StackEdit.

2. Key Features

  • UI Integration: A “Markdown” button in the main WordPress editor header.
  • Split-View Editor: A modal or full-screen overlay with a side-by-side Markdown source and rendered HTML preview.
  • Content Synchronization: Ability to launch the editor with the current post’s content and sync changes back.
  • File Import: Import content from a .md file directly into the WordPress editor.
  • File Export: Export the current post’s content as a .md file, converting all blocks to Markdown.

3. Detailed Features

3.1. Main Editor UI Integration

  • “Markdown” Button:
  • A new button labeled “Markdown” shall be added to the top header bar of the WordPress block editor, next to core buttons like “Save draft” and “Preview”. Its placement should be similar to the “Edit with Elementor” or “Templately” buttons as shown in the user-provided reference image.
  • The button must be visually distinct but consistent with the WordPress admin UI.
  • On click, the button shall reveal a dropdown menu.
  • Dropdown Menu:
  • The dropdown menu will contain three options: 1. Edit as Markdown 2. Import from Markdown 3. Export as Markdown

3.2. “Edit as Markdown” Functionality

  • Trigger: Clicking the “Edit as Markdown” option from the dropdown menu.
  • Interface:
  • This action shall open a full-screen modal or overlay that contains the split-view editor.
  • The editor will be divided into two vertical panes:
  • Left Pane (Source): A text editor for raw Markdown input with syntax highlighting.
  • Right Pane (Preview): A rendered HTML preview of the content from the left pane.
  • The preview pane must update in real-time as the user types in the source pane, without requiring a manual refresh.
  • Content Loading: When triggered, the editor shall automatically parse the current content of the WordPress editor (all blocks) into a single Markdown document and load it into the left source pane.
  • Saving/Applying Changes:
  • The editor modal shall have two primary action buttons: “Apply Changes” and “Cancel”.
  • Clicking “Apply Changes” will convert the Markdown from the source pane into corresponding WordPress blocks, replacing the entire content of the standard editor. The modal will then close.
  • Clicking “Cancel” will close the modal without making any changes to the WordPress editor’s content.

3.3. “Import from Markdown” Functionality

  • Trigger: Clicking the “Import from Markdown” option from the dropdown menu.
  • Action:
  • This will trigger the browser’s native file upload dialog, filtered to accept only .md or .markdown files.
  • Upon file selection, the plugin will read the content of the .md file.
  • The Markdown text will be parsed and converted into corresponding WordPress blocks, replacing any content currently in the editor.
  • A confirmation alert (e.g., a JavaScript confirm() dialog or a custom modal) should appear before replacing the content, stating: “This will replace the current content of the editor. Are you sure you want to continue?”

3.4. “Export as Markdown” Functionality

  • Trigger: Clicking the “Export as Markdown” option from the dropdown menu.
  • Action:
  • The plugin will take all blocks currently in the WordPress editor and convert them into a single, clean Markdown document.
  • The post title should be included at the top of the file as an H1 header (# Post Title).
  • This action will trigger a browser download of the generated content as a .md file.
  • The default filename should be a sanitized version of the post title (e.g., the-future-of-human-ai-communication.md).

4. References & Code Repositories

This is an open-source project and the code and documentation can be found at…

4.1. WordPress Plugin Development

  • WordPress Plugin Boilerplate: A standardized foundation for building high-quality WordPress plugins. It provides a structured starting point.
  • Repository: https://github.com/DevinVinson/WordPress-Plugin-Boilerplate
  • Gutenberg Block Editor Handbook: Official documentation for adding UI elements, creating blocks, and interacting with the editor’s data. Essential for integration.
  • Documentation: https://developer.wordpress.org/block-editor/
  • Adding a button to the editor header: A tutorial or guide on how to add a custom button in the document header bar.
  • Reference: https://developer.wordpress.org/block-editor/reference-guides/slotfills/plugin-document-setting-panel/ (for sidebar) and research into PluginMoreMenuItem for the top-right menu.

4.2. Markdown Editor & Conversion Libraries

  • EasyMDE – Simple Markdown Editor: A beautiful and easy-to-implement JavaScript Markdown editor. It is a fork of SimpleMDE and is actively maintained. It can be configured for a split-view mode.
  • Repository: https://github.com/Ionaru/easy-markdown-editor
  • CodeMirror: A versatile in-browser code editor. It is the foundation for many Markdown editors and provides fine-grained control over the editing experience, including creating split-pane views.
  • Repository: https://github.com/codemirror/codemirror5
  • Turndown – HTML to Markdown Converter: An excellent library for reliably converting HTML content from the WordPress editor into clean Markdown for the “Edit” and “Export” features.
  • Repository: https://github.com/mixmark-io/turndown
  • Marked – Markdown Parser and Compiler: A fast and robust Markdown parser to convert Markdown input into HTML for the live preview pane and for converting imported content into blocks.
  • Repository: https://github.com/markedjs/marked