Automating SEO for Markdown: A GitHub Actions Linter for Hugo Blogs

Linting Hugo Markdown for SEO

Search Engine Optimization (SEO) is a crucial factor in making content discoverable, but manually checking every blog post for title length, word count, and heading structure can be tedious. If you use Hugo or another Markdown-based static site generator, ensuring each post meets SEO best practices can become an error-prone process.

To solve this, I built Hugo SEO Linter—a Python-based linter paired with a GitHub Actions workflow that automates these checks. This tool helps content creators maintain consistent, SEO-friendly formatting without manual review, ensuring every post is optimized before it goes live.

🛑 The Problem: SEO Issues in Markdown-Based Blogs

Static site generators like Hugo are fantastic for speed and flexibility, but they don’t include built-in SEO validation. Some common issues I’ve seen include:

1️⃣ Title & Description Length

• Too short? It won’t attract clicks.
• Too long? Search engines truncate it.

2️⃣ Word Count

• Posts under 500 words often fail to rank well.
• Short posts struggle to provide enough context for search engines.

3️⃣ Heading Structure

• Overusing # (H1) tags in Markdown can confuse search engines.
• Google prefers structured content, and improper heading use impacts readability.

4️⃣ Manual Review Takes Time

• Checking SEO manually is tedious.
• Simple mistakes can slip through and hurt rankings.

Instead of fixing these issues after publishing, I wanted a proactive solution that checks for problems before a post is even merged into my blog.

🚀 The Solution: A GitHub Actions-Based Markdown Linter

The Hugo SEO Linter automatically reviews Markdown posts against best practices. It consists of:

✅ A Python Linter (seo_linter.py)

• Parses the front matter for title and description.
• Checks length requirements.
• Validates word count.
• Scans for improper # (H1) usage.

✅ A GitHub Actions Workflow (seo-linter.yml)

• Runs on every push and pull request.
• Blocks commits if posts don’t meet SEO standards.
• Provides instant feedback on formatting issues.

⚙️ How It Works

1️⃣ Install the Linter in Your Hugo Repository

Clone the repo and copy the linter into your Hugo project:

git clone https://github.com/sedward5/Hugo-SEO-Linter.git
cd Hugo-SEO-Linter

Manually copy:

• scripts/seo_linter.py → Your repo’s scripts/ directory
• .github/workflows/seo-linter.yml → Your repo’s .github/workflows/

2️⃣ Customize the SEO Rules

Modify seo_linter.py to set your own limits:

MIN_WORD_COUNT = 500  # Adjust as needed
TITLE_MIN = 50
TITLE_MAX = 75
DESC_MIN = 120
DESC_MAX = 158
ALLOW_H1 = False  # Set to True if you want to allow one H1 heading

3️⃣ Automate SEO Checks with GitHub Actions

Once installed, the linter runs automatically whenever you push a commit or open a pull request.

Manually trigger it with:

python scripts/seo_linter.py path/to/post.md

If errors are found, the GitHub Action blocks the commit and reports issues directly in your pull request.

🎯 Why This Matters

SEO-optimized posts rank higher, attract more organic traffic, and offer better readability. By integrating this linter into my workflow, I’ve eliminated the need for manual SEO audits, catching issues before posts go live.

If you’re running a Hugo blog or any Markdown-based site, this tool can help you streamline your publishing process and improve search rankings—all without lifting a finger.

👉 Check out the repo and start using it today:
Hugo SEO Linter