Skip to content

Contributing

mdink edited this page Feb 28, 2026 · 1 revision

Contributing

Thank you for contributing to mdink!

Prerequisites

  • Rust 1.86 or later (edition 2024)
  • A terminal emulator (required for cargo run — mdink needs a real TTY)

Install Rust via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Development commands

# Run all tests
cargo test

# Run a single test by name (substring match)
cargo test test_name

# Lint — must be clean before committing
cargo clippy -- -D warnings

# Run the app on a sample file (requires a real terminal)
cargo run -- testdata/basic.md

# Exercise all four font-slot rendering paths
cargo run -- testdata/font-slots.md

Before submitting

  1. cargo test passes with no failures.
  2. cargo clippy -- -D warnings is clean (zero warnings).
  3. New functionality has tests.
  4. New style-producing code reads from &MarkdownTheme rather than hardcoding colors or modifiers.

Coding rules

These rules are derived from real refactors in this codebase. See .claude/rust-practices.md for the full rationale.

Match arms — catch-all last

Wildcard arms (_ or Type::Variant(_)) silently shadow every arm below them. Always put catch-all arms last within their group.

// Wrong — Start(_) swallows Link, Emphasis, etc.
Event::Start(_) => skip(),
Event::Start(Tag::Link { .. }) => handle_link(), // never reached

// Correct
Event::Start(Tag::Link { .. }) => handle_link(),
Event::Start(Tag::Emphasis) => handle_em(),
Event::Start(_) => skip(), // catch-all last

Ownership — copy cheap values out before mutating

When a shared borrow conflicts with a subsequent mutation, extract the needed value (if it's Copy) before the mutation begins.

// depth is u32 (Copy) — extract it, release the borrow, then mutate
let depth = match self.state_stack.last() {
    Some(State::Skipping { depth }) => *depth,
    _ => return,
};
self.state_stack.pop();

Prefer std::mem::take over clone-then-clear

let content = std::mem::take(&mut self.current_spans);
self.blocks.push(Block::Paragraph { content });

Use debug_assert! for invariants

debug_assert! compiles to nothing in release builds. Use it to document "this cannot happen if my logic is correct".

debug_assert!(!self.style_stack.is_empty(), "pop_style on empty style_stack");

Use LazyLock for expensive test fixtures

Pay the construction cost once per test binary, not once per test. Applies to loading syntax sets, theme files, or any slow initialization.

static HIGHLIGHTER: LazyLock<Highlighter> = LazyLock::new(Highlighter::new);
fn h() -> &'static Highlighter { &HIGHLIGHTER }

Use include_str! for test data files

Embedding a file at compile time turns a missing or moved file into a build error rather than a runtime test failure.

let source = include_str!("../testdata/font-slots.md");

Module boundary rule

No stage may import from a later stage in the pipeline:

cli → config → theme → highlight → parser → layout → renderer

highlight.rs is a leaf module: it must never import from any other mdink module. syntect types must not appear in parser.rs, layout.rs, or renderer.rs.


Adding a new block type

Adding a new RenderedBlock variant is the most common contribution. The change touches exactly four files:

1. src/parser/mod.rs

Add pulldown-cmark event handling to produce the new variant:

// Example: handling a new FancyBox block type
Event::Start(Tag::FancyBox) => {
    self.push_state(State::InFancyBox);
}
Event::End(TagEnd::FancyBox) => {
    let content = std::mem::take(&mut self.current_spans);
    self.blocks.push(RenderedBlock::FancyBox { content });
    self.pop_state();
}

2. src/layout/mod.rs

Add a match arm to flatten() that converts the new variant into display lines:

RenderedBlock::FancyBox { content } => {
    // wrap and push lines, similar to Paragraph
}

3. src/renderer.rs

Add a match arm to draw() (or the relevant draw helper) that renders the new variant.

4. src/theme/mod.rs

If the new block needs theme-configurable styling, add a new struct (e.g. FancyBoxStyle) with Serialize/Deserialize, add it to MarkdownTheme, add a default, and add a strip_colors call in MarkdownTheme::strip_colors().


Project roadmap

The planned phases are tracked in plans/overview.md (in the repository). High-level:

  • Phase 3 — Lists, tables, blockquotes (new RenderedBlock variants)
  • Phase 4 — Images: Sixel/Kitty/iTerm2 inline rendering (complete — already shipped)
  • Phase 5 — JSON theming (complete — already shipped)
  • Phase 7 — Man page + shell completions via xtask (complete — already shipped)