Bristlecone Markdown

Description

Bristlecone Markdown lets you write WordPress content in Markdown and keep the source for later edits. It is a self-contained replacement for Jetpack’s Markdown features, and its syntax is aligned with iA Writer (Markdown support only, not the rest of the iA Writer app).

The plugin is developed by Bristlecone IT Services. Plugin homepage: bristleconeit.com/bristlecone-markdown. Source and issues are on GitHub.

Writing surfaces

• Markdown block in the block editor, with source and preview tabs
• Optional Markdown-first editor (off by default): new posts start with a Markdown block, and new blocks prefer Markdown instead of a paragraph
• Whole-document Markdown for the Classic Editor, the REST API, and iA Writer’s Publish command
• Comment Markdown, enabled separately

HTML is stored in post_content (and in the block’s saved markup). The Markdown source is kept in post_content_filtered for document-mode posts, so the site still displays if you deactivate the plugin.

Syntax

CommonMark plus:

• Strikethrough ~~text~~
• Highlight ==text==
• Tables
• Footnotes [^1] and iA Writer inline footnotes [^this is the note.]
• Heading permalinks and cross-references ([Heading][], optional {#id} / [Label] on headings)
• Table of contents placeholder {{TOC}}
• YAML front matter and [%key] interpolation
• $inline$ and $$block$$ math (KaTeX, loaded only when needed)
• Superscript ^2 / y^(a+b)^ and subscript x~z
• Page break +++
• Unpublished // comments (stripped from output)
• MultiMarkdown-style citations [p. 23][#CiteKey]
• Safe inline HTML

Fenced code blocks can be highlighted on the server (no extra JavaScript). Theme developers can override .hljs or dequeue bristlecone-markdown-highlight.

Jetpack Markdown

If Jetpack Markdown is still active, Bristlecone Markdown does not convert posts or comments, so content is not processed twice. An admin notice offers a one-click control to disable the Jetpack Markdown module. Existing Jetpack Markdown posts (_wpcom_is_markdown or _wpcom_markdown, plus post_content_filtered) are adopted automatically afterward.

When that module is off, existing jetpack/markdown Gutenberg blocks stay editable (they are not treated as missing blocks). Saving a post rewrites them to bristlecone/markdown. The inserter still offers only the Bristlecone Markdown block. An optional Tools converter can rewrite every matching post at once; it is off by default and requires Settings → Bristlecone Markdown → “Enable Jetpack Markdown block converter under Tools”, then Tools → Bristlecone Markdown Converter, then a confirmation checkbox.

Other Markdown blocks

This plugin does not replace every Markdown plugin. It can adopt a few Gutenberg block names so existing posts stay editable:

• simple-markdown/markdown-block (attribute content) when that plugin is not already registering the block
• Custom identifiers under Settings → Advanced: one namespace/block-name|attribute per line (for example acme/markdown|content). If |attribute is omitted, Bristlecone tries source, then content, then markdown

Aliases are hidden from the inserter and convert on save. The same Tools checkbox unlocks a scanner that lists unregistered block names containing “markdown” for review. Nothing is rewritten or added to the custom list until you select names and confirm. Names that look like editor comments (for example markdown-comment) are flagged and left unchecked.

iA Writer

In iA Writer you can publish drafts to WordPress 5.6+ over the REST API as Markdown. Bristlecone Markdown converts that body on save and returns Markdown source to non-Gutenberg clients on edit.

YAML keys such as title, excerpt, tags, categories, and slug are mapped onto the WordPress post when present. If title is applied to an auto-draft and slug is omitted, the permalink is generated from the title. Other keys are stored and available for [%key] interpolation.

Intentionally not converted

• Task lists (- [ ]) — local writing aid; skip on publish
• Content Blocks / file transclusion — these depend on iA Writer’s local library. WordPress cannot see that library. Compile or export the transcluded document in iA Writer before publishing.

Footnotes

Footnote IDs are namespaced with the post ID (bristlecone-markdown-fn-{id}-…) so archives and the core Footnotes block are less likely to clash. New posts are converted again after insert so those IDs are not left as a placeholder. Footnote markup can still be sensitive to theme CSS and to wpautop on classic (non-block) content; we disable wpautop for document-mode Markdown posts. If a theme styles sup unusually, footnotes may need a CSS tweak. Footnote lists still render on archive views for each post that contains them.