How do we best display code examples on MDN Web Docs?

[schalkneethling]

In mdn/yari#6083 @lex111 proposed a change to how pre blocks are currently styled and displayed. Quoting from the pull request:

Code blocks are using soft-wrap for long lines, which makes the code harder to read and understand. In general, this is not a recommended practice for docs, since code blocks should be scrollable since it also makes the page longer and prevents the user from seeing the code as usual way.

In the following comment @caugner made a valid point that the change might degrade the experience for some users. Quoting from the pull request:

Unfortunately this degrades the usability on larger screens (see screenshots below).
Please maintain the current behavior for pointer devices (@media (hover: hover)), distinguishing them from touch devices (@media (hover: none)). See: https://developer.mozilla.org/en-US/docs/Web/CSS/@media/hover

A conversation has evolved from there, so I believe it is a good time to start a discussion and reach an actionable conclusion. As mentioned in this comment, I do believe we can improve the current user experience by combining @lex111’s proposal with @caugner’s suggestion and merging the referenced pull request.

There is a larger topic in play here related to linting code examples within the content and applying standard formatting using a tool such as Prettier as mentioned by @Rumyra.

There are valuable suggestions from others in the pull request thread as well, which should also be taken into account here.

Related issues

• Add a Markdown linter for all .md files
• Add US English spell checker/linter for markdown
• Update Markdown-related meta-docs with info about how to use Markdown linters
• [Markdown] Running Prettier

Historic reference

• https://github.com/mdn/doc-linter-webextension
• https://github.com/mdn/doc-linter-rules

[OnkarRuikar]

I have implemented some features to the code block. That will further improve the user experience:

lineNo.mov

Detailed info is on the PR page: mdn/yari#6372

As the wrapped lines become more distinguishable, it may save us from manually chopping the long lines in markdown code fences. Also, it seems we detest limiting the line length.

---

Linting PRs

We shouldn't make contribution process confusing/hard. With current lint configurations, during daily manual linting, we are finding only 4-5 fills with small issues. Refer https://github.com/mdn/content/pull/16315/files. Also, automatic changes to code may lead to merge conflicts in local repos.

Daily lint PRs

If we lint once a day, there will be one less step getting the PR merged. Also, no lint issue will get skipped. To add a new lint rule it's good to fix it in the entire repo first then add it to the daily task. @teoli2003 has explained it well.

[schalkneethling]

Comment from @OnkarRuikar in mdn/yari#6372 (comment):

Some of the popular documentation sites do use highlighting even for small blocks:

Here we can quickly spot what the discussion is all about. We don't have to necessarily spend time on reading the entire code description. Reading that site is a breeze.

Most of the readers land on a documentation page from google search, looking for finding solutions for their problem quickly. They are always in hurry, and they mostly scan the page. Very few read the page from top to bottom like a text book.
With this feature, readers who are in hurry won't necessarily have to read the surrounding text to get the point/solution. Experienced developers or those who have already read the page will find this useful and time saving.

Some of us find the feature useful. Form the mentioned discussion:

I agree with you @chrisdavidmills that highlighting is a pain for the author, but IMO it can be better for the reader, even in quite small blocks of code.

Also, authors will be happy to take the small extra effort to give better user experience. They are always eager to add extra decorations to their content.

---

longer code blocks are usually not good documentation anyway (they are better as separate example sites).

Agreed. But we can't always force authors to have small code blocks and rearrange their content significantly. Arguing with them on the size of code blocks won't be encouraging. Also, there are exiting long code blocks.

I think highlighting creates (and in our past created) a maintenance problem, where the code gets updated and the references don't.

But we have a strong review system now. As per my experience, the reviewers here are very efficient and they do not let a single mistake pass.

[schalkneethling]

Additional input from @hamishwillee:

• Enhance code example block: line numbers, highlight lines, line anchors yari#6372 (comment)
• Enhance code example block: line numbers, highlight lines, line anchors yari#6372 (comment)

[Josh-Cena]

Just want to jump in on this. Docusaurus (which both Alexey and I are maintainers of) uses a toggle button between "wrapping" and "non-wrapping" mode: https://docusaurus.io/tests/pages/code-block-tests#code-block-wrapping-tests

Line numbers are not necessary IMO since I've never found a need to say "look at line X" where it's not convertible to a comment.

Highlight lines are implemented in Docusaurus as "magic comments": https://docusaurus.io/docs/markdown-features/code-blocks#highlighting-with-comments They are not necessary on MDN, though, since it's very hard to create a uniform rule about when and where we should use highlight lines, and comments convey the semantics better.

[OnkarRuikar]

Highlighting using magic comments sounds better as it does not need line numbers, so it doesn't break after the code gets updated.

Decision was made not not have such features as they are hard to maintain. The mdn web docs had these features before...

[Rumyra]

I'm closing this due to linting updates which have happened. If anyone wants to suggest any other updates to code blocks, feel free to open an issue on yari 👍