Why should I use GitHub Actions instead of mkdocs gh-deploy?

GitHub Actions is the modern recommended method; it offers better security via OIDC, clearer environment tracking, and removes the need for local write access to the gh-pages branch.

Can I use this for documents that contain LaTeX commands?

Yes, the skill includes logic to remove PDF-specific commands like \pagebreak that cause visual artifacts when rendering to HTML.

Does this skill help with grid tables?

Yes, it provides the specific extension configuration and installation steps needed to render Pandoc-style grid tables in MkDocs.

How does this skill handle broken list rendering?

It identifies and fixes 4-space indentation and unsupported list markers (like roman numerals) that Python-Markdown incorrectly interprets as code blocks.

MkDocs GitHub Pages Deployment & Fixer

Name: MkDocs GitHub Pages Deployment & Fixer
Author: SecurityRonin

bySecurityRonin

Deployment & DevOps

Automates MkDocs deployments to GitHub Pages using modern GitHub Actions while fixing common Python-Markdown rendering issues.

About

This skill provides a comprehensive framework for deploying MkDocs documentation to GitHub Pages using secure, modern GitHub Actions workflows. Beyond simple deployment, it addresses 'hard-won' knowledge regarding Python-Markdown rendering pitfalls, such as indentation errors that turn lists into code blocks, truncated footnotes, and broken grid tables. It is particularly useful for teams maintaining complex policy or technical documentation who need to ensure their web output is clean, professional, and free of LaTeX artifacts or formatting bugs.

Key Features

Automated fixes for Python-Markdown list indentation and marker issues
Grid table support configuration for Pandoc-style documentation
Footnote formatting logic to ensure multi-line content renders correctly
LaTeX command removal to eliminate visual artifacts in HTML output
Modern GitHub Actions workflow templates using OIDC and environment tracking
0 GitHub stars

Use Cases

Migrating legacy MkDocs deployment scripts to secure GitHub Actions 'Pages' source
Ensuring complex policy documents with footnotes and grid tables render perfectly
Standardizing documentation formatting across large repositories with nested lists

About

Key Features

Automated fixes for Python-Markdown list indentation and marker issues
Grid table support configuration for Pandoc-style documentation
Footnote formatting logic to ensure multi-line content renders correctly
LaTeX command removal to eliminate visual artifacts in HTML output
Modern GitHub Actions workflow templates using OIDC and environment tracking
0 GitHub stars

Use Cases

Migrating legacy MkDocs deployment scripts to secure GitHub Actions 'Pages' source
Ensuring complex policy documents with footnotes and grid tables render perfectly
Standardizing documentation formatting across large repositories with nested lists