Hugo documentation webpage contrast too low, getting eyestrain

Howdy! I’m reading through the doc at, and am having
a constant feeling that it’s… dim. I can’t focus on the text properly,
and I think it’s because the text contrast is too low. Zooming in
doesn’t even really help much. Is there a way to ask the site to use a higher contrast theme? explains the issue, but has bit-rotted a bit. helps but is overkill; it makes the site ugly.

I think @budparr is the person to ask about this as he created the Hugo Docs theme and, to my knowledge, is especially thoughtful and smart about accessibility. Have you tried running the site through a WCAG 2.0 validator?

At your suggestion, I did try one ( ) but it didn’t specifically call out low contrast as a problem except in a few images.

To be more specific, exhibits the problem in the normal text “To verify your new install”. Chrome dev tools show this is rendered in color #555.
Unchecking that box in chrome dev tools evidently lets me see what it would look like normally… and it’s beautifully visible then!

Simply changing #555 to something closer to black would make the entire site far more usable for me.

(The headings are then rather contrasty; they could continue to be #555 without bothering me at all.)

Gray text is bad. Dark gray text on a light gray background is worse. Light gray text on a light gray background is just mean; whoever invented “highlighting” that makes comments less legible than the code (Add a Theme) should be beaten with a high-contrast stick.

Disclaimer: I also hate colorized ls output. Using MacPascal one semester in college left me with a lasting distaste for all forms of syntax highlighting.


Yes, you are referring to the highlight formatting for code. It does appear to be AA compliant at around a contrast ratio of 6.23.

However, personally I agree, the default highlight styles for code in Hugo are too low contrast for real comfort.

1 Like

20-year-old designers with perfect vision are really going to hate their “accessible” decisions when they hit 50. :smirk:


I’m surprised that contrast level is considered compliant. Are you sure?

The standard probably needs to give more weight to the thinness and size of the type. For the small thin text in question, a bit more contrast is appropriate.

May I suggest that you open a GitHub issue at the Hugo website Theme repo.

You can also link to this thread from the GitHub issue.

1 Like

I was surprised that AA compliance is down at 4. something.

Of course, you really should be aiming for AAA compliance.

It definitely feels low contrast to me personally - but then I have 58 yo eyes. But then I’ve never really understood the grey-on-grey design movement.

Haha, well it is all very personal isn’t it. I used to really dislike dark themes for coding but now I don’t like light themes - odd. On the other hand, I dislike dark web site themes generally. So I use Monokai for Hugo highlighting and “Dark+ Material” for VScode.

Ad hominem arguments are not allowed here, as far as I am concerned.

Locking this topic right now.

To the original poster

Please open a GitHub issue at the Hugo website Theme repo, as I said above.

1 Like