Question: instructions to add new styles

[cmoulliard]

Could you please document and add the instructions needed to contribute to your project in order to ?

• Add a new style
• Move existing styles (https://github.com/asciidoctor/asciidoctor-stylesheet-factory)
• Is it possible that we use less or sass to generate the css files
• Can we release the styles for a specific version of Asciidoctor

[dohliam]

To add a new style:

• Just include include the corresponding css file to the css folder with all the other styles.
• Optional: add a screenshot to the screenshots directory for inclusion in the showcase
• Optional: add the new style to the list in the readme.

If you are starting from scratch on a new style you can use the template.css file as a framework. It includes most of the elements that might be interesting to tweak in asciidoctor output. Just remove anything you don't want to change.

Moving existing styles:

• It might be possible to compile the stylesheet factory themes or import them directly from e.g. here or here. I imagine this would require some tweaking but it might work.

Using less/sass:

• I think the idea was to avoid using CSS preprocessors to keep things as simple and transparent as possible. Given the minimalistic nature of most of the themes (mostly just a few lines), using a preprocessor seems like it might be overkill.

Releasing styles for specific versions of Asciidoctor:

• Can you clarify this? Are you worried about backwards compatibility between the themes and a particular version of Asciidoctor? Have there been breaking changes in Asciidoctor that would significantly affect the way the themes work? Or are there other issues?

[cmoulliard]

Can you clarify this? Are you worried about backwards compatibility between the themes and a particular version of Asciidoctor? Have there been breaking changes in Asciidoctor that would significantly affect the way the themes work? Or are there other issues?

I would like to be sure that the styles suggested here will work with by Asciidoctor v1.5.4. If this is the case, then you can release a version of your styles which are compatible to that version. That will allow third party projects to download this release to propose the styles locally

[cmoulliard]

Where this asciidoc.css file is coming from ("https://github.com/darshandsoni/asciidoctor-skins/blob/gh-pages/css/asciidoctor.css"). Asciidoctor project ? Is it your own asciidoctor css file ?

[dohliam]

Where this asciidoc.css file is coming from ("https://github.com/darshandsoni/asciidoctor-skins/blob/gh-pages/css/asciidoctor.css"). Asciidoctor project ? Is it your own asciidoctor css file ?

@darshandsoni will need to confirm this, but I believe it is the same as (or slightly modified from) the default Asciidoctor css. It should be similar to e.g. this one.

[darshandsoni]

Thanks for jumping on there @dohliam!
You are correct on that last point there, it is the same as the default Asciidoctor css.

Now that you mention it @cmoulliard I realise that this may bring about very minor compatibility issues as asciidoctor gets updated. Because it is a static css file on this repo, it doesn't get the latest from the asciidoctor itself automatically.
Having said that, when asciidoctor gets updated it rarely makes major changes to the default stylesheet. The devs of asciidoctor focus more on it's functions and not the skins, so they don't mess around with the css too much. Moreover, I expect that an update to their default css would be additive and not subtractive so if anything, there'll just be a lag with features, which can be patched quickly by filing an issue or PR.

To quickly answer your concerns about v1.5.4, it seems to be working fine when I tested it. I may not have tried all the feautures so give it a go and feel free to flag any issues here!

[cmoulliard]

It could be interesting that your project, like asciidoctor-stylesheet-factory, asciidoctor.js use the same asciidoctor file. If we join our efforts to achieve this goal, that should be already a great step.

• Asciidoctor (Ruby Project) & asciidoctor.js both use this file : https://github.com/asciidoctor/asciidoctor/blob/master/lib/asciidoctor/stylesheets.rb#L26

Remark : Currently, I have no idea where this file (asciidoctor-default.css) has been created & is maintained

• The asciidoctor-stylesheets-factory project generates an asciidoctor-css file using this scss template : https://github.com/asciidoctor/asciidoctor-stylesheet-factory/blob/master/sass/asciidoctor.scss

Is the css file generated the same as packaged within your project or asciidoctor (ruby, js) ?