Add AGENTS.md and copilot-setup-steps workflow

[Copilot]

Adds AI coding agent documentation and GitHub Actions workflow for environment setup, following the pattern established in MyST-Parser.

Files Added

• AGENTS.md: Comprehensive guide covering project architecture (token stream-based parser with three-stage pipeline: core→block→inline), development workflows (tox-based testing/docs/benchmarking), code style (Ruff/Mypy strict), testing patterns (pytest + CommonMark spec compliance), and common operations (adding parsing rules, creating plugins, customizing renderers)

• .github/workflows/copilot-setup-steps.yml: Environment setup workflow that installs Python 3.11, uv, pre-commit/pre-commit-uv, and tox/tox-uv on workflow_dispatch, push, or PR events affecting the workflow file

Key Sections in AGENTS.md

• Repository structure reflecting actual layout (markdown_it/, tests/, docs/, benchmarking/)
• Architecture details: parser chains (core/block/inline), token stream vs AST approach, Ruler class for rule management
• Development commands: tox -e py311, tox -e docs-clean, tox -e py311-bench-core, tox -e profile, tox -e fuzz
• Common patterns with code examples for adding rules, creating plugins, and customizing rendering
• Debugging techniques: token stream inspection, rule enable/disable, CLI usage

Example debugging pattern documented:

# See the token stream
tokens = md.parse("# Heading\n\nParagraph")
for token in tokens:
    print(f"{token.type} | {token.tag} | {token.content}")

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/repos/actions/setup-python/releases
  • Triggering command: /usr/bin/curl curl -s REDACTED (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

Overview

Add an AGENTS.md file and .github/workflows/copilot-setup-steps.yml to the markdown-it-py repository, following the pattern established in the MyST-Parser repository.

Files to Create

1. AGENTS.md

Create an AGENTS.md file in the repository root with guidance for AI coding agents. Use the AGENTS.md from MyST-Parser as a template, but adapt it for markdown-it-py:

Project Overview section should describe:

• markdown-it-py is a Python port of markdown-it (JavaScript)
• It's a Markdown parser following the CommonMark spec
• Configurable syntax with support for plugins
• High performance

Repository Structure section should reflect the actual structure:

pyproject.toml          # Project configuration and dependencies (flit)
tox.ini                 # Tox test environment configuration

markdown_it/            # Main source code
├── __init__.py         # Package init
├── main.py             # MarkdownIt main class
├── token.py            # Token dataclass
├── ruler.py            # Ruler class for managing rules
├── tree.py             # SyntaxTreeNode for AST representation
├── renderer.py         # RendererHTML and RendererProtocol
├── parser_core.py      # ParserCore - top-level rules executor
├── parser_block.py     # ParserBlock - block-level tokenizer
├── parser_inline.py    # ParserInline - inline tokenizer
├── utils.py            # Utility types (OptionsType, PresetType, etc.)
├── common/             # Common utilities
├── helpers/            # Helper functions
├── presets/            # Configuration presets (commonmark, gfm-like, zero, etc.)
├── rules_core/         # Core parsing rules
├── rules_block/        # Block-level parsing rules
├── rules_inline/       # Inline parsing rules
├── cli/                # Command-line interface
└── py.typed            # PEP 561 marker

tests/                  # Test suite
├── test_api/           # API tests
├── test_cmark_spec/    # CommonMark spec compliance tests
├── test_port/          # Port-specific tests
├── test_tree/          # SyntaxTreeNode tests
├── fuzz/               # Fuzzing tests for OSS-Fuzz
├── test_cli.py         # CLI tests
├── test_linkify.py     # Linkify tests
└── test_tree.py        # Tree tests

docs/                   # Documentation source
├── conf.py             # Sphinx configuration
├── index.md            # Documentation index
├── architecture.md     # Design principles
├── using.md            # Usage guide
├── plugins.md          # Plugin documentation
├── contributing.md     # Contributing guide
├── performance.md      # Performance benchmarks
└── security.md         # Security considerations

benchmarking/           # Performance benchmarking
scripts/                # Utility scripts

Development Commands section based on tox.ini:

# Run all tests
tox

# Run tests with specific Python version
tox -e py311

# Run tests with plugins
tox -e py311-plugins

# Build docs (clean)
tox -e docs-clean

# Build docs (incremental)
tox -e docs-update

# Run benchmarks
tox -e py311-bench-core
tox -e py311-bench-packages

# Run profiler
tox -e profile

# Run fuzzer
tox -e fuzz path/to/testcase

Code Style Guidelines based on pyproject.toml:

• Formatter/Linter: Ruff (configured in pyproject.toml)
• Type Checking: Mypy with strict settings
• Pre-commit hooks for consistent code style

Architecture Overview based on docs/architecture.md:

• Parsing pipeline: Markdown → Tokens → HTML
• Three nested chains: core, block, inline
• Token stream representation (not AST by default)
• Ruler class for managing rules
• Renderer for output generation

Include sections for:

• Testing guidelines (pytest, pytest-regressions, CommonMark spec tests, fuzzing)
• Commit message format (same as MyST-Parser)
• PR requirements
• Key files
• Debugging tips
• Common patterns (adding rules, creating plugins)
• Reference documentation links

2. .github/workflows/copilot-setup-steps.yml

Create a Copilot setup workflow similar to MyST-Parser's:

name: Copilot Setup Steps

on:
  workflow_dispatch:
  push:
    paths:
      - .github/workflows/copilot-setup-steps.yml
  pull_request:
    paths:
      - .github/workflows/copilot-setup-steps.yml

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest

    permissions:
      contents: read

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: "3.11"
        cache: pip

    - name: Install uv
      run: pip install uv

    - name: Install pre-commit and pre-commit-uv
      run: pip install pre-commit pre-commit-uv

    - name: Install tox and tox-uv
      run: pip install tox tox-uv

References

• MyST-Parser AGENTS.md: https://github.com/executablebooks/MyST-Parser/blob/master/AGENTS.md
• MyST-Parser copilot-setup-steps.yml: https://github.com/executablebooks/MyST-Parser/blob/master/.github/workflows/copilot-setup-steps.yml
• markdown...

This pull request was created from Copilot chat.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.