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.

[elasticspoon]

I opened a PR to fix the theming issues.

I also realized the those pages don't have <h1> tags which is an a11y concern. Should I open a new issue for that? It seems unrelated to this one.

[gopherbot]

Change https://go.dev/cl/553957 mentions this issue: _content: fix markdown styling with dark theme under /src

[hyangah]

Out of curiosity - how do users end up landing in the /src page? I thought package docs usually link to the original VCS pages instead of /src. For example, https://pkg.go.dev/cmd/compile#section-directories has links to https://cs.opensource.google/go/go/+/refs/tags/go1.21.6:src/cmd/compile/.

[hyangah]

Thanks @elasticspoon for the fix!
@findleyr I assigned it to you since you are already a reviewer.

[elasticspoon]

Out of curiosity - how do users end up landing in the /src page? I thought package docs usually link to the original VCS pages instead of /src. For example, https://pkg.go.dev/cmd/compile#section-directories has links to https://cs.opensource.google/go/go/+/refs/tags/go1.21.6:src/cmd/compile/.

My guess would be the go dev pages are indexed vs the opensource.google ones are not. If you google (or ddg for that matter) the opensource.google pages don't show up. The top result for "golang ssa compiler" atleast for me is the go.dev site.

[findleyr]

@hyangah just grepping x/website, there are a few links to pages in GOROOT, e.g. https://go.dev/doc/install/source links to bootstrap.sh.

I finally understand the fix, and it seems reasonable.

[xieyuschen]

Hi @findleyr @hyangah , i just found another page https://go.dev/lib/godoc/analysis/help looks like this as well, i used the same code as @elasticspoon 's fix in another PR.