Skip to content

How to Publish Raw HTML Files in a MkDocs Site

Why serve HTML directly?

  • Reuse landing pages exported from WordPress or other static tools without reworking layouts.
  • Keep complex embeds or widgets that would be cumbersome to convert to Markdown.
  • Spin up short-lived campaign pages quickly while staying inside the same repository.

MkDocs (including the Material theme) copies any HTML found under docs/ straight into the build. Follow the steps below to fold raw HTML assets into your workflow.

Basic workflow

  1. Place the HTML file under docs/ (for example docs/blog/readable-code.html).
  2. Reference it from a Markdown page via link or iframe.
  3. Run mkdocs build --strict to validate and mkdocs gh-deploy to publish.

Note: Standalone HTML bypasses MkDocs templating, so headers/footers will not be injected automatically. Wrap it with Markdown/iframe or convert it to a Jinja template if you need the full theme chrome.

Treating HTML as a blog post

1. Organise files

/docs/blog/
  ├─ readable-code.html    # Raw HTML article
  ├─ readable-code.md      # Embedding stub (Japanese)
  └─ readable-code.en.md   # Embedding stub (English)
- Set the iframe src relative to the Markdown file. - When your project enforces JP/EN pairs, create both Markdown stubs so the article pair validation passes.

2. Embed with an iframe

<div class="embedded-html-article">
  <iframe src="../readable-code.html"
          title="Readable Code: A Must-Read Playbook for Programmers"
          loading="lazy"
          style="width: 100%; min-height: 2600px; border: none;">
  </iframe>
</div>
- Adjust style to control height and remove borders so the page blends with Material. - Fix the dimensions if you want to avoid inner scroll bars.

3. Register the page in navigation

Point the nav entry at the Markdown stub instead of the raw HTML so breadcrumbs, search, RSS, and i18n keep working.

  - 📰 ブログ:
      - 記事一覧: blog/index.md
      - 最新記事:
          - リーダブルコード：プログラマー必読の実践術: blog/readable-code.md

Linking to HTML directly

  • From any Markdown page you can link with [Open the HTML version](../readable-code.html).
  • If you must add the HTML to navigation, create a thin Markdown wrapper that performs a meta refresh redirect.
<meta http-equiv="refresh" content="0; url=../readable-code.html">

That said, Material generates search indexes and feeds from Markdown, so using HTML-only entries in nav is usually a bad idea.

Things to watch

  • Validation: External scripts or inline CSS inside HTML may trigger warnings during mkdocs build --strict or link checking. Consider extracting shared styles to extra_css.
  • Localization: HTML assets are language-agnostic; provide language-specific Markdown wrappers and copy to keep the navigation consistent across locales.
  • Relative paths: Update image/script URLs inside the HTML based on its folder depth.
  • Caching: GitHub Pages/Cloudflare may cache the HTML aggressively. Append cache-busting query strings or purge the cache when testing updates.

Recap

  • Drop HTML into docs/ and MkDocs will deploy it untouched.
  • Drive user traffic through Markdown stubs (iframe or link) so ancillary features continue to work.
  • Monitor build warnings and refactor shared assets for maintainability.

Documenting this workflow ensures future HTML imports stay predictable and reviewable.