Yamllint

One excellent option is yamllint. It’s a command-line YAML linter written in Python that checks YAML files for syntax errors and stylistic issues. Since you use Linux and prefer Python, yamllint should work well for you.

Scripts

These can be placed in the mkdocs root directory

check-yaml-metadata.sh

exit
#!/bin/bash
# This script searches for all Markdown (.md) files in the areas/ops directory,
# extracts the YAML front matter, runs yamllint on it using strict formatting rules,
# and outputs filenames where the metadata has formatting issues.

# Set the directory to check (hardcoded to areas/ops)
SEARCH_DIR="docs"

# Usage: ./check-yaml-metadata.sh [directory]
# If no directory is provided, it defaults to the current directory.

# Set the directory to check (defaults to current directory if not provided)
SEARCH_DIR="${1:-.}"


# Create a temporary file for storing YAML front matter
TEMP_YAML=$(mktemp)

echo "Scanning Markdown files in '${SEARCH_DIR}' for YAML metadata issues..."
echo "--------------------------------------------------"

# Find all .md files under the specified directory
find "$SEARCH_DIR" -type f -name "*.md" | while read -r file; do
    # Extract YAML front matter (assumes YAML is delimited by lines containing only '---')
    sed -n '/^---$/,/^---$/p' "$file" > "$TEMP_YAML"

    if [ -s "$TEMP_YAML" ]; then
        # Run yamllint on the extracted YAML front matter
        yamllint_output=$(yamllint "$TEMP_YAML" 2>&1)
        exit_code=$?

        if [ $exit_code -ne 0 ]; then
            echo "YAML formatting issues found in: $file"
            echo "$yamllint_output"
            echo "--------------------------------------------------"
        fi
    else
        echo "No YAML front matter found in: $file"
    fi
done

# Remove the temporary file
rm "$TEMP_YAML"

delete_index_md

#!/bin/bash

# Check if a directory argument is provided, otherwise use current directory
TARGET_DIR="${1:-.}"

# Find and delete all index.md files recursively
find "$TARGET_DIR" -type f -name "index.md" -exec rm -v {} \;

echo "All index.md files have been deleted from $TARGET_DIR and its subdirectories."

prepsite.sh

#!/bin/bash
#
# This script pres the site for testing
rm -R site
./delete_index_md.sh docs
python3 generate_indexes.py
find docs -type f \( -iname "*.md" -o -iname "*.markdown" \) -print0 | xargs -0 yamllint > yaml_errors.txt

remove-trailing-spaces.sh

#!/bin/bash
# This script automatically repairs trailing spaces in all Markdown (.md) files within a specified directory.
# It uses sed to remove trailing whitespace at the end of each line.
#
# Usage: ./fix-trailing-spaces.sh [directory]
# If no directory is provided, it defaults to the current directory.

# Set the directory to check (defaults to current directory if not provided)
TARGET_DIR="${1:-.}"

echo "Removing trailing spaces in all Markdown files within '${TARGET_DIR}'..."
echo "--------------------------------------------------"

# Find all .md files in the target directory and remove trailing whitespace using sed.
find "$TARGET_DIR" -type f -name "*.md" -exec sed -i 's/[ \t]*$//' {} \;

echo "Trailing spaces have been removed from Markdown files in '${TARGET_DIR}'."

yaml-cleanup.py

#!/usr/bin/env python3
import os
import re
import sys
import yaml
# Custom representer to use folded style (>) for strings longer than 80 characters
def folded_str_representer(dumper, data):
    if isinstance(data, str) and len(data) > 80:
        return dumper.represent_scalar('tag:yaml.org,2002:str', data, style='>')
    return dumper.represent_scalar('tag:yaml.org,2002:str', data)

yaml.add_representer(str, folded_str_representer)

def process_file(filepath):
    """
    Extracts YAML front matter from the given Markdown file,
    re-formats it using PyYAML (with folded style for long strings),
    and rewrites the file with the updated YAML.
    """
    with open(filepath, 'r', encoding='utf-8') as f:
        content = f.read()

    # Match YAML front matter delimited by lines containing only '---'
    match = re.search(r'^---\n(.*?)\n---\n', content, re.DOTALL)
    if not match:
        print(f"[SKIP] No YAML front matter in: {filepath}")
        return

    original_yaml = match.group(1)
    try:
        data = yaml.safe_load(original_yaml)
    except Exception as e:
        print(f"[ERROR] Failed to parse YAML in {filepath}: {e}")
        return

    # Dump the YAML with our custom folded string representation
#    new_yaml = yaml.dump(data, default_flow_style=False, sort_keys=False)
    new_yaml = yaml.dump(data, default_flow_style=False, sort_keys=False, allow_unicode=True)

    # Reconstruct file content with new YAML front matter
    new_content = re.sub(r'^---\n(.*?)\n---\n', f"---\n{new_yaml}---\n", content, flags=re.DOTALL)
    with open(filepath, 'w', encoding='utf-8') as f:
        f.write(new_content)
    print(f"[UPDATED] YAML reformatted in: {filepath}")

def process_directory(directory):
    """
    Walks through the specified directory and processes all Markdown (.md) files.
    """
    for root, _, files in os.walk(directory):
        for file in files:
            if file.endswith('.md'):
                process_file(os.path.join(root, file))

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: ./automated-yaml-reformatter.py <directory>")
        sys.exit(1)
    target_directory = sys.argv[1]
    process_directory(target_directory)

Key Points about yamllint

• Installation: You can install yamllint via pip:

pip install yamllint

Or use your Linux distribution’s package manager (for example, on Ubuntu):

sudo apt-get install yamllint

• Usage: Once installed, you can run yamllint on your markdown files that contain YAML front matter. For example:

yamllint myfile.md

If your YAML front matter is correctly delimited (with --- at the start and end), yamllint will parse that section and report any errors (like missing spaces after colons).

• Custom Configuration: yamllint supports custom configuration, so you can adjust rules to suit your style preferences or project requirements. This can be done via a .yamllint configuration file in your project directory.

• Problem Detection: It will catch issues such as missing spaces after colons, incorrect indentation, duplicate keys, and other syntax problems, helping you avoid rendering issues in MkDocs.

For further details, you might check out the yamllint documentation which covers configuration and usage extensively. This should help you ensure your markdown pages’ YAML front matter is correctly formatted.