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
Labels

Comments

@jimporter
Copy link
Contributor

@jimporter jimporter commented Aug 22, 2015

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

@jimporter jimporter commented Aug 22, 2015

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

@dirk-olmes dirk-olmes commented Aug 24, 2015

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

@tomchristie tomchristie commented Aug 24, 2015

Before and after screenshots would probably be helpful.

@d0ugal
Copy link
Member

@d0ugal 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

@d0ugal d0ugal added the Enhancement label Aug 24, 2015
@facelessuser
Copy link
Contributor

@facelessuser facelessuser commented Aug 24, 2015

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 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

@jimporter jimporter commented Aug 24, 2015

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

@jimporter jimporter commented Aug 24, 2015

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

colors

@d0ugal
Copy link
Member

@d0ugal d0ugal commented Aug 25, 2015

Yup, that does look better to me

@trel
Copy link
Contributor

@trel trel commented Aug 25, 2015

agreed.

@robodude666
Copy link

@robodude666 robodude666 commented Aug 27, 2015

👍

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

@jimporter jimporter commented Aug 27, 2015

@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 pushed a commit to jimporter/mkdocs that referenced this issue Dec 12, 2015
jimporter pushed a commit to jimporter/mkdocs that referenced this issue Jan 21, 2016
jimporter pushed a commit to jimporter/mkdocs that referenced this issue Feb 20, 2016
@d0ugal d0ugal closed this in #772 Feb 25, 2016
d0ugal added a commit that referenced this issue Feb 25, 2016
@jimporter
Copy link
Contributor Author

@jimporter jimporter commented Feb 26, 2016

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
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
8 participants
You can’t perform that action at this time.