cc @dmitshur

Generally speaking, this is by design, not a bug. What GitHub does where every piece of code font text has its own box and background is typographically clumsy, as demonstrated by this sentence.

Is the tutorial somehow not readable? It seems perfectly fine to me. Many many books have been written with code displays that don't have backgrounds. See for example The Go Programming Language.

I think readability is improved by a subtle background color difference, even if it looks aesthetically unpleasant to some.

The reason is that some semantics are being conveyed by the choice to write some text in code font, but it is easy to miss the difference when only the typeface is different. Here's an example from the text above:

• Declare a main package (a package is a way to group functions, and it's made up of all the files in the same directory).

Without the background color difference, and depending on what fonts are actually used (system-dependent), it may be easy to miss that main is a different font, and read it like this:

• Declare a main package (a package is a way to group functions, and it's made up of all the files in the same directory).

That changes the meaning. The reader being introduced to Go would think that this is talking about some abstract "main package", not realizing that it is actually a specific package name main.

It's a minor thing, but I believe the downsides of the change are even less significant.

I believe the tutorial has few confusing point but it could be better. Many websites may have reasons to support the Markdown style.

Furthermore, the website is inconsistent in style, we can see the grey background for code in blog articles (like json-rpc) or package documentations (like bufio). It seems authors prefer to choose what they like and there is no rule.

Anyway, I think it might be meticulous and trivial work to unify the style, and it does involve the input-output ratio.

If this is still in the works, I'd add in syntax highlighting beyond just a shade change would be nice. Possibly a light and dark version.

For someone just learning the language, which is already a bit complex compared to something like JavaScript or Python, distinguishing keywords from values and anything else that might be relevant could be helpful.

Rust has a great set of websites that allow for toggling of a handful of palettes, which helps to distinguish documentation from snippets and examples. I think the platform powering those documents is mdBook.

Just my $.02. I know y'all are doing this in your spare time and all of us Gophers definitely appreciate it!

(If I can help at all, please let me know.)

Thanks for reading!