readthedocs/sphinx_rtd_theme

special case external reference link styling

Open

#932 opened on May 26, 2020

View on GitHub
 (0 comments) (0 reactions) (0 assignees)CSS (3,473 stars) (1,413 forks)batch import
Good First IssueImprovementNeeded: design decision

Description

Problem

Internal links to things like modules / classes etc will receive bold black text, which makes them distinguishable from the otherwise teletype orange.

External links would benefit from similar treatment. The external links come up with the intersphinx extension, not sure what else emits reference external but probably others?

Currently:

sphinx_rtd_links

With some styling

sphinx_rtd_links_styled

Reproducible Project

Attached here is a minimal repro that will use internal and external links: sphinx_rtd_theme_link_styles.zip

Toggle if True: near bottom of conf.py to include / exclude custom CSS styling from _static/custom.css.

Edit: I made the internal links green as visual indicator for development, if there's green in the internal links then you didn't switch off the custom CSS and are not testing theme natively! :slightly_smiling_face:

I would ordinarily submit a PR, but TBH I have only hacky web skills and the theme is clearly well thought out in terms of colors. AKA y'all know better what it should be, but AFAICT bold + some-non-orange-color works. It's also very easy to override for users.

Relevant CSS (I probably have not so great selector...but hacking is all I can do with web x0):

/* Make external links stand out from teletype text. */
a[class='reference external'] > code > span {
  color: #2980B9;
  font-weight: bold;
}

Error Logs/Results

N/A

Expected Results

External reference links should be visually distinct from standard teletype text so that users understand it is actually link text! :slightly_smiling_face:

Environment Info

  • Python Version: 3.7.7
  • Sphinx Version: 3.0.3
  • RTD Theme Version: 0.4.3

Please let me know if there's anything I can do to help fix it!

Contributor guide