Create an Asciidoctor stylesheet for HTML output about asciidoctor HOT 21 CLOSED

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

from asciidoctor.

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.

from asciidoctor.

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.

• http://jsfiddle.net/mojavelinux/XdLk8/embedded/result/ (applied to the Arquillian Getting Started Guide)
• http://jsfiddle.net/mojavelinux/6sxgj/embedded/result/ (applied to the Arquillian Persistence Extension Manual)
• http://jsfiddle.net/mojavelinux/VQWau/embedded/result/ (applied to Fixing Mistakes from teach.github.com)

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.

• http://jsfiddle.net/mojavelinux/6dkGZ/embedded/result/
• http://jsfiddle.net/mojavelinux/vTF7d/embedded/result/

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

• http://jsfiddle.net/mojavelinux/YMtDU/embedded/result/
  (the style for the literal blocks hasn't been ported over yet)

I'm interested to see this evolve!

from asciidoctor.

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.

from asciidoctor.

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

from asciidoctor.

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

from asciidoctor.

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

from asciidoctor.

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

from asciidoctor.

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 [email protected] 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

from asciidoctor.

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

On Fri, Feb 1, 2013 at 10:07 AM, Jason Porter [email protected]:

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 [email protected]
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.

from asciidoctor.

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.

from asciidoctor.

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 [email protected]:

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

from asciidoctor.

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!

from asciidoctor.

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.

from asciidoctor.

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.

from asciidoctor.

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

from asciidoctor.

Excellent. I'll get moving on that soon.

from asciidoctor.

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

from asciidoctor.

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.

from asciidoctor.

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 [email protected] 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

from asciidoctor.

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

from asciidoctor.