Skip to content

Add a script to validate Markdown formatting in documentation #113128

@Abhijais4896

Description

@Abhijais4896

Problem

This repository contains several Markdown documentation files such as:

  • README.md
  • docs/*.md
  • examples documentation

Over time, formatting inconsistencies may appear in these files, for example:

  • incorrect heading hierarchy
  • trailing whitespace
  • images without alt text
  • empty or malformed links

Currently these issues are usually detected during manual reviews.

Proposed Solution

Introduce a small script that automatically validates Markdown formatting across the repository.

The script could check for common issues such as:

  • skipped heading levels (e.g., H2 → H4)
  • trailing whitespace
  • images without alt text
  • empty Markdown links

The script could scan all Markdown files in the repository and print warnings for formatting violations.

Possible Implementation

A simple implementation could be created using Python or an existing Markdown linting tool.

Example script location:

scripts/markdown_validator.py

The script could scan:

  • README.md
  • docs/
  • examples/

Benefits

  • improves documentation consistency
  • helps contributors detect formatting issues early
  • reduces manual review effort

If this improvement is considered useful, I would be happy to implement the script and submit a pull request.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions