If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/github/markup shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 4 active contributors
• Distributed ownership (top contributor 36% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Small team — 4 contributors active in recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live github/markup repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/github/markup.

What it runs against: a local clone of github/markup — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in github/markup | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of github/markup. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/github/markup.git
#   cd markup
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of github/markup and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "github/markup(\\.git)?\\b" \\
  && ok "origin remote is github/markup" \\
  || miss "origin remote is not github/markup (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "lib/github/markup.rb" \\
  && ok "lib/github/markup.rb" \\
  || miss "missing critical file: lib/github/markup.rb"
test -f "lib/github/markups.rb" \\
  && ok "lib/github/markups.rb" \\
  || miss "missing critical file: lib/github/markups.rb"
test -f "lib/github/markup/implementation.rb" \\
  && ok "lib/github/markup/implementation.rb" \\
  || miss "missing critical file: lib/github/markup/implementation.rb"
test -f "lib/github/markup/gem_implementation.rb" \\
  && ok "lib/github/markup/gem_implementation.rb" \\
  || miss "missing critical file: lib/github/markup/gem_implementation.rb"
test -f "lib/github/markup/command_implementation.rb" \\
  && ok "lib/github/markup/command_implementation.rb" \\
  || miss "missing critical file: lib/github/markup/command_implementation.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/github/markup"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

github/markup is a Ruby library that determines which markup parser to use and converts markup files (Markdown, RST, AsciiDoc, Org-mode, Textile, etc.) to HTML. It's the first step in GitHub's rendering pipeline—it handles format detection and conversion, delegating sanitization and post-processing to downstream systems. The library supports 10+ markup formats through a pluggable adapter pattern. Simple modular architecture: lib/github/markup.rb is the main entry point, lib/github/markup/ contains implementation adapters (gem_implementation.rb, command_implementation.rb for subprocess calls, markdown.rb for special handling). Each markup format registers via lib/github/markups.rb. test/markups/ contains fixture files (input + expected .html output) for regression testing. bin/github-markup is the CLI wrapper.

GitHub's internal rendering infrastructure and Ruby developers who need to convert markup files to HTML and want GitHub-compatible output. Primarily used by GitHub.com itself to render README files, wikis, and documentation in repositories.

Production-ready and actively maintained. The codebase shows 18,952 lines of Ruby with comprehensive test fixtures for each supported markup format (test/markups/ contains .html reference files), CI/CD via GitHub Actions (.github/workflows/ci.yml), and clear dependencies listed in Gemfile. This is battle-tested infrastructure that powers GitHub.com's rendering.

Low-risk core but moderate dependency surface area: relies on external gem implementations (commonmarker, RedCloth, rdoc, asciidoctor, wikicloth, creole, org-ruby) and external CLI tools (docutils via Python, Pod2html via Perl). Each markup library is independently installed, creating version management complexity. The code is GitHub-owned so maintenance is reliable, but adding new markup formats requires integrating untested third-party libraries.

Active maintenance with dependabot.yaml configured (.github/dependabot.yaml) for automated dependency updates. Stale issue management enabled (.github/workflows/stale.yml). Recent work appears focused on keeping dependencies current and ensuring all markup formats continue to parse correctly via the test suite.

git clone https://github.com/github/markup.git && cd markup && bundle install && source .venv/bin/activate (if testing Python/RST features) && bundle exec rake test

Daily commands: bundle exec github-markup README.md or bundle exec rake test to run full suite. For local dev: python3 -m venv .venv && source .venv/bin/activate && cd script && ./bootstrap to install all dependencies.

• lib/github/markup.rb — Core entry point that dispatches markup files to the appropriate renderer based on file extension.
• lib/github/markups.rb — Registry mapping file extensions to markup implementations; essential to understand supported formats and how to add new ones.
• lib/github/markup/implementation.rb — Abstract base class defining the interface all markup implementations must follow.
• lib/github/markup/gem_implementation.rb — Concrete implementation wrapper for gem-based renderers; most common pattern for adding markup support.
• lib/github/markup/command_implementation.rb — Concrete implementation wrapper for shell command-based renderers; alternative pattern for external tools.
• bin/github-markup — CLI entry point; shows how the library is invoked in practice and serves as integration example.
• test/markup_test.rb — Comprehensive test suite with fixtures for all supported formats; demonstrates expected behavior and testing patterns.

• lib/github/markup.rb (Dispatcher) (Ruby, Registry pattern) — Routes markup files to the correct implementation based on file extension; orchestrates the rendering pipeline
  • Failure mode: Returns nil if format is unsupported or if the underlying renderer crashes; no graceful degradation (e.g., fallback to plaintext)
• lib/github/markups.rb (Registry) (Ruby arrays/hashes, DSL-style configuration) — Maintains the registry of all supported markup formats, mapping extensions to implementations and their render methods
  • Failure mode: Missing or misconfigured entry causes format to be unsupported; no validation that registered methods exist
• lib/github/markup/implementation.rb (Abstract Base) (Ruby inheritance, duck typing) — Defines the interface all renderers must implement; provides common utilities for subclasses
  • Failure mode: Subclasses that don't implement required methods will raise NoMethodError at render time
• lib/github/markup/gem_implementation.rb (Gem Wrapper) (Ruby reflection (method_missing, send), gem require, exception handling) — Wraps Ruby gem-based renderers; dynamically calls the gem's conversion method with error handling
  • Failure mode: If gem is not installed, raises LoadError; if gem's API changes, conversion fails at runtime
• lib/github/markup/command_implementation.rb (Command Wrapper) (Ruby backticks, $? exit status, shell escaping) — Wraps external CLI tools; spawns subprocesses, captures output, handles I/O and exit codes
  • Failure mode: If command not in PATH, raises Errno::ENOENT; shell injection possible if input not properly escaped

Add support for a new markup format via gem

1. Add the gem dependency to Gemfile and run bundle install (Gemfile)
2. Register the format in the markups array with gem_impl helper, mapping file extensions to the gem and conversion method (lib/github/markups.rb)
3. Create test fixture files: input file with desired extension and corresponding .html file with expected output (test/markups/README.{extension})
4. Run tests to verify the new format renders correctly (test/markup_test.rb)

Add support for a markup format via external command

1. Create a shell script wrapper in lib/github/commands/ that invokes the external tool and outputs HTML (lib/github/commands/{tool}2html)
2. Register the format in the markups array with command_impl helper, mapping extensions to the command script (lib/github/markups.rb)
3. Create test fixture input and expected output files (test/markups/README.{extension})
4. Run the full test suite to ensure the command wrapper works correctly (test/markup_test.rb)

Add format-specific custom processing logic

1. Create a new format-specific class in lib/github/markup/ inheriting from Implementation, overriding convert and/or other methods (lib/github/markup/{format}.rb)
2. In markups.rb, register the format using the custom class directly instead of gem_impl or command_impl helpers (lib/github/markups.rb)
3. Add test fixtures and verify behavior with the test suite (test/markup_test.rb)

• Ruby with Gem-based plugins — Flexible architecture allows adding new markup renderers as dependencies without modifying core code; leverages rich Ruby markup ecosystem (Markdown, Textile, reStructuredText, AsciiDoc gems).
• Shell command wrappers — Supports tools that don't have Ruby bindings (Pod, Pod6) or are more stable as CLI tools; decouples gem lifecycles from markup library.
• Strategy pattern (Implementation base class) — Abstracts rendering regardless of whether it's via gem or command, allowing uniform interface for dispatcher logic.
• Extension-based dispatch — Simple, reliable routing of files to renderers; file extensions are authoritative (not content sniffing), reducing ambiguity.

• Only handle markup conversion; sanitization and filtering done downstream

  • Why: Keeps library focused on single responsibility; markup rendering can be reused in different contexts with different security policies.
  • Consequence: Consumers must implement their own HTML sanitization pipeline; risk of XSS if sanitization is skipped or incorrectly applied.

• Gem-based renderers are required as dependencies; command wrappers are fallback

  • Why: Direct library calls are faster and more reliable than shell invocation; gems allow easier integration and custom processing.
  • Consequence: Larger dependency footprint; version conflicts possible between gems; command wrappers have overhead and reliability issues (shell escaping, PATH concerns).

• No caching within github-markup; caching assumed upstream

  • Why: Keeps library stateless and composable; caching strategy depends on deployment context (GitHub.com vs. standalone usage).
  • Consequence: Rendering the same file multiple times incurs repeated cost; callers must implement caching if needed.

• File extension determines format (no magic number detection)

  • Why: Fast, deterministic, explicit; avoids complexity of content sniffing and ambiguous cases.
  • Consequence: Misnamed files will render with wrong format; no fallback if extension is incorrect.

• HTML sanitization and XSS prevention (explicitly out of scope per README)
• Syntax highlighting of code blocks (delegated to github/linguist)
• Emoji, task lists, named anchors, or other GitHub-specific post-processing filters
• CDN caching or image optimization
• Real-time rendering or streaming
• Support for markup formats that cannot be rendered to HTML (e.g., binary formats)

Python 3 venv required for RST support (.venv activation is documented but easy to miss). Perl Pod2html only works on Perl >= 5.10; older systems fail silently. External tools (asciidoctor, wikicloth, docutils) must be installed separately—missing deps don't error immediately but cause rendering to fall back to plaintext. script/bootstrap and script/bootstrap.contrib bootstrap different subsets of dependencies; running wrong one leaves gaps. Test fixtures use hardcoded expected HTML—minor formatter changes break tests even if output is semantically correct.

• Adapter/Strategy Pattern — The entire markup library is built on pluggable adapters (GemImplementation, CommandImplementation, format-specific subclasses) that allow swapping parsers without changing dispatcher code—critical to understanding how to add new markup formats
• Subprocess/Shell Invocation with Error Handling — CommandImplementation.rb executes external Python/Perl tools via backticks and must handle failures gracefully; a key risk area for security and stability in this codebase
• Fixture-Driven Testing — The test suite doesn't write assertions—it compares rendered output against golden-master .html files in test/markups/; understanding this pattern is essential for adding tests and debugging rendering differences
• Markup Format Auto-Detection via File Extension — GitHub::Markups.render() determines which parser to use solely from filename extension (registered in lib/github/markups.rb); changing this mapping can break rendering for whole repositories
• Lazy Loading / Optional Dependencies — Markup doesn't require all gem dependencies upfront; each parser is require'd only when needed, avoiding huge installation footprint—Gemfile lists optional groups per format
• Cross-Language Interop (Ruby + Python + Perl) — The library orchestrates three language ecosystems: Ruby gems (commonmarker, asciidoctor), Python subprocess (docutils for RST), and Perl scripts (Pod2html); each has different error modes and CLI conventions
• Graceful Degradation / Fallback Rendering — When a parser fails or is missing, markup falls back to plaintext (escaped) rather than crashing—test/fixtures/fail.sh exercises this, essential for production stability

• github/linguist — Companion repo that handles syntax highlighting of code blocks in the HTML output after markup conversion
• commonmarker/commonmarker — The primary Ruby gem used by markup for Markdown parsing; understanding its options (tables, strikethrough) is essential
• gjtorikian/html-pipeline — Downstream GitHub gem that sanitizes, postprocesses, and adds emoji/task-list features to the HTML that markup produces
• asciidoctor/asciidoctor — One of the major external gem dependencies used for .adoc/.asciidoc format rendering
• python-docutils/docutils — Python library invoked via subprocess for reStructuredText (.rst) support; understanding its CLI is key to troubleshooting RST rendering

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test fixtures and assertions for all markup format edge cases

The test/markups/ directory contains fixture pairs (.markup and .html files) for various formats, but test/markup_test.rb likely only runs basic happy-path tests. There are missing edge case fixtures for: malformed markup, nested structures, special characters, and Unicode handling across all supported formats (asciidoc, rst, markdown, textile, mediawiki, org, creole, pod, rdoc, litcoffee). This would catch regressions in underlying library updates and improve robustness.

• [ ] Audit test/markup_test.rb to identify which edge cases are currently tested
• [ ] Create new fixture pairs in test/markups/ for edge cases: nested lists, deeply nested code blocks, Unicode/emoji, malformed syntax for each format
• [ ] Add corresponding assertions in test/markup_test.rb to validate these fixtures
• [ ] Run full test suite to ensure no regressions

Implement and test command-line interface robustness for lib/github/commands/ implementations

The repo has command implementations (pod2html, pod62html, rest2html) in lib/github/commands/ but test/markup_test.rb likely doesn't thoroughly test error handling when these external commands fail, timeout, or produce unexpected output. This is critical since these are shell-out operations that can fail unpredictably in CI or production. Missing: timeout handling, stderr capture, and invalid input scenarios.

• [ ] Review lib/github/markup/command_implementation.rb for error handling gaps
• [ ] Add tests in test/markup_test.rb for: command timeouts, non-zero exit codes, missing command binaries, and corrupted input
• [ ] Add test fixtures in test/fixtures/ that intentionally trigger failures
• [ ] Update lib/github/commands/ implementations to handle edge cases gracefully

Add type hints and documentation to lib/github/markup/implementation.rb base class and subclasses

The lib/github/markup/ directory has an inheritance hierarchy (implementation.rb as base, with command_implementation.rb, gem_implementation.rb, markdown.rb, rdoc.rb as subclasses), but likely lacks YARD documentation or type hints on public methods. This makes it harder for new contributors to understand how to add support for new markup formats. Improved documentation would lower contribution friction significantly.

• [ ] Add YARD @param and @return documentation to lib/github/markup/implementation.rb (especially to_html and other public methods)
• [ ] Document the contract for subclasses in lib/github/markup/gem_implementation.rb and lib/github/markup/command_implementation.rb
• [ ] Add example of how to add a new markup format (referencing lib/github/markup/markdown.rb or lib/github/markup/rdoc.rb as templates) to CONTRIBUTING.md
• [ ] Verify documentation renders properly with yard doc command

• Add test fixtures for edge cases: test/markups/ has coverage for basic cases but lacks fixtures for nested lists, complex tables, and malformed input in Markdown/RST/AsciiDoc—create 3-5 fixture files with expected HTML to catch regressions: low: basic markup knowledge, fixture format
• Document markup format feature parity: README lists supported formats but doesn't explain which features (tables, strikethrough, etc.) work in each format—create a comparison matrix or document known limitations of each converter: low: research, writing
• Add timeout and memory limits to command_implementation.rb: subprocess calls to docutils and Pod2html currently have no safeguards against runaway processes—add Timeout::timeout() and document resource limits: medium: Ruby subprocess patterns, system resource limits

The github/markup library has a moderate security posture with notable risks around command execution, output sanitization, and dependency management. The primary concern is the reliance on external command-based markup processors (pod2html, rest2html) which present command injection risks if inputs aren't properly sanitized. Additionally, the library explicitly defers HTML sanitization to downstream consumers, creating XSS risks if used independently. Dependency management and test fixture handling require review. Strengths include CI/CD workflows and organized code structure

• High · Command Execution via External Markup Processors — lib/github/markup/command_implementation.rb, lib/github/commands/*. The codebase implements CommandImplementation that executes external commands for markup processing (pod2html, pod62html, rest2html). This approach is vulnerable to command injection if user-controlled input is passed unsanitized to these shell commands. The presence of bin/github-markup and lib/github/commands/* suggests direct command execution. Fix: Use safe argument passing with proper escaping (e.g., Kernel.system with array arguments). Validate and sanitize all inputs. Consider using dedicated parsing libraries instead of shell commands. Implement strict allowlists for executable paths.
• High · Potential XSS in Markup Rendering — lib/github/markup.rb, lib/github/markups.rb. The library's README explicitly states 'markup itself does no sanitization of t[he HTML]'. While sanitization occurs downstream on GitHub.com, if this library is used independently by other projects, the output HTML could contain unescaped user input or malicious markup that wasn't neutralized by the underlying markup processors. Fix: Implement output sanitization within the library itself using gems like 'sanitize' or 'loofah'. Never rely on downstream sanitization. Provide secure-by-default rendering options.
• Medium · Insufficient Input Validation on File Extensions — lib/github/markups.rb, lib/github/markup.rb. The markup library determines processors based on file extensions (.asciidoc, .rst, .pod, etc). If file extension detection is case-insensitive or lacks strict validation, attackers could bypass intended markup processors or trigger unintended handlers. Fix: Implement strict, case-sensitive file extension matching. Use explicit allowlists of supported extensions. Validate that extensions match expected formats before routing to processors.
• Medium · Dependency Version Management — Gemfile, Gemfile.lock, github-markup.gemspec. The Gemfile and Gemfile.lock are present but content not provided. Without visibility into pinned versions, there's risk of using outdated markup processing libraries with known vulnerabilities (e.g., old versions of Markdown, AsciiDoc, Textile processors). Fix: Audit all gem dependencies for known CVEs using 'bundle audit'. Pin versions to latest secure releases. Implement automated dependency scanning in CI/CD (noted in .github/workflows/ci.yml). Keep dependencies updated regularly.
• Medium · Test Fixtures May Contain Malicious Content — test/markups/*, test/markup_test.rb. The test/markups/ directory contains multiple markup files (README.asciidoc, README.rst, etc.) with corresponding HTML outputs. If these fixtures are used for testing without proper isolation, they could contain payloads that demonstrate vulnerabilities or escape sequences. Fix: Review test fixtures for potentially dangerous markup. Keep fixtures separate from production code. Use sandboxed test environments. Document the origin and safety of all test data.
• Low · Missing Security Documentation — Repository root. No SECURITY.md or security policy file is present. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file with instructions for responsible vulnerability disclosure. Follow GitHub's security policy guidelines. Include information about supported versions and patching timelines.
• Low · Executable Scripts Without Clear Validation — bin/github-markup, script/bootstrap, script/cibuild. The presence of bin/github-markup and script/* executable files suggests command-line entry points. These need careful input validation to prevent abuse. Fix: Audit all executable entry points for input validation. Document expected inputs. Implement argument parsing with validation. Consider using gems like 'Thor' or 'OptionParser' for safe CLI argument handling.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.