Enable the use of different stylesheets (including custom)

[gdanov]

I would like to be able to use more than one template and if possible be able to specify my own

[mojavelinux]

By template, do you mean stylesheet (aka theme?).

[gdanov]

yes I mean stylesheet

[mojavelinux]

Then I agree!

To provide built-in stylesheets, I think we should address the other issue of making the themes from the Asciidoctor stylesheet factory available via Bower. Otherwise, we are copying stylesheets all over the place.

[clojens]

Looks like I walked in at the right time. @mojavelinux whats the idea with the bower packages? Provide a publishing template .json for the people who develop with it, to have them push on their own behalf to bower? How does one group related (family) of bower packages anyway? I haven't seen a tags field or such... uses naming convention? I assume you wouldn't want to go the way of 'central registry' (aka package manager) for something like styles right ...?

[mojavelinux]

@clojens hopefully, the time is still right :) Sorry for the delay.

So we'll need to put the Bower integration into the https://github.com/asciidoctor/asciidoctor-stylesheet-factory repository. Then, the Atom plugin can consume it.

We'd implement it just like other CSS frameworks are implemented, such as Bootstrap. Here's an example:

https://github.com/twbs/bootstrap/blob/master/bower.json

We'll probably want to go with the strategy that the generated files are published into a tag (otherwise, master gets to be a mess). Of course, that means we need to start tagging. At first, I'm not worried about making the stylesheets super pretty, just that we have them available in Bower. Then we can start to clean them up. This also solves the problem of how to ship images. I think it's a great strategy.

Here's the issue to follow-up on:

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

I'd say that this issue depends on that issue.

[mojavelinux]

Note that fixing https://github.com/asciidoctor/asciidoctor-stylesheet-factory/issues/15 also simplifies stylesheet selection in any tool that uses Asciidoctor or Asciidoctor.js, including the Atom plugin, the Chrome extension, the Firefox extension and the Brackets extension. This is going to be big :)

[meyerweb]

Tossing in my +1 for this feature. I would find it incredibly useful to be able to use stylesheets that correspond to what I’m doing in ASCIIdoc—one theme for coding, another for blogging, another for personal writing, and so on.

It would also be really great if the editor remembered which theme a file uses, so when you load it up, the preview is already set properly.

[mojavelinux]

@meyerweb Thanks for citing these use cases. That helps understand the motivation for this improvement and gives us a good way to explain it once we add it.

I especially like the idea of remembering the theme file used for a given document. Great suggestion! :+1: I'd like to see this in the Chrome Extension as well once we have per-file themes.

I'm going to move the stylesheet factory refactoring up in my priority list so we can get moving on this feature.

[magi42]

Could we have more detailed instructions for how to configure a stylesheet in Atom settings? The Bower configuration was a bit beyond me.

[mojavelinux]

@magi42 My explanation was a proposal, not something that currently works. Development is still needed here.

[KangarooCreativeTeam]

I'm just writing to +1 this.

I always work in a dark-ish room, with dark themes. I HATE that the preview is a blinding white! MY EYES! ARRRRG! >_<

RELEVANT: Last week, Atom 1.1 was released, & it's Markdown preview features using the same theme the rest of the editor is currently configured to use (with the option to use the default white Github theme). [Press release > "Themed Markdown Preview"]

I think the best solution is to default to using the same theme as the editor (with the option to specify a custom stylesheet coming down the line in future when ready...). I think it'll look the best / most consistent at all times (whatever theme I've currently chosen to use in the editor, from all my favourites).

Thank you :)

--HEAD KANGAROO KangarooCreativeTeam.com

[nicorikken]

I agree with @KangarooCreativeTeam The Markdown preview neatly conforms to the theme. As the Atom themes already provide a variety of colors and fonts, in particular the ones used to style Markdown, I would opt to use a style-sheet that uses these theme-based CSS stylesheets in rendering. The (github flavored) Markdown package has 2 built-in stylesheets: one adopting to the theme style, one mimicking the GitHub online style. The preference can be set in the package configuration. I can see a similar setup for the AsciiDoc preview, where there are 2 built-in themes: one showing the default Asciidoctor preview, one rendering according to the theme CSS.

I haven't looked at the rendering internals, but I would assume 2 themes can be statically linked throughout the package if necessary. Than it would mainly require someone to create the style relating to theme-based styles.

[mojavelinux]

Correct, we need to develop a new theme for Asciidoctor that ties into the (LESS) theme variables. One approach is to start from scratch, a clean room implementation. Another approach is to use the asciidoctor-stylesheet-factory to produce a LESS stylesheet that has references to the theme variables.

Creating a theme for Asciidoctor is not a small task (but it's not impossible either). Like with the grammar, there are a lot of components to deal with.

The benefit of a clean room implementation for the Atom preview is that the stylesheet only has to focus on the content part (the embeddable HTML). A lot of the default stylesheet deals with a) a CSS reset across browsers, which we don't need in this case and b) styles for the framing around the content.

[nicorikken]

Wouldn't changing fonts and colors be sufficient?

[mojavelinux]

Just changing the fonts and colors is something that is (mostly) accomplished using the stylesheet factory.

I still think that a clean implementation is the most ideal path. There's a lot of unnecessary CSS that the default stylesheet provides in this context, and it's a bit roundabout to use Sass to build LESS output. Taking it one step at a time, you'd probably be able to make a decent "native" stylesheet in a few days time.

[mojavelinux]

It also allows us to skate around the open issue that the stylesheet factory still can't produce a stylesheet for the embeddable HTML (see https://github.com/asciidoctor/asciidoctor-stylesheet-factory/issues/18).

[nicorikken]

:+1:

[nicorikken]

I cannot get started with development because of the atom-space-pen-views not being included. Downloading and linking the repo didn't work either. So at this very moment I cannot even start working on this issue. Until somebody fixes the development track, I will hold off spending further time on this issue. 😢

[mojavelinux]

@Mogztter or @anthonny, do you know what's going on with atom-space-pen-views? Have you been able to get past it in your local checkout?

[ggrossetie]

No, everything is working fine on my machine. I'm using apm command line to hack on Atom.

[nicorikken]

I forgot to call apm install, now it is working just fine, and I've already made my first stylesheet modifications. I'd like to transfer the sass (scss) components stylesheets from the stylesheet-factory to less, to have a good basis for supporting all features. I found this helpful overview http://www.nicoespeon.com/en/2013/06/convert-sass-project-into-less/

[nicorikken]

@mojavelinux How would you consider the option to migrate the stylesheet factory to LESS (which enables side-by-side comparisons on the same theme styles), and then create a separate stylesheet which bases itself on the syntax styles?

[nicorikken]

@mojavelinux @ldez I did some early prototyping on a LESS version of the stylesheet factory. Both syntaxes are quite new to me, so plenty of difficulties to port it. Especially the components/_asciidoc.scss is a pain in the ass, because of the use of logic, iterators, and inheritance. I need a better understanding of both styling language to perform a succesful port. Porting the other files is relatively straightforward. Another issue is the inclusion of foundation/components/* and compass/css3/* which are both SCSS based. It seems functions are used (like emCalc), and so I cannot simply include rendered CSS files. Maybe (hopefully) I will be able to make a rendered import of the components/_asciidoc.scss and settings/_defaults.scss at least for now. It seems the current inheritance model is something like:

└─┬ asciidoctor
  ├── components/awesome-icons
  ├─┬ components/asciidoc
  │ ├── foundation/components/inline-lists
  │ ├── foundation/components/tables
  │ ├── foundation/components/panels
  │ ├── foundation/components/type
  │ └── foundation/components/grid
  ├─┬ settings/asciidoctor
  │ └─┬ settings/defaults
  │   ├── compass/css3/box-shadow
  │   ├── foundation/components/global
  │   └── normalize
  └── components/print

What do you think? Hybrid between rendered and LESS, go for a clean-room implementation as suggested earlier, or go LESS all the way?

[ldez]

Sass is more flexible et more powerful than LESS.

We don't need to convert SASS to LESS, we can process the SASS.

[nicorikken]

@ldez How would you create a solution for parsing SASS rather then LESS? Using Grunt maybe? The main reason for going with LESS is to integrate with the syntax definitions from the editor. I read somewhere that Atom only supported LESS natively, not SASS.

[nicorikken]

@ldez can you give some hints for a solution to compile the SASS on the spot, incorporating the syntax styles?

[nicorikken]

@ldez going by http://stackoverflow.com/questions/4436643/is-there-a-sass-js-something-like-less-js maybe something like sass.js?

[ldez]

nope, I thinking about Node-sass

[mojavelinux]

Sorry for the delay. I'll chime in later today.

[nicorikken]

Just to report back: after the node suggestion, I did some initial stuff, but I'm lacking the Javascript skills to pull this off. Maybe I'll give it another go someday.