x/website: markdown files unreadable with dark theme

[xieyuschen]

What is the URL of the page with the issue?

https://go.dev/src/cmd/compile/internal/ssa/README

What is your user agent?

Safiri and Chrome

Screenshot

Safari

Chrome

What did you do?

I use the dark mode in my mac desktop. The website isn't rendered properly in my desktop. I tried to visit it both chrome and safari to avoid the disturb of the plugins(I don't use safari hence it's default without any plugin installed).

$ uname
Darwin GF9534F26Q 21.2.0 Darwin Kernel Version 21.2.0: Sun Nov 28 20:28:41 PST 2021; root:xnu-8019.61.5~1/RELEASE_ARM64_T6000 arm64

What did you expect to see?

The fonts should be rendered in a light color.

What did you see instead?

They are in dark mode.

[xieyuschen]

As i'm not familiar with the framework used in golang documentation website, I have no idea to fix it by my own:(

[mauri870]

Apparently all README files rendered at go.dev look this bad with dark mode, another one is https://go.dev/src/cmd/compile/README.

I'm not sure if README files were supposed to be readable at all in go.dev, but some of these pages are really good introductions that don't have an equivalent page, such as https://go.dev/doc/asm. We should definitely fix this.

It appears that data-theme="light" renders them correctly, so this appears to be an issue with dark mode in particular.

[elasticspoon]

I looked at this a bit. The following CSS is responsible for styling font.

.Article {
  color: var(--color-text);
}

On the pages where the dark theme works the main body of text is enclosed in an <article> tag as such:

<main class="SiteContent SiteContent--default" id="main-content">
    <article class="Doc Article">
        <h1>A Quick Guide to Go's Assembler</h1>

The markdown files under go.dev/src are not wrapped in an <article> tag:

<main class="SiteContent SiteContent--default" id="main-content">
  <h2 id="introduction-to-the-go-compiler">Introduction to the Go compiler</h2>

I believe the issue is there is no .tmpl file for files under the /src path unlike for the /doc.

The easiest fix would be to add a /src/default.tmpl. However, I am not sure what sort of template should be used for those files. Borrowing the template for .doc files does fix the issue.

I could submit a PR for that if fixing in this manner is acceptable.

Also, the "fixed" page is still missing a correct title attribute which for .doc files seems to be supplied with a comment string within the markdown.

<!--{
	"Title": "A Quick Guide to Go's Assembler",
}-->

Fixing that would require editing the markdown itself as well.

[mauri870]

@elasticspoon Thanks for looking into this! Your fix seems reasonable, adding a template for the src seems fine, we just have to make this new styling only apply to normal text and markdown files, and not go source files, so pages such as https://go.dev/src/cmd/compile/main.go continue to work as before.

Regarding the title, I think that is no big deal since currently any src/ page has a generic title - The Go Programming Language.