Markdown for AI Plugin

Introduction

The Markdown for AI plugin creates a clean Markdown version of every eligible post and page on your Publii website. It gives AI tools a simpler way to read your content without navigation, theme markup, scripts, cookie notices, and the other elements that belong to the HTML version of a page.

The plugin runs while Publii generates the site. It reads the original content from the editor, converts it when necessary, and writes a companion .md file next to the corresponding HTML document. There is no client-side JavaScript and no additional processing after the site has been uploaded.

For example:

/post/ becomes /post.md
/post.html becomes /post.md
/page/about/ becomes /page/about.md
/page/about.html becomes /page/about.md

Markdown for AI works on its own, but it can also work alongside the LLMS.txt Generator plugin. Used together, one plugin provides a compact index of the website and the other provides readable Markdown versions of the individual documents.

Enabling the Plugin

Open Publii and go to Tools & Plugins. Find Markdown for AI and activate it using the toggle in the bottom-left corner of the plugin tile.

The default settings generate Markdown files for both posts and pages during normal site generation. Local Preview generation is disabled by default, so enable Generate files during preview if you want to inspect the files before publishing.

Important: Enabling Markdown generation adds one companion .md file for each eligible post and page. Because every document is then published in both HTML and Markdown form, the number of content files processed during synchronization can be close to twice as high as before. This is expected and does not create duplicate posts or pages in Publii.

How the Plugin Works

When Publii renders an individual post or page, the plugin creates a Markdown document from the content stored by its editor. The resulting file follows the same URL hierarchy as the HTML page, but uses the .md extension.

The plugin deliberately limits generation to individual posts and pages. It does not create Markdown copies of tag listings, author listings, archives, pagination, 404 pages, or other collection views. These pages are useful for browsing a website, but they usually repeat excerpts and links rather than provide a complete document.

Markdown Discovery in HTML

Whenever a Markdown file is generated, the plugin adds an alternate-document link to the corresponding HTML page:

<link rel="alternate" type="text/markdown" href="https://example.com/post.md"/>

This lets tools inspecting the HTML source discover the Markdown version without having to guess the URL. The link is only added when the file has actually been created. Content excluded through the plugin settings or marked noindex does not advertise a missing Markdown document.

The HTML page remains the primary version of the content. The alternate link simply points to another representation of the same document.

SEO and Google Search

Markdown for AI does not replace or modify the SEO settings of the original post or page. Publii's HTML document remains the primary version, with its existing canonical URL, title, meta description, robots settings, and structured data left unchanged. Generated .md files are not added to the website sitemap.

Each markdown document can include the original HTML URL, publication and update dates, description, author, and tags. This readable metadata gives AI tools useful context, but it does not replace HTML SEO metadata or create an additional ranking signal for Google.

Google may discover, crawl, and index text formats in addition to HTML, but it does not give markdown or other AI-oriented files special treatment. Google's current guidance states: Doing so will neither harm nor help your site's visibility or rankings in Google Search. See Google's guide to optimizing for generative AI features.

SEO note: According to Google's current guidance, publishing Markdown or similar AI-oriented files should neither improve nor harm a website's visibility in Google Search. Google may still discover and crawl these files, and its handling of equivalent content can vary or change over time. Markdown for AI does not add generated .md files to the sitemap and excludes content marked noindex by default. Website owners should monitor indexing in Google Search Console after deployment.

Document Structure

Every generated document starts with the post or page title as a visible H1 heading. The title is always included, even when optional metadata is disabled.

With the default settings, the output looks like this:

# Post title

- URL: https://example.com/post/
- Published: 2026-08-11T10:00:00.000Z
- Updated: 2026-08-11T12:00:00.000Z
- Description: A short description of the post
- Author: Jane Smith
- Tags: AI, Publii

The post content starts here.

The metadata is ordinary Markdown rather than YAML front matter. Fields are only included when the relevant value exists:

URL - the canonical HTML URL of the post or page
Published - the publication date in ISO 8601 format
Updated - the last modification date in ISO 8601 format
Description - the individual SEO description when available, otherwise the content description or excerpt
Author - the assigned author
Tags - the tags assigned to the document

The plugin cleans metadata values before writing them. HTML in descriptions is converted to Markdown, line breaks are removed, and repeated spaces are collapsed.

Supported Publii Editors

Publii stores content differently depending on the editor used for a post or page. Markdown for AI detects the editor and handles each source format separately.

Markdown Editor

Content written in the Markdown editor is preserved as Markdown. The plugin does not convert it through HTML first, so headings, lists, links, code fences, and other formatting remain as written. Publii media placeholders are resolved to the correct media URLs.

WYSIWYG Editor

WYSIWYG content is stored as HTML and converted with Turndown plus its GitHub Flavored Markdown extensions. The conversion preserves common elements such as headings, paragraphs, emphasis, links, images, blockquotes, lists, tables, strikethrough, task lists, horizontal rules, and fenced code blocks.

Embedded iframes are represented as links. Audio and video elements are also converted to links so the media remains discoverable without carrying player markup into the document. Executable or page-specific elements such as script, style, noscript, and Publii script containers are removed.

Block Editor

Block editor content is read directly from Publii's block data rather than flattened into rendered page HTML. This allows the plugin to preserve details that would otherwise be easy to lose, including:

heading levels and heading links
ordered and unordered lists
quote authors
code block languages
image links, alternative text, and captions
all images and captions from gallery blocks
embeds, custom HTML, and separators

The automatic table of contents and read-more blocks are skipped because they provide navigation rather than document content. If a block type is not recognized, the plugin still attempts to convert its text or HTML content.

If the stored block data is damaged and cannot be parsed, the plugin skips that document and records a clear error in the Publii log instead of creating an empty or misleading Markdown file.

Plugin Configuration

Generate Markdown for Posts

Enabled by default. Creates a Markdown file for every eligible published post. Disable this option if the website should expose Markdown versions of pages only.

If the option is disabled after files have already been generated, the plugin removes the old post Markdown files during the next generation. This prevents outdated copies from remaining in the output.

Generate Markdown for Pages

Enabled by default. Creates Markdown files for eligible published pages while preserving their URL hierarchy. A nested page such as /page/install/ is written as /page/install.md.

As with posts, disabling the option removes previously generated page Markdown files during the next generation.

Exclude Noindex Content

Enabled by default and recommended. Posts and pages whose SEO robots setting contains noindex do not receive a Markdown version.

This applies to values such as noindex, follow and noindex, nofollow. If a Markdown file was created before the SEO setting changed, the stale file is removed the next time Publii renders that document. The HTML page also stops advertising a Markdown alternate.

You can disable this option if you intentionally want Markdown files for content excluded from search indexing. Keep in mind that the resulting files will still be public after deployment if someone knows their URLs.

Include Content Metadata

Enabled by default. Adds the canonical HTML URL, publication and update dates, description, author, and tags below the document title.

Disable this option when you want the smallest possible output containing only the H1 title and the main content. The title itself is never removed.

Generate Files During Preview

Disabled by default. Turn it on when you want Publii to create Markdown files during local Preview.

Preview files use Publii's local file:/// addresses. The alternate link in the HTML source also uses a local URL, for example:

<link rel="alternate" type="text/markdown" href="file:///Users/your-name/Publii/sites/example/preview/post.md"/>

This is expected in Preview and makes it possible to open the Markdown document directly from the locally generated HTML. Public HTTPS addresses are used during normal site generation and deployment.

The Preview setting does not affect published output. When Preview generation is turned off, previously generated Markdown files are removed from the Preview directory during the next render.

Working with LLMS.txt Generator

Markdown for AI and LLMS.txt Generator solve two related but different problems:

LLMS.txt Generator creates llms.txt, a concise index that introduces the website and points to important posts and pages.
Markdown for AI creates complete Markdown versions of individual posts and pages.

When both plugins are active for the same website, Markdown for AI detects LLMS.txt Generator automatically. Each generated document receives a short content-index notice at the top:

> ## Content Index
> Fetch the complete content index at: https://example.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# Post title

This gives an AI tool reading a single document a direct route back to the website's main content index. No additional integration setting is required. If LLMS.txt Generator is disabled or not installed, the notice is simply omitted and the rest of the Markdown document is unchanged.

A practical setup is to use LLMS.txt Generator for discovery and curation, then Markdown for AI for the full text of each resource. Configure key resources, featured posts, topic sections, and recent content in llms.txt; the individual HTML pages advertised by that file will in turn expose their Markdown alternatives.

Using and Checking the Generated Files

Once configured, the plugin runs automatically whenever Publii generates the site. There is no separate export button.

To check the result before publishing:

Enable Generate files during preview.
Run Preview again so Publii rebuilds the files.
Open a post or page in the previewed site.
View the HTML source and look for rel="alternate" with type="text/markdown".
Open the URL from its href attribute, or locate the companion file in the site's Preview directory.

After deployment, a post available at https://example.com/post/ should have its Markdown version at https://example.com/post.md.

HTTP Content Type

Markdown files should be served with the text/markdown content type. For example, a request to:

https://example.com/post.md

should return:

Content-Type: text/markdown

If Markdown files are downloaded instead of displayed in the browser, Apache users can add the following rule to their .htaccess file:

<IfModule mod_mime.c>
    AddType text/markdown .md
    AddCharset UTF-8 .md
</IfModule>

Troubleshooting

No Markdown Files Appear in Preview

Open the plugin settings and enable Generate files during preview, then start Preview again. The option is disabled by default.

A Specific Post or Page Is Missing

Check the following:

Make sure generation is enabled for that content type.
Open the post or page SEO settings and check whether its robots value contains noindex.
If the content should remain noindex but still needs Markdown, disable Exclude noindex content with the understanding that the file will be public after deployment.
For block editor content, check the Publii log for an invalid JSON message.

The Alternate Link Is Missing from the HTML Source

The link is only inserted when the Markdown file is successfully generated. Confirm that the content is eligible, Preview generation is enabled when testing locally, and the page is not excluded by noindex.

The Content Index Notice Is Missing

The notice appears only when LLMS.txt Generator is active for the same website. Enable that plugin and regenerate the site. Markdown for AI continues to work normally without it.

An Old Markdown File Is Still Visible

Regenerate the affected post or page. Markdown for AI removes stale files when content becomes noindex, when generation for its content type is disabled, or when Preview generation is turned off.

If the old file is on the public server rather than in Publii's local output, run a complete synchronization so deleted local files are also removed from the destination according to your deployment method.

The Markdown File Opens as a Download

The file was generated correctly, but the hosting platform is sending an unsuitable content type. Configure text/markdown; charset=utf-8 for .md responses on the server.