Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Styling for inline code snippets is ugly #718

Closed
jimporter opened this issue Aug 22, 2015 · 13 comments
Closed

Styling for inline code snippets is ugly #718

jimporter opened this issue Aug 22, 2015 · 13 comments

Comments

@jimporter
Copy link
Contributor

There are a couple of things I don't like about how inline code is formatted. Some of these are a matter of opinion, but for completeness, I'll list them anyway, and you can feel free to ignore them. :)

  1. Inline code is reddish (#E74C3C in readthedocs and #C7254E in mkdocs/bootswatch), which - aside from being somewhat distracting in my opinion, is subtly different from the highlight.js color for strings (#D14).
  2. mkdocs/bootswatch themes give inline code a pink background, which is also distracting. The readthedocs style is nicer because it has the same background as code blocks.
  3. Links whose text is inline code don't look like links. I think the text should use the link color, since otherwise it's impossible to tell that it's a link.

I'm happy to provide a patch for these issues, provided you agree that they're issues. If you disagree with some of them, let me know and I'll exclude those parts from the patch.

@jimporter
Copy link
Contributor Author

Oh, if you want to see these changes in action, I've done all of the above with some extra CSS for my project's docs (using the yeti theme on a pretty-recent master version of MkDocs). The main page has examples of inline code with and without links: http://jimporter.github.io/mettle/

@dirk-olmes
Copy link

Ah and I thought I was the only one not liking the reddish inline code blocks.

Given that @jimporter and me are already two mentioning this issue, wouldn't it make more sense to change the default of the theme(s)?

@tomchristie
Copy link
Contributor

Before and after screenshots would probably be helpful.

@d0ugal
Copy link
Member

d0ugal commented Aug 24, 2015

This has bothered me too, just never enough to do anything about it :) I would support changing this. It certainly looks out of place on the MkDocs documentation.

Updates to the bootswatch themes need to go in this repo tho' https://github.com/mkdocs/mkdocs-bootswatch

@facelessuser
Copy link
Contributor

It has to do with how reStructured text gets formatted vs markdown. I think usually, there are additional classes for inline code blocks in reStructured. Markdown conversion to html is a lot more simple. So our inline code blocks get targeted as something slightly different than what is intended when using markdown.

@waylan
Copy link
Member

waylan commented Aug 24, 2015

@facelessuser is correct. Take a look as Read the Docs' own documentation (which is generated by Sphinx using ReStructeredText). All the "inline code" is red and marked up as follows:

<code class="docutils literal"><span class="pre">sphinx-quickstart</span></code>

That is using ReStructuredText's literal role. The code role might get styled differently. I say "might" because I don't see that the theme has a style defined for that role. One of my annoyances with Rest is that the default literal span in not a code span. Therefore, code spans generally get styled differently than I expect and themes often ignore actual code spans.

In any event, the ugly red style is part of the RTD theme as it comes from them. Is that something MkDocs wants to change? I realize there are some changes already, but those mostly address differences in features between Sphinx and MkDocs. This would in effect be a visual change only.

@jimporter
Copy link
Contributor Author

Well, if RTD's theme intentionally uses that red, I don't have to change that, but I think it'd make sense to change it for the mkdocs/bootswatch themes.

@jimporter
Copy link
Contributor Author

Here's a before and after on the mkdocs theme:

colors

@d0ugal
Copy link
Member

d0ugal commented Aug 25, 2015

Yup, that does look better to me

@trel
Copy link
Contributor

trel commented Aug 25, 2015

agreed.

@robodude666
Copy link

👍

I noticed recently that it's impossible to tell if inline code has a link on it, without mousing over it first.

@jimporter could you share the CSS used to make those changes? 😄

@jimporter
Copy link
Contributor Author

@robodude666 https://github.com/jimporter/mettle/blob/master/doc/css/extra.css#L23-L26

Just change the color to whatever matches your theme (I use yeti).

@jimporter
Copy link
Contributor Author

Here's the pull request for the Bootswatch themes: mkdocs/mkdocs-bootswatch#12

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

8 participants