The Markdown to HTML shortcode

[pom_markdown_to_html] renders one trusted Markdown file as safe HTML on a page. It is useful for a page whose source remains on the filesystem; synchronized product documentation normally uses it automatically.

Usage

[pom_markdown_to_html path="/wp-content/settings/pom-framework/sites/6/docs/pom/06-pom-forms/06-google-drive-integration-pom.md"]

path is required. The optional lang attribute selects a stored documentation translation, using an active language code such as es or es_ES. Omit it, or use auto, to follow the current language.

[pom_markdown_to_html path="/wp-content/settings/pom-framework/sites/6/docs/pom/06-pom-forms/06-google-drive-integration-pom.md" lang="es"]

Translations are available for documents managed by Sync docs on the documentation site. English always reads the original file. If a requested translation is missing, the English document appears with a notice. An existing translation remains readable while a changed source awaits synchronization. Rendering a page never starts a translation request.

Polylang posts use an explicit language. With POM Translate, the canonical post normally omits lang so its body follows the selected language. The changelog shortcode does not use stored documentation translations.

How paths are resolved

Content-directory paths are handled separately so that installations where the content directory is a symbolic link or a mounted filesystem outside the installation still work.

After symbolic links are resolved, the file must remain inside the selected root and must be readable. An invalid, unreadable or out-of-root path renders nothing — no error, no placeholder.

That silence is deliberate, and it is the thing to remember when a page comes out blank: check the path first.

What is rendered

The Markdown, converted to HTML in safe mode, so raw HTML written inside the Markdown is not emitted directly.

Markdown files are treated as informational content throughout. Shortcode-like text stays visible and is never executed, whether it appears in ordinary prose or inside a fenced code block — so a documentation page can show [pom_docs_nav] as an example without running it.

Relative assets and documentation links are adjusted for publication:

• a relative image source is resolved from the Markdown file's directory;
• a relative link to another .md file is converted to the corresponding public documentation path;
• its query string or fragment is preserved;
• absolute, protocol-relative, root-relative, fragment-only and query-only destinations are left unchanged.

This allows repository links such as next-guide.md#verify and nearby screenshots to continue working after synchronization.

For synchronized documents, relative Markdown links resolve to the target document in the selected language. Heading anchors retain their English identifiers so existing fragments keep working. Filenames, image destinations and source Markdown links remain unchanged inside the translation.

Code blocks

When the Markdown contains a fenced or indented code block, the theme's code-block assets are loaded — and only on pages that need them, so a page without code costs nothing extra.

The language after the opening fence selects the highlighter:

```php
echo 'Example';
```

Use text for an example that should not be highlighted. The languages supported by the theme's code-block bundle include html, css, javascript, php, py, cs and java.

Display a changelog with accordions

Use the changelog variant on a page that displays release notes:

[pom_markdown_changelog_to_html path="/wp-content/plugins/pom-cache/CHANGELOG.md"]

Replace only the shortcode name on your changelog pages; retain the same path. Regular documentation should continue to use [pom_markdown_to_html]. WPBakery also offers Markdown changelog to HTML in the POM Standard category.

The introduction, first H2 and all its content remain visible inline. Every later H2 becomes a collapsed POM Theme panel containing all content through the next H2, including subheadings, lists, images and code. If the first H2 is Changes pending release tag, that pending section is the one that stays inline. The theme's accordion appearance, icons, keyboard controls, CSS and scripts are reused automatically.

Write each release as a top-level ## heading with a non-empty title and content, separated by blank lines. Use ### for categories inside the release:

# Changelog

## Changes pending release tag

- No changes yet.

## 1.2.3 2026-09-16

### Fixed

- Corrected a display issue.

Do not nest release headings in lists or quotes, use another H1 within the releases, or leave code fences unclosed. Version text and dates do not determine grouping; the H2 hierarchy does.

If fewer than two usable sections are found, a heading or section is empty, H2 headings are nested, heading hashes lack a following space, a top-level code fence is unclosed, or the HTML structure cannot be parsed safely, the entire file stays inline. The same fallback applies when the compatible POM Theme renderer or WordPress HTML processor is unavailable. Paths, safe Markdown rendering, literal shortcode examples and code highlighting follow the rules above.

After saving, verify that the first section is visible, later panels start closed, and clicking or using Enter/Space opens each panel. A malformed section should leave the entire changelog readable inline.

When to use it

• Publishing a Markdown document that is maintained elsewhere, without copying it into the editor.
• Showing a file that changes independently of the page.

For product documentation, prefer Sync docs, which creates proper documentation posts with categories, ordering and navigation. This shortcode renders one file on one page and nothing more.

Verify

1. Add the shortcode with the path and update the page.
2. View the page as a signed-out reader.
3. Confirm headings, lists, links and any images render correctly.
4. Confirm Markdown examples that resemble shortcodes remain visible instead of executing.
5. If there is code, confirm the highlighting matches the declared language.

Troubleshooting

• The page is blank: verify the exact path, its leading slash, file readability and that its resolved location stays within the allowed root.
• An image is broken: confirm the image exists beside the article at the relative path written in Markdown, including letter case.
• A documentation link is wrong: link to the target .md source with a relative path so it can be rewritten consistently.
• Raw HTML is shown as text: safe mode does not publish arbitrary HTML from Markdown. Use supported Markdown instead.
• A shortcode example executed elsewhere: ensure that content is being rendered through this shortcode rather than copied into a normal WordPress shortcode-capable block.

Limitations

The shortcode displays one file. It does not create documentation posts, categories, manifest order or product navigation. Use Sync docs from Markdown for the complete product documentation workflow.