Markdown code blocks use the same style for text and code blocks

[camelid]

From this page:

Yet some code samples are syntax-highlighted:

I checked the source for this page, and it looks fine:

# Documentation tests

`rustdoc` supports executing your documentation examples as tests. This makes sure
that examples within your documentation are up to date and working.

The basic idea is this:

```ignore
/// # Examples
///
/// ```
/// let x = 5;
/// ```
```

The triple backticks start and end code blocks. If this were in a file named `foo.rs`,
running `rustdoc --test foo.rs` will extract this example, and then run it as a test.

Please note that by default, if no language is set for the block code, `rustdoc`
assumes it is `Rust` code. So the following:

``````markdown
```rust
let x = 5;
```
``````

is strictly equivalent to:

``````markdown
```
let x = 5;
```
``````

There's some subtlety though! Read on for more details.

## Passing or failing a doctest

Like regular unit tests, regular doctests are considered to "pass"
if they compile and run without panicking.
So if you want to demonstrate that some computation gives a certain result,
the `assert!` family of macros works the same as other Rust code:

```rust
let foo = "foo";

assert_eq!(foo, "foo");
```

This way, if the computation ever returns something different,
the code panics and the doctest fails.

I'm wondering if this might be a bug in mdbook, but I figured I would post here first since this is the only place I've seen it.

[bugadani]

Technically those examples are not marked to be syntax-highlighted as rust. The first one, ignore doesn't specify, the next ones specify "markdown". Inconsistent, but it smells like incorrect intent, and not a mdbook bug to me.

[camelid]

I know, but mdBook has support for Markdown syntax highlighting, yet the code marked with markdown is not being highlighted as Markdown.

[bugadani]

Ah, that wasn't clear, sorry.

[camelid]

Cc @ehuss – I'm thinking this might be an mdBook issue

[ehuss]

I don't understand exactly what you are expecting.

The first example has no language. You can change it to rust,ignore, but I don't really know if that is an improvement, since it is all comments, it will change it to a harder-to-read color.

The second and third examples are correctly highlighted as markdown, but it is a code block, so it only has one color.

[bugadani]

Well, I deleted my previous comment since that was wrong, but there is a longer code block that has plain text and inner code blocks, and it is rendered using a single color. Starts with

``````markdown
First, we set `x` to five:

I can see in the HTML that it's picked up as expected as language-markdown, but it seems interesting that it's rendered the same as the no-language ones.

[ehuss]

Since it is inside a code block, "plain text" in markdown will be rendered the same as code blocks (with triple backticks) since they are all a "code" style. Other markdown constructs (like headers, lists, links, etc.) will have different colors.

It might be feasible to style hljs-code differently, but that seems like it will take a fair bit of work to make sure it doesn't have negative consequences. I'm also unsure how to style it differently, since it is already in a <code> block.

[jyn514]

Personally this doesn't seem like a giant loss to me; the point of these examples is the markdown syntax, not the Rust code itself. I wouldn't mind having the rust highlighted, but if it's hard to do like ehuss mentioned, I'm not sure it's worth it.

[bugadani]

I don't necessarily agree with you here. In the context of markdown, plaintext is not code, so I think it should be styled somewhat differently. And most of the highlighters do, I think.

Let's see what GitHub does here.

random code

I'm not arguing for the inner code to be rust-highlighted, but the markdown be markdown-highlighted :)

[jyn514]

Well, in any case, this isn't a rustdoc issue, it's a mdbook issue. Can someone move it there?

[ehuss]

Transferred.

I didn't say it should or should not be styled the same, I just said why it is the same. It would probably be reasonable to add a different color to hljs-code, but I don't know what a good color choice would be. One would need to pick colors for all five color themes, make sure they don't regress on any language (and there are many). That would be a fair bit of work I think.