Add pre-commit pandoc hook with configurable formatting options

jupblb · ampcode-com · jupblb · commit a06400b91c94 · 2025-08-17T11:08:33.000+02:00
- Wraps pandoc for formatting Markdown files - Configurable column width (default: 80) - Optional reference-style links (default: enabled) - Configurable input/output formats (default: gfm) - MIT licensed for open source use Co-authored-by: Amp <amp@ampcode.com> Amp-Thread-ID: https://ampcode.com/threads/T-a4b3b491-de29-4cf7-a459-f324a9c0c53b
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -0,0 +1,8 @@
+# Example configuration for testing
+repos:
+  - repo: .
+    rev: HEAD
+    hooks:
+      - id: pandoc
+        # Optional: customize formatting options
+        # args: [--columns=100, --no-reference-links, --from=markdown, --to=markdown]
diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml
@@ -0,0 +1,7 @@
+- id: pandoc
+  name: Format markdown files with pandoc
+  description: Format markdown files using pandoc with standardized settings
+  entry: pandoc-format
+  language: script
+  types: [markdown]
+  minimum_pre_commit_version: 2.17.0
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michal Kielbowicz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -0,0 +1,106 @@
+# pre-commit-pandoc
+
+A [pre-commit] hook for formatting Markdown files using [pandoc].
+
+## Features
+
+This hook formats Markdown files with pandoc using the following settings:
+
+- 80 column width for better readability
+- Reference-style links for cleaner markdown
+- GitHub Flavored Markdown (GFM) input and output
+- Standalone document mode
+
+## Prerequisites
+
+- [pre-commit] installed
+- [pandoc][1] installed
+
+## Installation
+
+Add this to your `.pre-commit-config.yaml`:
+
+``` yaml
+repos:
+  - repo: https://github.com/jupblb/pre-commit-pandoc
+    rev: v1.0.0  # Use the latest version
+    hooks:
+      - id: pandoc
+```
+
+Then run:
+
+``` bash
+pre-commit install
+```
+
+## Usage
+
+The hook will automatically format your Markdown files when you commit. You can
+also run it manually:
+
+``` bash
+# Run on all files
+pre-commit run pandoc --all-files
+
+# Run on specific files
+pre-commit run pandoc --files README.md CONTRIBUTING.md
+```
+
+## Configuration
+
+The pandoc hook uses the following default settings:
+
+- `--columns=80` - Wrap text at 80 columns
+- `--reference-links` - Use reference-style links
+- `-s` - Standalone document (always enabled)
+- `-f gfm` - From GitHub Flavored Markdown
+- `-t gfm` - To GitHub Flavored Markdown
+
+You can customize these settings using args in your `.pre-commit-config.yaml`:
+
+``` yaml
+repos:
+  - repo: https://github.com/jupblb/pre-commit-pandoc
+    rev: v1.0.0
+    hooks:
+      - id: pandoc
+        args:
+          - --columns=100  # Set column width to 100
+          - --no-reference-links  # Disable reference-style links
+          - --from=markdown  # Change input format
+          - --to=markdown  # Change output format
+```
+
+### Available Arguments
+
+- `--columns <number>` - Set the column width (default: 80)
+- `--no-reference-links` - Disable reference-style links (default: enabled)
+- `--from <format>` - Set input format (default: gfm)
+- `--to <format>` - Set output format (default: gfm)
+
+Common format values include: `gfm` (GitHub Flavored Markdown), `markdown`,
+`markdown_strict`, `commonmark`. See [pandoc documentation][2] for all
+supported formats.
+
+## How it Works
+
+The hook runs pandoc on each Markdown file with the specified flags. If the file
+content changes after formatting, the hook will:
+
+1.  Update the file with the formatted content
+2.  Exit with a non-zero status to prevent the commit
+3.  Allow you to review and stage the changes
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License - see LICENSE file for details.
+
+  [pre-commit]: https://pre-commit.com
+  [pandoc]: https://pandoc.org/
+  [1]: https://pandoc.org/installing.html
+  [2]: https://pandoc.org/MANUAL.html#general-options
diff --git a/pandoc-format b/pandoc-format
@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+#
+# Wrapper script for pandoc to format markdown files
+# Used as a pre-commit hook
+
+set -euo pipefail
+
+# Check if pandoc is installed
+if ! command -v pandoc &> /dev/null; then
+    echo "Error: pandoc is not installed. Please install pandoc before using this hook."
+    echo "Visit https://pandoc.org/installing.html for installation instructions."
+    exit 1
+fi
+
+# Default values
+COLUMNS=80
+USE_REFERENCE_LINKS=true
+FROM_FORMAT="gfm"
+TO_FORMAT="gfm"
+
+# Parse arguments
+FILES=()
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --columns)
+            if [[ $# -lt 2 ]]; then
+                echo "Error: --columns requires an argument"
+                exit 1
+            fi
+            COLUMNS="$2"
+            shift 2
+            ;;
+        --no-reference-links)
+            USE_REFERENCE_LINKS=false
+            shift
+            ;;
+        --from)
+            if [[ $# -lt 2 ]]; then
+                echo "Error: --from requires an argument"
+                exit 1
+            fi
+            FROM_FORMAT="$2"
+            shift 2
+            ;;
+        --to)
+            if [[ $# -lt 2 ]]; then
+                echo "Error: --to requires an argument"
+                exit 1
+            fi
+            TO_FORMAT="$2"
+            shift 2
+            ;;
+        *)
+            FILES+=("$1")
+            shift
+            ;;
+    esac
+done
+
+# Check if any files were provided
+if [ ${#FILES[@]} -eq 0 ]; then
+    echo "Error: No files provided"
+    exit 1
+fi
+
+# Build pandoc arguments
+PANDOC_ARGS=(
+    "--columns=$COLUMNS"
+    "-s"
+    "-f" "$FROM_FORMAT"
+    "-t" "$TO_FORMAT"
+)
+
+if [ "$USE_REFERENCE_LINKS" = true ]; then
+    PANDOC_ARGS+=("--reference-links")
+fi
+
+# Process each file
+exit_code=0
+
+for file in "${FILES[@]}"; do
+    # Create a temporary file for output
+    tmpfile=$(mktemp)
+    
+    # Run pandoc with the specified flags
+    if pandoc "${PANDOC_ARGS[@]}" --output "$tmpfile" "$file" 2>/dev/null; then
+        
+        # Check if the file changed
+        if ! cmp -s "$file" "$tmpfile"; then
+            # Replace the original file with the formatted version
+            mv "$tmpfile" "$file"
+            echo "Formatted: $file"
+            exit_code=1
+        else
+            rm "$tmpfile"
+        fi
+    else
+        echo "Error: Failed to format $file"
+        rm -f "$tmpfile"
+        exit_code=1
+    fi
+done
+
+exit $exit_code
