Repository navigation
Contributing
Thank you for contributing to mdink!
- 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# 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-
cargo testpasses with no failures. -
cargo clippy -- -D warningsis clean (zero warnings). - New functionality has tests.
- New style-producing code reads from
&MarkdownThemerather than hardcoding colors or modifiers.
These rules are derived from real refactors in this codebase. See .claude/rust-practices.md for the full rationale.
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 lastWhen 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();let content = std::mem::take(&mut self.current_spans);
self.blocks.push(Block::Paragraph { content });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");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 }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");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 RenderedBlock variant is the most common contribution. The change touches exactly four files:
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();
}Add a match arm to flatten() that converts the new variant into display lines:
RenderedBlock::FancyBox { content } => {
// wrap and push lines, similar to Paragraph
}Add a match arm to draw() (or the relevant draw helper) that renders the new variant.
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().
The planned phases are tracked in plans/overview.md (in the repository). High-level:
-
Phase 3 — Lists, tables, blockquotes (new
RenderedBlockvariants) - 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)