=== Markdown Renderer for GitHub ===
Contributors: wakalab
Tags: markdown, github, syntax-highlighting, mermaid, documentation
Requires at least: 6.8
Tested up to: 7.0
Requires PHP: 8.2
Stable tag: 2.11.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Render GitHub Flavored Markdown in WordPress: Shiki code highlighting, Mermaid diagrams, and Chart.js charts. For documentation and dev blogs.

== Description ==

Markdown Renderer for GitHub brings GitHub Flavored Markdown (GFM) rendering to WordPress for technical blogs, documentation sites, tutorials, code portfolios, and developer resources. Add Markdown in the block editor or with the `[gfmr_markdown]` shortcode, then render code, tables, task lists, diagrams, and charts on the front end.

The free plugin includes:

* GitHub Flavored Markdown rendering with tables, task lists, strikethrough, autolinks, footnotes, and emoji shortcodes such as `:rocket:`
* GitHub-style alerts: `> [!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, and `[!CAUTION]` callouts
* Native grammars for 30+ programming languages, plus fallback handling for many more
* GitHub Light, GitHub Dark, and system-aware code themes
* Mermaid diagrams with interactive controls
* 8 chart types through Chart.js charts from `chart` fenced code blocks
* Optional PlantUML rendering through a configured external PlantUML/Kroki server
* Table of Contents, structured data, multilingual URL options, and server-side rendering controls
* A built-in admin manual with Getting Started, Usage, FAQ, Troubleshooting, Support, and System Info tabs
* WordPress Abilities API support on WordPress 6.9+ for AI agents such as Claude Code and Codex

A separate Pro add-on may provide advanced workflow features such as enhanced code-block options, custom themes, higher-level AI orchestration, and priority support. Core Markdown, syntax highlighting, Mermaid, Chart.js, PlantUML, and the basic settings are included in the free plugin.

Detailed user guidance is available inside the plugin settings screen after activation. This keeps the manual, FAQ, troubleshooting, support guidance, and non-secret system information close to the WordPress admin workflow without requiring a separate documentation website.

== Installation ==

**Install from WordPress admin:**

1. Go to Plugins > Add New.
2. Search for "Markdown Renderer for GitHub".
3. Click Install Now.
4. Click Activate.

**Install from a ZIP file:**

1. Go to Plugins > Add New > Upload Plugin.
2. Upload the plugin ZIP file.
3. Click Install Now.
4. Click Activate.

**First setup after activation:**

1. Open Markdown Renderer for GitHub > Manual in the WordPress admin menu.
2. Read the Getting Started tab.
3. Add a Markdown block to a post or page, or wrap Markdown in the `[gfmr_markdown]` shortcode.
4. Preview the front-end page.
5. Adjust the Code Block theme, Markdown style preset, Table of Contents, diagram, structured data, multilingual, or server-side rendering settings only when your site needs them.

== Frequently Asked Questions ==

= What should I do first after installation? =

Open Markdown Renderer for GitHub > Manual, read the Getting Started tab, then create or edit a post with the Markdown block. Preview the front-end page and adjust the Code Block settings if needed.

= How do I add Markdown content? =

Use the Markdown block in the block editor. In the Classic editor, widgets, or templates, wrap Markdown in the `[gfmr_markdown]` enclosing shortcode. The shortcode renders through the same core pipeline as the block.

= How do I add a note or warning callout? =

Use the GitHub alert syntax: start a blockquote whose first line is `> [!NOTE]`, then write the body on the following quoted lines. `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, and `[!CAUTION]` work the same way. The keyword must be alone on that first line, otherwise the block stays an ordinary blockquote.

= What should I check if settings are not reflected? =

Save the settings, clear page cache, CDN cache, browser cache, and any asset optimization cache. Then check a front-end post that actually contains a Markdown block or `[gfmr_markdown]` shortcode.

= Can I use this with my theme or cache plugin? =

Usually yes. If output looks stale or broken, temporarily disable cache, minification, defer, and combine settings. If styles still look wrong, test briefly with a default WordPress theme to isolate theme CSS conflicts.

= Does this plugin send content to external services? =

By default, no. Shiki, Mermaid, Chart.js, and markdown-it are bundled locally and served from your WordPress installation. Optional PlantUML and server-side Mermaid rendering can send diagram source to an external renderer only after you enable and configure those features. See Third Party Services for details.

= What is the difference between the free and Pro versions? =

The free plugin includes the main rendering features: GFM, Shiki, Mermaid, Chart.js, PlantUML, Table of Contents, structured data, multilingual options, and basic AI agent abilities. Pro is a separate add-on for advanced workflow features and priority support. You do not need Pro for the core rendering features.

= What happens to my settings when I delete the plugin? =

Nothing is removed by default: deleting the plugin leaves its settings, caches, and post metadata in the database, so reinstalling restores your configuration. If you want a clean removal, enable "Remove Data on Uninstall" on the General Settings tab before deleting the plugin. That option is off by default and cannot be undone once the plugin is deleted.

= Where can I get support? =

Free plugin usage questions and reproducible bugs should go to the WordPress.org support forum. Pro license, billing, contract, refund, and account questions should not be posted in the WordPress.org forum; use the support guidance shown inside the plugin admin screen.

= What information should I include in a support request? =

Include WordPress version, PHP version, plugin version, theme, affected feature, steps to reproduce, and relevant non-secret System Info from the plugin settings screen. Never share license keys, API keys, Application Passwords, tokens, cookies, or private account information.

== Screenshots ==

1. **Block Editor** - Add and edit Markdown in the block editor with live syntax highlighting
2. **Syntax Highlighting** - Front-end code blocks with Shiki highlighting and a copy button
3. **Mermaid Diagrams** - Mermaid flowchart rendered from a fenced code block on the front end
4. **Tables and Formatting** - GitHub Flavored Markdown tables, text formatting, lists, and blockquotes
5. **Mobile Rendering** - Responsive Markdown output on mobile-width screens
6. **Code Block Settings** - Theme selection and live preview in the plugin settings screen
7. **Chart.js Data Visualization** - Chart.js bar chart rendered from a `chart` fenced code block
8. **Markdown to Rendered Output** - Raw Markdown alongside its polished WordPress rendering

== Changelog ==

= 2.11.2 =
* Add GitHub-style alerts (NOTE/TIP/IMPORTANT/WARNING/CAUTION)
* Add GitHub-style emoji shortcode support
* Add opt-in uninstall data cleanup
* Gate destructive settings behind explicit confirmation in AI abilities
* Guard early-exit vendor restore and stale vendor.backup detection
* Lazy-load markdown-it fallback renderer for multilingual blocks
* Cover vendor.backup.stale-* dirs in all exclusion configs

= 2.11.1 =
* Bake WP-CLI and apt tooling into the E2E image
* Compare downloads_drop within the same release class
* Back out the v2.11.1 bump that PR #1129 swept in

= 2.11.0 =
* add Pro code-block editor translations and JSON coverage test
* add Pro custom theme support with fail-closed validation
* integrate custom Shiki themes into runtime and SSR
* add custom Shiki theme admin UI
* add Free-core strip for Pro custom Shiki themes
* Add modest Free vs Pro info section to settings Manual tab
* add Pro-gated financial candlestick and OHLC charts
* invite wp.org review and announce external links for a11y
* add high-level AI orchestration abilities
* Add screenshots 7-8 for Chart.js and rendered output preview
* add C4 Model architecture diagrams via a c4 code block
* fix chronically-failing Woodpecker steps
* fix standalone-mode fatals and Docker Pro setup race (#1074)
* register custom Shiki theme objects in frontend createHighlighter()
* place file args before --fix in .lintstagedrc.js commands
* remove dead gfmr-highlighter.js module and its stale dependents
* pin npm to <11 and guard esbuild lock subtree drop
* Increase ps aux memory test timeout and resync changelog

= 2.10.5 =
* add availability field to roadmap schema and validation
* add Pro code-block enhancement pack with Free-core strip (#1033)
* sync Pro bundled Free core version during release
* configure GFMR Pro Lemon Squeezy product
* connect GFMR Pro updater endpoint
* align version metadata with bundled core
* repair license activation package
* unify LSQ update endpoint path and add drift guard
* guard pro-package.sh copy steps against leaked symlinks
* register wp-cli gfmr command via classmap autoload trigger

= 2.10.4 =
* Add in-plugin Manual content to settings page
* add shared client-side SVG allowlist sanitizer
* update GfmrLicenseManagerTest/GfmrPremiumFeatureGateTest to match current implementation
* fix Patchwork/Brain Monkey bootstrap ordering for 3 test files
* reconcile ExternalServiceDependencyTest with current implementation
* allow markdown-label tags and text transform in SVG sanitizer
* preserve multilingual SSR body on initial load
* Stabilize Mermaid diagram reveal
* prevent frontend rendering regressions

= 2.10.3 =
* Add admin manual submenus
* Count multiline translations without msgfmt
* Satisfy PHP lint for admin pages

= 2.10.2 =
* Add live style-preset preview to settings page
* Align light theme code background with GitHub #f6f8fa
* render default-language body in multilingual blocks for untranslated visitor language

= 2.10.1 =
* Size Mermaid lightbox from SVG natural viewBox
* Add idempotent demo-post seeder for local verification
* hide Save Changes button on the Extensions settings tab
* hide copy button label text via gfmr-copy-text class

= 2.10.0 =
* Prune stale non-standard asset subdirs in SVN deploy
* exclude CJK-subject commits from changelog and guard commit subjects
* add WordPress.org stats tracker
* verify wp.org publish after deploy
* add KaTeX latex rendering support
* add markdown style presets
* add advisory CI reports for knip and bundle size
* add post-merge quality threshold alert
* add local Plugin Check husky gate
* add language switcher disable hook
* Add init-stage timeout to Shiki worker manager
* differential re-render on OS theme change
* Scope MutationObserver code-block processing to inserted roots
* Add WordPress Abilities API foundation for AI agents
* reduce PR CI work
* cache SSR allowed-html allow-list per request
* short-circuit has_markdown_patterns backtick detection
* batch SSR cache reads in code-block pass
* Cache base SVG allowed-tags array per request
* Add filterable worker line threshold
* generate SVN tag as clean svn copy after trunk commit
* resolve knip quality threshold breach
* Repair task list checkbox attr spacing before kses (Issue #854)
* align frontmatter date expectations with js-yaml v5
* Keep chart container light background on dark themes
* Revert js-yaml to v4 and pin against v5 major bump
* Keep frontmatter dates as strings via JSON_SCHEMA

= 2.9.4 =
* Maintenance release: internal CI nightly schedule adjustment only. No changes to plugin functionality.

= 2.9.3 =
* add [gfmr_markdown] shortcode for block-independent Markdown
* promote security severity gate to blocking on critical (#837 F-B)
* add Lemon Squeezy auto-updater for the standalone Pro plugin
* skip Mermaid in SSR code-block highlighting (Issue #861)
* nest content-only delegation to avoid dead-branch error
* wire up toc_sticky and remove dead chart_zoom_enabled setting
* gate PlantUML AJAX proxy behind is_plantuml_enabled()
* make get_the_tags callback accept a single argument

= 2.9.2 =
* add WordPress Playground Live Preview blueprint
* improve readme discoverability and add settings review footer
* Add per-language featured images for built-in multilingual mode
* Add release smoke gate manifest and CI locale parity
* Add Settings action link to plugin row
* give deploy-svn.sh standalone defaults for slug/SVN vars
* remove test-environment artifacts from wp.org screenshots
* preserve GFM task list checkboxes through SSR/baked sanitization

= 2.9.1 =
* add multilingual taxonomy assignments
* keep WordPress.org readme tabs fresh and fix version cache-busting
* isolate readiness tests from config.sh env leak (README_FILE)

= 2.9.0 =
* add i18n .mo auto-recompile hooks and wporg/i18n audit agents
* add WP-cross-version smoke and timing history median
* add diff coverage and security severity gate quality gates
* add interactive chart controls
* add approximate grammar fallbacks for unbundled languages
* add markdown image drop uploads
* reveal frontend content on render pipeline failure
* stabilise diagram-layout tests against font-metrics flake
* use foreignObject bounds for diagram label alignment tests
* optimize PR lint and dependency caches
* exclude .security-allowlist.json from wp.org dist
* reveal Mermaid SSR cache-warmed diagrams
* wire roadmap status update into release
* repair version-check tooling and sync composer.json version
* unify nav waitForURL/waitForNavigation timeout to 60s
* retry WP login in global-setup to absorb startup flakiness
* clean up release lock via EXIT trap on early abort

= 2.8.1 =
* improve inline code contrast and stabilize tests
* align diagram rendering layouts
* repair mermaid state diagram styles
* preserve mermaid flowchart polygon transforms
* preserve mermaid flowchart path transforms
* keep wide mermaid diagrams readable
* fit wide mermaid diagrams to container
* center chart preview images
* update mermaid server privacy gate live

= 2.8.0 =
* live Mermaid bg color and concurrent chart rendering
* Add cross-session diagram cache with localStorage persistence
* Add SVN trunk cleanup script for stray readiness-results
* scan clean dist in plugin-check instead of dev tree
* Add shared concurrent-load guard for editor diagram libraries
* add non-interactive mode and reduce log noise
* Add bounded render cache helper and skip rendered Mermaid blocks
* Show friendly notice for PlantUML suppressed diagrams
* Add server-side Mermaid rendering via Kroki
* add configurable PlantUML server URL
* send a sync trigger to wakalab-site on release
* Add per-language SEO meta description feature
* Add interactive diagram toolbar with expand and collapse
* add clipboard image paste with media upload
* adaptive debounce + PlantUML completeness guard
* skip redundant builds and vendor reinstalls
* render baked Mermaid diagrams and code blocks in prerendered content
* resolve stale roadmap-update.yml reference in integrated-release STEP 3.4

= 2.7.17 =
* scope and time-box Plugin Check to prevent release hang
* isolate E2E compose project to stop release/CI smoke collision

= 2.7.16 =
* harden release smoke against transient nav timeouts

= 2.7.15 =
* add WordPress.org submission readiness check suite
* automate nightly plugin-check parallel diff (Phase 6-A)
* Reserve placeholder space to reduce CLS/FOUC
* load frontend styles non-render-blocking with critical CSS
* Exclude heavy diagram pages from prerender (WP7.0 spike)
* load Shiki grammars on demand per page languages
* add Site Health check for diagram bundle compression
* add Service Worker for long-term vendor caching
* extend diagram cache TTL to 30 days with version-keyed invalidation
* bake Chart.js into cached WebP/PNG images on render
* bake editor-rendered diagrams to skip frontend JS
* skip Mermaid renderer when diagrams are fully baked
* bake SVGs into eviction-proof post meta
* Offload Shiki highlighting to Web Worker
* Memoize editor Mermaid/Chart renders with source-keyed cache
* defer frontend scripts and schedule non-blocking init
* Lazy-load Shiki and Mermaid bundles on demand
* Chunk initial block rendering to reduce INP
* run setup-php release jobs on ubuntu-latest (fix native runner sudo loop)
* make wporg readiness tests resilient to missing jq/msgfmt
* check license.txt with correct lowercase name
* avoid set -e abort on (( count++ )) in cleanup_old_reports
* replace bash 4 mapfile in cache-cleanup PR job
* allow anonymous Mermaid SVG cache warming
* add bounded schema-aware cache keys
* make plugin check gate executable
* restrict baked data: URIs to base64 raster images
* harden baked data: URI handling against entity-encoded bypass
* Route worker init failure to main-thread highlighter
* Prevent readiness script abort from grep|head SIGPIPE under pipefail
* Treat undeterminable readiness values as warn, not false fail

== Upgrade Notice ==

= 2.9.1 =
Maintenance release: multilingual taxonomy assignments, fresher WordPress.org readme metadata, and a readiness-test fix. Safe, recommended update.

= 2.9.0 =
Adds on-demand language fallbacks, interactive chart controls, and WordPress.org / i18n release-quality automation. Upgrading regenerates the plugin's cached front-end assets.

= 2.8.0 =
Adds optional server-side Mermaid rendering, a configurable PlantUML server, per-language SEO meta descriptions, and an interactive diagram toolbar.

= 2.7.15 =
Major front-end performance pass: on-demand Shiki grammars, Web Worker highlighting, diagram baking/caching, and reduced layout shift.

= 1.0.0 =
First official release with GitHub Flavored Markdown rendering.

== Technical Requirements ==

* WordPress 6.8 or higher
* PHP 8.2 or higher
* Modern browser with JavaScript enabled
* Recommended: 128MB+ PHP memory limit
* Recommended: gzip or Brotli compression enabled for static JavaScript on your web server

**Why server compression matters:**
The syntax-highlighting and diagram libraries are large when uncompressed (Shiki ~2.35 MB, Mermaid ~3.2 MB) but shrink dramatically when delivered with gzip or Brotli (Shiki ~302 KB, Mermaid ~908 KB). For the best front-end performance, ensure your web server compresses static JavaScript (for example mod_deflate/mod_brotli on Apache, or the gzip/brotli directives on nginx). Most managed hosts and CDNs enable this by default. The plugin adds a **Tools &rarr; Site Health** check that reports whether these bundles are actually being served compressed.

== Support ==

For support, please visit the WordPress.org support forum for this plugin. Our team actively monitors and responds to support requests.

**Before posting a support request:**
* Check the FAQ section above for common questions
* Ensure you're using the latest version of the plugin
* Include your WordPress and PHP versions in your support request

**Feature Requests:**
We welcome feature suggestions! Please post them in the support forum with detailed descriptions of your use case.

== Source Code ==

This plugin uses build tools for development efficiency.

**Compressed File Source Code:**
* **build/index.js**: WordPress Block Editor integration code
  * Source: blocks/markdown/src/ folder
  * Build: npm run build
* **assets/libs/shiki/shiki.min.js**: Shiki syntax highlighter (self-contained bundle, no CDN)
  * Source: scripts/vendor/shiki-entry.mjs
  * Build: npm run vendor:shiki

**Source Code Access:**
* **GitHub Repository**: https://github.com/my-biz-dev/markdown-renderer-for-github
* **License**: GPL v2 or later
* **Development Branch**: main

**Build Instructions:**
1. Install Node.js 22 LTS (see .nvmrc)
2. Install dependencies with `npm install`
3. Build with `npm run build`
4. Run tests with `npm run test`

**Developer Resources:**
* **Development Environment Setup**: See CLAUDE.md and docs/DEVELOPMENT.md
* **Contributing**: See CONTRIBUTING.md
* **Build Process Details**: See BUILD.md

== Third Party Services ==

By default this plugin runs entirely on your own server. The core rendering libraries are bundled locally and make no external requests:

* Shiki syntax highlighter - served from your WordPress installation (no CDN)
* Mermaid diagram renderer - served from your WordPress installation (no CDN)
* Chart.js chart renderer - served from your WordPress installation (no CDN)
* markdown-it parser - bundled locally

**Optional features that contact an external server (opt-in, off by default):**

Two features can send diagram source to an external rendering server. Both are inactive until you explicitly enable, configure a server URL, and accept the in-plugin privacy notice:

* **PlantUML diagrams** - PlantUML has no in-browser renderer, so the source of each ```plantuml block is sent to a PlantUML/Kroki server to produce the image.
  * Default server (configurable, or self-hostable): https://www.plantuml.com/plantuml
  * Service: PlantUML - https://plantuml.com/
* **Server-side Mermaid rendering (Kroki)** - an optional mode that pre-renders Mermaid diagrams on a Kroki server for faster first paint. When enabled, the Mermaid source is sent to the configured server.
  * Default server (configurable, or self-hostable): https://kroki.io
  * Service: Kroki - https://kroki.io/

To keep diagram source private you can point either feature at a server you self-host. When both options are left in their default (disabled) state, no diagram data or any other content leaves your site.

**Pro license validation (only if you activate a Pro license key):**

This Free plugin ships the shared license-gating code used by the separate Pro plugin. If you install the Pro plugin and enter a license key, activating, deactivating, or periodically re-validating that key sends the license key (no diagram or post content) to the license server:

* Service: Lemon Squeezy - https://www.lemonsqueezy.com/
* Endpoint: https://api.lemonsqueezy.com/v1/licenses/

Without the Pro plugin and an activated license key, no request is made to this endpoint.

**Privacy & Security Benefits (default configuration):**
* No tracking, analytics, or data collection
* No data is transmitted to external servers unless you opt in to PlantUML or server-side Mermaid rendering, or activate a Pro license key
* Works offline and in closed networks with the default settings

== Privacy ==

This plugin does not collect any personal data, and with the default settings all processing happens locally on your server. If you opt in to PlantUML or server-side (Kroki) Mermaid rendering, the source text of those diagrams is sent to the rendering server you configure - choose a server you trust, or self-host one, for sensitive content. If you activate a Pro license key, the key is sent to the Lemon Squeezy license server to validate it.

== Credits ==

* Syntax highlighting: [Shiki](https://shiki.style/)
* Diagram rendering: [Mermaid](https://mermaid.js.org/)
* Chart rendering: [Chart.js](https://www.chartjs.org/)
* Markdown parsing: [markdown-it](https://markdown-it.github.io/)

== Developer Information ==

This section provides essential information for developers who want to extend or customize the plugin.

**For complete API documentation, architecture diagrams, and customization examples, see:**
[Developer Documentation on GitHub](https://github.com/my-biz-dev/markdown-renderer-for-github/tree/main/docs)

= Available Hooks and Filters =

**Actions:**

* `gfmr_metadata_saved` - Fired when code block metadata is saved
  * Parameters: `$post_id` (int), `$metadata` (array)
  * Use case: Sync metadata with external services, logging

**Filters:**

* `gfmr_metadata_get_metadata` - Filter retrieved metadata before use
  * Parameters: `$metadata` (array), `$post_id` (int)
  * Use case: Custom language detection, metadata modification

* `gfmr_schema_data` - Filter Schema.org JSON-LD data before output
  * Parameters: `$schema` (array), `$post` (WP_Post)
  * Use case: Add custom schema properties, author profiles

= PHP Constants =

* `GFMR_PLUGIN_FILE` - Plugin main file path
* `GFMR_SLUG` - Plugin slug ('markdown-renderer-for-github')
* `GFMR_URI` - Plugin URL
* `GFMR_PATH` - Plugin directory path
* `GFMR_PLUGIN_PATH` - Plugin directory name (relative)
* `GFMR_PLUGIN_BASENAME` - Plugin basename
* `GFMR_ASSETS_PATH` - Assets directory URL

= JavaScript Global Objects =

* `wpGfmConfig` - Plugin configuration object
* `wpGfmRenderer` - Core rendering API (processCodeBlocks, renderContent, initialize)
* `wpGfmHighlighter` - Highlighter wrapper instance
* `wpGfmShikiHighlighter` - Actual Shiki highlighter instance
* `wpGfmUnifiedHighlight(code, lang, options)` - Unified highlight function
* `wpGfmSwitchTheme(newTheme)` - Theme switching function ('light', 'dark', 'system')
* `wpGfmRenderDiagram(content, element, options)` - Diagram rendering function

= Settings Option =

Option name: `gfmr_theme_settings`

Available keys:

* `theme` - Theme setting ('light', 'dark', 'system')
* `schema_enabled` - Enable Schema.org JSON-LD output (bool)
* `schema_auto_detect_type` - Auto-detect article type (bool)
* `schema_include_author` - Include author in schema (bool)
* `schema_include_publisher` - Include publisher in schema (bool)
* `uninstall_remove_data` - Remove plugin data on uninstall (bool, default false)

= Plugin Development =

This plugin follows WordPress coding standards and provides clean, semantic HTML output.

**Detailed Documentation:**

For complete documentation including full API reference with code examples, architecture diagrams (Mermaid), step-by-step customization guides, and CSS class reference, visit:

[GitHub Developer Documentation](https://github.com/my-biz-dev/markdown-renderer-for-github/tree/main/docs)
