markdown-exporter: Instructions file for Codex

Agent Coding Guidelines for md-exporter

This document provides essential information for agentic coding agents working in the md-exporter repository.

🔧 Build, Lint, and Test Commands

Package Management

• Primary: uv package manager is used for dependency management
• Fallback: pip if uv is not available
• Python Requirement: Python 3.11 or higher required

Code Quality and Formatting

Lint and Format Code

# Alternative: Run from project root using provided script
./dev.reformat.sh

Run Tests

# Run all tests
test/bin/run_all_tests.sh 

# Run specific test file
test/bin/test_md_to_docx.sh 

or

uv run pytest test/skills/test_md_to_docx.py

Development Scripts

• Test Scripts: Individual test scripts in test/bin/

📝 Code Style Guidelines

Formatting and Style

• Line Length: 120 characters maximum
• Line Ending: LF (Unix-style)
• Indentation: 4 spaces (not tabs)
• Quotes: Use double quotes for strings unless single quotes are preferred for specific cases
• End of File: All files must end with newline character

Python Style Standards

Import Organization

# Standard library imports
from pathlib import Path
from tempfile import NamedTemporaryFile

# Third-party imports
from pypandoc import convert_file

# Local imports (relative paths)
from scripts.utils.markdown_utils import get_md_text

Type Hints and Annotations

• Use Python 3.11+ union syntax: Path | None (not Optional[Path])
• All function parameters and return values should have type hints
• Use pathlib.Path for file paths, not strings

Function Documentation

def convert_md_to_docx(
    md_text: str, output_path: Path, template_path: Path | None = None, is_strip_wrapper: bool = False
) -> None:
    """
    Convert Markdown text to DOCX format

    Args:
        md_text: Markdown text to convert
        output_path: Path to save the output DOCX file
        template_path: Optional path to DOCX template file
        is_strip_wrapper: Whether to remove code block wrapper if present

    Raises:
        ValueError: If input processing fails
        Exception: If conversion fails
    """