Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/darshandsoni/asciidoctor-skins

Control how your asciidoctor powered documentation looks
https://github.com/darshandsoni/asciidoctor-skins

asciidoctor collection css theme

Last synced: 13 days ago
JSON representation

Control how your asciidoctor powered documentation looks

Awesome Lists containing this project

README 

        
// Settings:

:experimental:

ifndef::env-github[:icons: font]

ifdef::env-github,env-browser[]

endif::[]

ifdef::env-github[]

:caution-caption: :fire:

:important-caption: :exclamation:

:note-caption: :paperclip:

:tip-caption: :bulb:

:warning-caption: :warning:

endif::[]



= asciidoctor-skins: CSS stylesheets for asciidoctor



Markdown is superbly simple. Perfect for writing quick notes and pages with a basic structure. Asciidoctor is superbly sophisticated. Where markdown fails, asciidoc/asciidoctor allows you to document things with ease, fine grain control and a civilised demeanor, worlds away from hair wrenching word processors.



Asciidoctor comes with a very clean default stylesheet that saves users from spending time formatting their documents. This repository is for users who would like some other style choices, without having to rewrite stylesheets from scratch. All stylesheets in here pull in asciidoctor's defaults first and then apply custom styles to a few elements.



== Usage

If you have no idea what asciidoctor is, check out their fabulous project https://asciidoctor.org/[here].



IMPORTANT: Once you've got an `.adoc` document going, download the link:css/asciidoctor.css[asciidoctor.css] file and a css skin file of your choice into your project directory.



1. In your `.adoc` file, add the following line: `:stylesheet: Your_Chosen_Stylesheet.css`

2. Render your html file by running `asciidoctor sample.adoc`

3. _Et voilà!_ Your beautiful web page based document is rendered.



== Demo



You can preview all of the stylesheets in the https://darshandsoni.com/asciidoctor-skins[online demo].



To change the displayed stylesheet, just add the name of the CSS file after a `?` character at the end of the URL. For example, to preview the material stylsheet, just add `?material`.



== Custom preview



You can now add a JS switcher to any document to quickly preview the contents rendered with any of the available asciidoctor skins. Just add the following line to the `` section of any asciidoctor-generated HTML page:



    



== Skins



Note: To preview all of them, visit the https://darshandsoni.com/asciidoctor-skins/screenshots/[screenshots] page.



Available stylesheets:



* https://darshandsoni.com/asciidoctor-skins/?asciidoctor[default asciidoctor stylesheet]

* https://darshandsoni.com/asciidoctor-skins/?clean[clean]

* https://darshandsoni.com/asciidoctor-skins/?dark[dark]

* https://darshandsoni.com/asciidoctor-skins/?fedora[fedora]

* https://darshandsoni.com/asciidoctor-skins/?gazette[gazette]

* https://darshandsoni.com/asciidoctor-skins/?italian-pop[italian-pop]

* https://darshandsoni.com/asciidoctor-skins/?medium[medium]

* https://darshandsoni.com/asciidoctor-skins/?monospace[monospace]

* https://darshandsoni.com/asciidoctor-skins/?notebook[notebook]

* https://darshandsoni.com/asciidoctor-skins/?plain[plain]

* https://darshandsoni.com/asciidoctor-skins/?template[template]

* https://darshandsoni.com/asciidoctor-skins/?tufte[tufte]

* https://darshandsoni.com/asciidoctor-skins/?ubuntu[ubuntu]



NOTE: the https://darshandsoni.com/asciidoctor-skins/?template[template] skin is specifically designed as an aid for theming experiments, to make it easier to see the sections of the document affected by different CSS classes.



=== Additional themes



* https://darshandsoni.com/asciidoctor-skins/?asciidoc-classic[Asciidoc Classic] - The original default http://asciidoc.org/[AsciiDoc] stylesheet by Stuart Rackham. Licensed under https://github.com/asciidoc/asciidoc/blob/master/COPYING[GPLv2].



=== Collections



**Adoc skins**, based on the official https://themes.asciidoctor.org/preview/[Asciidoctor themes site] by the Asciidoctor project (https://github.com/asciidoctor/asciidoctor-stylesheet-factory/blob/master/LICENSE[MIT]):



* https://darshandsoni.com/asciidoctor-skins/?adoc-colony.css[Colony]

* https://darshandsoni.com/asciidoctor-skins/?adoc-foundation-lime.css[Lime]

* https://darshandsoni.com/asciidoctor-skins/?adoc-foundation-potion.css[Potion]

* https://darshandsoni.com/asciidoctor-skins/?adoc-foundation.css[Foundation]

* https://darshandsoni.com/asciidoctor-skins/?adoc-github.css[Github]

* https://darshandsoni.com/asciidoctor-skins/?adoc-golo.css[Golo]

* https://darshandsoni.com/asciidoctor-skins/?adoc-iconic.css[Iconic]

* https://darshandsoni.com/asciidoctor-skins/?adoc-maker.css[Maker]

* https://darshandsoni.com/asciidoctor-skins/?adoc-readthedocs.css[Readthedocs]

* https://darshandsoni.com/asciidoctor-skins/?adoc-riak.css[Riak]

* https://darshandsoni.com/asciidoctor-skins/?adoc-rocket-panda.css[Panda]

* https://darshandsoni.com/asciidoctor-skins/?adoc-rubygems.css[Rubygems]



**Bootswatch skins**, based on https://github.com/thomaspark/bootswatch/[bootswatch] by @thomaspark (https://github.com/thomaspark/bootswatch/blob/gh-pages/LICENSE[MIT]):



* https://bootswatch.com/cerulean/[Cerulean]

* https://bootswatch.com/cosmo/[Cosmo]

* https://bootswatch.com/cyborg/[Cyborg]

* https://bootswatch.com/darkly/[Darkly]

* https://bootswatch.com/flatly/[Flatly]

* https://bootswatch.com/journal/[Journal]

* https://bootswatch.com/lumen/[Lumen]

* https://bootswatch.com/paper/[Paper]

* https://bootswatch.com/readable/[Readable]

* https://bootswatch.com/sandstone/[Sandstone]

* https://bootswatch.com/slate/[Slate]

* https://bootswatch.com/spacelab/[Spacelab]

* https://bootswatch.com/superhero/[Superhero]

* https://bootswatch.com/yeti/[Yeti]



**Material skins**, by @darshandsoni:



* https://darshandsoni.com/asciidoctor-skins/?material-amber[material amber]

* https://darshandsoni.com/asciidoctor-skins/?material-blue[material blue]

* https://darshandsoni.com/asciidoctor-skins/?material-brown[material brown]

* https://darshandsoni.com/asciidoctor-skins/?material-green[material green]

* https://darshandsoni.com/asciidoctor-skins/?material-grey[material grey]

* https://darshandsoni.com/asciidoctor-skins/?material-orange[material orange]

* https://darshandsoni.com/asciidoctor-skins/?material-pink[material pink]

* https://darshandsoni.com/asciidoctor-skins/?material-purple[material purple]

* https://darshandsoni.com/asciidoctor-skins/?material-red[material red]

* https://darshandsoni.com/asciidoctor-skins/?material-teal[material teal]



== Bookmarklet



You can quickly and easily test out how different themes look with a given document using the asciidoctor-skins bookmarklet. This will add a dropdown menu at the top of the page with all the different available themes. Just paste the following code into your address bar to create a CSS switcher for any Asciidoctor-generated document:



[source,javascript]

----

javascript:(function()%7Bvar%20body%20%3D%20document.getElementsByTagName('body')%5B0%5D%3Bscript%20%3D%20document.createElement('script')%3Bscript.type%3D%20'text%2Fjavascript'%3Bscript.src%3D%20'https%3A%2F%2Fdarshandsoni.com%2Fasciidoctor-skins%2Fswitcher.js'%3Bbody.appendChild(script)%7D)()

----



Alternatively, just drag the link on the https://darshandsoni.com/asciidoctor-skins/#_bookmarklet[demo page] to your browser's bookmark bar.



Boomarklet generated by the https://mrcoles.com/bookmarklet/[Bookmarklet Creator]. Thanks to https://github.com/mrcoles/markdown-css[markdown-css] for the idea!



== Contribution



The purpose of this project is to allow asciidoc/asciidoctor users greater flexibility when it comes to customizing the look and feel of their documentation. Apart from the available stylesheets, you are welcome to build your own. If you think the world could use it, submit a pull request and it will be featured too!

You can either edit template.css (which has most elements listed), or create your own stylesheets from scratch.



=== Licence Agreement



By contributing changes to this repository, you agree to license your contributions under the https://github.com/darshandsoni/asciidoctor-skins/blob/gh-pages/LICENSE[MIT license]. This ensures your contributions have the same license as the project and that the community is free to use your contributions. You also assert that you are the original author of the work that you are contributing unless otherwise stated.



== Credits



* Demo based on https://github.com/cbracco/html5-test-page[html5-test-page] by @cbracco

* JS switcher based on https://github.com/dohliam/dropin-minimal-css[dropin-minimal-css]



== License



MIT.