Skip to content

Add backtick processing standardization for better compatibility with markdown processors #26

@sanyamsmulay

Description

@sanyamsmulay

Problem

When using markdown-code-runner with backtick code blocks that have the extra markdown-code-runner text along with extra options (e.g. filename), the output files contain these extra arguments which can cause issues with markdown processors like mkdocs and pandoc. These processors expect fenced code blocks to only have the language specifier.

For example:

print("Hello")

This causes compatibility issues as many markdown processors can only handle the simple form:

print("Hello")

Proposed Solution

Add a backtick standardization feature that:

  1. Preserves the extra options internally for markdown-code-runner's functionality (like filename for writing to files)
  2. Outputs clean fenced code blocks in the final markdown that only contain the language specifier
  3. Protects against data loss by requiring explicit opt-in when doing in-place file modifications

Implementation Details

  • Add a backtick_standardize flag to control this behavior (default: True for new files, requires --force-overwrite for in-place edits)
  • Extract and store options using _extract_backtick_options for internal use
  • Strip extra options when writing the final markdown output
  • Add documentation about this feature and its importance for compatibility

Benefits

  • Better compatibility with markdown processors and documentation generators
  • Cleaner output files
  • Safe defaults to prevent accidental data loss
  • Maintains all functionality while improving the output format

Example Usage

# New file - standardization enabled by default
markdown-code-runner input.md -o output.md

# In-place edit - requires explicit opt-in
markdown-code-runner input.md --backtick-standardize --force-overwrite

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions