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

Create an Asciidoctor stylesheet for HTML output #76

Closed
mojavelinux opened this issue Jan 14, 2013 · 21 comments
Closed

Create an Asciidoctor stylesheet for HTML output #76

mojavelinux opened this issue Jan 14, 2013 · 21 comments
Assignees
Labels
Milestone

Comments

@mojavelinux
Copy link
Member

@mojavelinux mojavelinux commented Jan 14, 2013

To demonstrate compliance with AsciiDoc, we've been testing the rendered HTML output against the default AsciiDoc stylesheet. However, I'll be the first to admit that the first time I saw that theme, I dismissed AsciiDoc for being stuck in the 90s.

Let's change that perception.

Asciidoctor should provide a professional, modern stylesheet for HTML output out of the box...something we can call our own.

We can draw inspiration from readthedocs.org, which recently took a fresh approach to a stylesheet for HTML-based documentation. We could also consider the look and feel of GitHub, Bootstrap, Foundation 3 and others.

Ideally, the stylesheet would coordinate with the Asciidoctor logo, issue #48.

@mojavelinux

This comment has been minimized.

Copy link
Member Author

@mojavelinux mojavelinux commented Jan 22, 2013

I think Ryan Tomakyo puts it best:

The default theme included in AsciiDoc is functional but is somewhat lacking in typographic consistencies.
It is also quite blue.

His theme repository (https://github.com/rtomayko/adoc-themes) could be used as raw material as well, unless something like Bootstrap or Foundation provides all we need.

I'd like to see FontAwesome used to replace the need for linked admonition icons by default too.

@mojavelinux

This comment has been minimized.

Copy link
Member Author

@mojavelinux mojavelinux commented Jan 28, 2013

I've messed around with some default styles for Asciidoctor that will bring a fresh look to AsciiDoc. I stuck them up on jsfiddle so that we can collaborate. If you can see a way to improve them, please do!

The first is an original theme built on top of the bare.css file in the adocs-theme repo by Ryan Tomayko.

I also played around with a theme based on the Fedora documentation. It's much more institutional looking, but perhaps that's to some people's liking.

I also tweaked Ryan's handbookish stylesheet which is based on the FreeBSD documentation:

I'm interested to see this evolve!

@graphitefriction

This comment has been minimized.

Copy link
Member

@graphitefriction graphitefriction commented Jan 30, 2013

Comments for the default theme.
Theme should be clean and modern but lean slightly toward a traditional publishing look and feel (per conversation with @mojavelinux on 1/29/2013).

author: increase font size
revnumber and date: style the same as author, put on same line as author with | or dot thingy to separate
More white space between author and toctitle

toctitle: Increase font size, remove bold, change font to serif and/or change to the same styling as h2
Remove underlining from beneath toc list items (but keep the link color)
Slightly increase line spacing between major toc sections but NOT between an major toc section and its subsections
Maybe a hrule beneath the toc to separate toc from preamble text or do some sort of p(lead) styling on preamble text?

Reduce line spacing between a 1st level bullet and its 2nd level bullets
Reduce line spacing between 2nd level bullets
Reduce line spacing between 3rd level bullets
Slightly reduce spacing between section h2 (and h4 (h3 spacing looks okay) and sectionbody title (and sectionbody text below h2 in following sections)
Increase font size of sectionbody title, remove bold
Possibly increase spacing between title and content below it
listingblock: looks good with the exception that it is totally unresponsive/no wrapping if window size shrinks and runs outside graphic behind it. The mixed responsiveness will need to be address at some point.
literalblock: maybe increase font size....

Is tableblock frame-topbot grid-all class supposed to be a default template style?

Why is the ordered list class called "arabic"?

dt: either remove bold or make a shade of gray
h4: looks like font size is smaller than dt, make h4 font size larger

Right bottom corner of table in persistence doc rendering doesn't look rounded by top corners do? (or are my eyeballs just wonky?)

icons broken in persistence doc rendering

footnote number in body of doc: no brackets around it
footnotes at bottom of page: reduce font size or lighten color

@LightGuard

This comment has been minimized.

Copy link
Member

@LightGuard LightGuard commented Jan 30, 2013

I may be in the minority here, but I like http://jsfiddle.net/mojavelinux/6dkGZ/embedded/result/ the best. The extra whitespace in code samples, the rounded corners for code really add a nice polish to I think. Some more colors in the code sections would be nice, but that's easy to do. Also using a sans-serif font is a nice touch.

@graphitefriction

This comment has been minimized.

Copy link
Member

@graphitefriction graphitefriction commented Jan 30, 2013

@LightGuard I think the plan (but I could be really wrong here) is to have multiple stylesheets bundled/compatible/pre-composed (whatever the right techno-jargon is) with Asciidoctor. The one you mentioned above and the BSD themed one are getting my first round of eyeballing right now. Then I plan to run back through all of them after the initial edits and tweak some more

And I agree with the aspects you like in the stylesheet.

@mojavelinux

This comment has been minimized.

Copy link
Member Author

@mojavelinux mojavelinux commented Feb 1, 2013

Here's the next round, now based on Foundation!

http://jsfiddle.net/mojavelinux/vnhAq/embedded/result/

I think you'll find that I hit all the issues that you mentioned (even some I didn't think I could fix at first).

@mojavelinux

This comment has been minimized.

Copy link
Member Author

@mojavelinux mojavelinux commented Feb 1, 2013

Oh yeah, it's using Font Awesome for the admonition icons too. 😎

@mojavelinux

This comment has been minimized.

Copy link
Member Author

@mojavelinux mojavelinux commented Feb 1, 2013

If you like the colors on the Foundation project website, you'll like this one:

http://jsfiddle.net/mojavelinux/MxKXw/embedded/result/

(All I did to get that was change some variables in the Sass stylesheet I created...I'll create a repo for it tomorrow).

@LightGuard

This comment has been minimized.

Copy link
Member

@LightGuard LightGuard commented Feb 1, 2013

Both look good, though for me, they both have subtle issues. I think I like
http://jsfiddle.net/mojavelinux/vnhAq/embedded/result/ the best, but maybe
a little too much red. The color difference on my monitor between the yield
and the exclaim are too close, they look like the same color. For the
yield, I'd stay with a yellow or an orange. At least here in the US those
two correspond to traffic colors so you associate them differently. A red
yield sign throws you off and I'm not sure how to respond to that.

With http://jsfiddle.net/mojavelinux/MxKXw/embedded/result/ I think the
black is too overpowering. Again with the yield sign, a black yield doesn't
do anything for me, I almost gloss right over it. The blues for the links
here are probably too light for a white background. I think a font size
between the two would be perfect. The font here seemed too small and the
other was just a titch too large imo.

I also toyed a bit with adding some drop shadow to the images and code
samples, really helps them pop out, but not a lot: box-shadow: 2px 2px 2px
gray;

On Fri, Feb 1, 2013 at 3:48 AM, Dan Allen notifications@github.com wrote:

If you like the colors on the Foundation project website, you'll like this
one:

http://jsfiddle.net/mojavelinux/MxKXw/embedded/result/

(All I did to get that was change some variables in the Sass stylesheet I
created...I'll create a repo for it tomorrow).


Reply to this email directly or view it on GitHubhttps://github.com//issues/76#issuecomment-12989242.

Jason Porter
http://en.gravatar.com/lightguardjp

@erebor

This comment has been minimized.

Copy link
Member

@erebor erebor commented Feb 1, 2013

FWIW, I like the look of the first one (vnhAq) better as well.

On Fri, Feb 1, 2013 at 10:07 AM, Jason Porter notifications@github.comwrote:

Both look good, though for me, they both have subtle issues. I think I
like
http://jsfiddle.net/mojavelinux/vnhAq/embedded/result/ the best, but
maybe
a little too much red. The color difference on my monitor between the
yield
and the exclaim are too close, they look like the same color. For the
yield, I'd stay with a yellow or an orange. At least here in the US those
two correspond to traffic colors so you associate them differently. A red
yield sign throws you off and I'm not sure how to respond to that.

With http://jsfiddle.net/mojavelinux/MxKXw/embedded/result/ I think the
black is too overpowering. Again with the yield sign, a black yield
doesn't
do anything for me, I almost gloss right over it. The blues for the links
here are probably too light for a white background. I think a font size
between the two would be perfect. The font here seemed too small and the
other was just a titch too large imo.

I also toyed a bit with adding some drop shadow to the images and code
samples, really helps them pop out, but not a lot: box-shadow: 2px 2px 2px
gray;

On Fri, Feb 1, 2013 at 3:48 AM, Dan Allen notifications@github.com
wrote:

If you like the colors on the Foundation project website, you'll like
this
one:

http://jsfiddle.net/mojavelinux/MxKXw/embedded/result/

(All I did to get that was change some variables in the Sass stylesheet
I
created...I'll create a repo for it tomorrow).


Reply to this email directly or view it on GitHub<
https://github.com/asciidoctor/asciidoctor/issues/76#issuecomment-12989242>.

Jason Porter
http://en.gravatar.com/lightguardjp


Reply to this email directly or view it on GitHubhttps://github.com//issues/76#issuecomment-13000519.

@jm

This comment has been minimized.

Copy link
Member

@jm jm commented Feb 1, 2013

I like the direction of these, but would you like me to wrangle a GitHub designer to help polish it up/offer input? I'm sure one of them would be glad to spend a few hours on it.

@LightGuard

This comment has been minimized.

Copy link
Member

@LightGuard LightGuard commented Feb 1, 2013

I think the more input we have the better. Obviously it'll be very hard to
please everyone, but more input couldn't hurt.

On Fri, Feb 1, 2013 at 9:45 AM, Jeremy McAnally notifications@github.comwrote:

I like the direction of these, but would you like me to wrangle a GitHub
designer to help polish it up/offer input? I'm sure one of them would be
glad to spend a few hours on it.


Reply to this email directly or view it on GitHubhttps://github.com//issues/76#issuecomment-13002361.

Jason Porter
http://en.gravatar.com/lightguardjp

@graphitefriction

This comment has been minimized.

Copy link
Member

@graphitefriction graphitefriction commented Feb 1, 2013

I would eagerly welcome and think it would be absolutely! awesome! if a GitHub designer could offer some input/guidance or polish. Thank you, Jeremy!

@cameronmcefee

This comment has been minimized.

Copy link

@cameronmcefee cameronmcefee commented Feb 1, 2013

Of the options listed here, I think http://jsfiddle.net/mojavelinux/vnhAq/embedded/result/ is my preference. It's pretty great as is. The only things that really stand out to me is the massive <h2> headings. I'd probably go with something a little smaller like 34px rather than 42px. Also maybe using bold numerals for the footnotes? That's kind of just nitpicky really. Here's what these changes would look like: http://jsfiddle.net/vnhAq/5/embedded/result/

Not sure if this is a concern, but there doesn't appear to be any kind of max width on the images. This means huge images could jump out of the layout.

@mojavelinux

This comment has been minimized.

Copy link
Member Author

@mojavelinux mojavelinux commented Feb 2, 2013

Thanks for taking the time to review the styles @cameronmcefee! What an honor.

I'll definitely incorporate the suggestions you made into the stylesheet. Also, your acknowledgement that we're on the right track really gives me a lot of confidence.

I look forward to the styles evolving over time, so if you have any other suggestions in the future, don't hesitate to chime in.

@dobermai

This comment has been minimized.

Copy link

@dobermai dobermai commented Feb 11, 2013

I like the last one which @cameronmcefee proposed the most ( http://jsfiddle.net/vnhAq/5/embedded/result/ ). Looks very modern and very elegant. Just applied the style to a test document and I really like it :)

@mojavelinux

This comment has been minimized.

Copy link
Member Author

@mojavelinux mojavelinux commented Feb 12, 2013

Excellent. I'll get moving on that soon.

@paulrayner

This comment has been minimized.

Copy link
Member

@paulrayner paulrayner commented Mar 2, 2013

+1 on @cameronmcefee's contribution. Very nice! One thing I noticed is the green pushpin in section 2 is missing the nice dropshadow that all the other icons have.

@mojavelinux

This comment has been minimized.

Copy link
Member Author

@mojavelinux mojavelinux commented Apr 2, 2013

I finally got around to creating the stylesheet factory project, which is capable of producing the default stylesheet we want to bundle w/ Asciidoctor (thanks to Sass, Compass and Foundation 4).

https://github.com/asciidoctor/asciidoctor-stylesheet-factory

Here's the default Asciidoctor stylesheet candidate:

https://github.com/asciidoctor/asciidoctor-stylesheet-factory/blob/master/sass/asciidoctor.scss

My plan is to tag the repository at the time we take the generated stylesheet and copy it into Asciidoctor. That way, we can track the source. Keeping the two projects separate allows for easier collaboration on the styles.

@LightGuard

This comment has been minimized.

Copy link
Member

@LightGuard LightGuard commented Apr 2, 2013

Guess I'll have to download it and apply a sheet to see what it looks like.

On Tue, Apr 2, 2013 at 4:04 PM, Dan Allen notifications@github.com wrote:

I finally got around to creating the stylesheet factory project, which is
capable of producing the default stylesheet we want to bundle w/
Asciidoctor (thanks to Sass, Compass and Foundation 4).

https://github.com/asciidoctor/asciidoctor-stylesheet-factory

Here's the default Asciidoctor stylesheet candidate:

https://github.com/asciidoctor/asciidoctor-stylesheet-factory/blob/master/sass/asciidoctor.scss

My plan is to tag the repository at the time we take the generated
stylesheet and copy it into Asciidoctor. That way, we can track the source.
Keeping the two projects separate allows for easier collaboration on the
styles.


Reply to this email directly or view it on GitHubhttps://github.com//issues/76#issuecomment-15805780
.

Jason Porter
http://en.gravatar.com/lightguardjp

@mojavelinux

This comment has been minimized.

Copy link
Member Author

@mojavelinux mojavelinux commented Apr 2, 2013

Yep, for now I don't have a demo setup. I plan to do that, perhaps in the
gh-pages on the same repo.

@ghost ghost assigned mojavelinux Apr 15, 2013
mojavelinux added a commit that referenced this issue Apr 25, 2013
resolves #76 add a default stylesheet
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
8 participants
You can’t perform that action at this time.