A list of common mistakes that people make while writing Markdown

Spec
1

Continuing the discussion from Djot: A light markup language by @jgm, knowingly acting out xkcd 386 “Duty Calls”:

I think the members of this forum spend too much time talking about power-user features like ease-of-implementation, parsing speed, advanced formatting features, and terse syntax. I don’t want to lock power users out of the ecosystem entirely (after all, I am one), but I don’t think it makes sense to elevate power user needs above the needs of non-power-users. By definition, we can take care of ourselves even when conditions are less than perfect.

The main “non-power-user” problem I see in Markdown is a trickle stream of incoming “bug reports” and help questions from people who think rustdoc corrupted their docs, because they accidentally triggered a feature that they didn’t intend to use. They just want to write. Many people who just want to write are good writers with valuable things to say. Some of the best works ever written use nothing more complex than paragraphs and headers.

It’s too easy to accidentally write refdefs

The short version is that you can too-easily write a link reference definition, usually wrapped in a bulleted list:

- [to prevent this]: verbosity (it should not be this easy to write text that doesn't appear in your document at all)

And that line will completely vanish:

This doesn’t just happen in issue trackers; people really do accidentally write this. You can infer how common it is with a search for clippy::doc_nested_refdefs.

For example, compare this docs.rs page with its source code.

It’s too easy to accidentally write HTML

Many cases of this are Rust-specific, since we write generics in angle brackets, so anyone who doesn’t wrap it in code spans winds up writing Vec<T> and getting Vec. Our lint for this is rustdoc::invalid_html_tags, but you can also hit that lint by accidentally writing a block quote.

For example, compare this docs.rs page with its source code.

It’s too easy to accidentally write block quotes

A weird quirk of CommonMark is that you need a space after - and * to write lists, but you don’t need a space after > to write a block quote.

-not a list
*not a list
>a blockquote

-not a list
*not a list

a blockquote

Accidental block quotes aren’t as bad as accidental HTML or accidental refdefs, since they don’t delete whole chunks of text from your document, but they’re still annoying.

In one example, you wind up writing a block quote where you intended to write the closing bracket on an HTML tag, so you get the rustdoc invalid_html_tags warning. Compare this docs.rs page with its source code.

In another example, this results in breaking out of a paragraph or a table, and you get the clippy::doc_lazy_continuation warning. Compare this docs.rs page with its source code.

It’s too easy to accidentally use lazy paragraph continuations

When I added the clippy::doc_lazy_continuation lint, I had to fix all the places where it fired in Clippy itself. It was 6:4 accidental:deliberate lazy continuations.

For another example, compare this docs.rs page with its source code

1 Like