<commit_before>= Asciidoctor Bootstrap Themes
<NAME>
:idprefix:
:idseparator: -
:sources: https://github.com/nerk/asciidoctor-bs-themes
:license: https://github.com/nerk/asciidoctor-bs-themes/blob/master/LICENSE

Create style sheets to theme AsciiDoc HTML output using http://www.getbootstrap.com[Bootstrap] and free themes from http://bootswatch.com/[Bootswatch].

== Introduction

The AsciiDoc markup processor http://asciidoctor.org[Asciidoctor] already includes a good set of CSS style sheets based on http://foundation.zurb.com[Foundation].
However, if you would like to use themes based on Twitter's http://getbootstrap.com[Bootstrap] instead, this project is for you.

Bootstrap is using the http://www.lesscss.org/[Less] preprocessor to compile +.less+ style sheets into CSS files. Most of Bootstrap's
styling like sizes, fonts, and colors is defined in a file named +variables.less+. By modifying the contents of this 
file or overriding the values of the defined variables, you can create your own Bootstrap themes.

A popular site with free Bootstrap themes is http://bootswatch.com/[Bootswatch]. Fortunately, rather than downloading the final
CSS files, you can also just grab the +variables.less+ file for almost any of the themes.

This project uses the Bootstrap +.less+ sources, +variables.less+ files from Bootswatch, and additional 
styling specific to AsciiDoc to create AsciiDoc-enhanced versions of the Bootswatch themes. The 
AsciiDoc specific styling is based on Dan Allen's Asciidoctor SASS style sheets 
https://github.com/asciidoctor/asciidoctor-stylesheet-factory[asciidoctor-stylesheet-factory].

Rather than using Bootswatch themes, you may also create a custom theme by providing your own +variables.less+ file. 
A good online resource for creating your own style is http://pikock.github.io/bootstrap-magic/index.html[Bootstrap Magic].

You may conveniently save your +variables.less+ directly from the site.

== Prerequisites

The following software must be installed before you start:

  * http://www.lesscss.org/[Less]
  * http://asciidoctor.org[Asciidoctor]

NOTE: Make sure that the Ruby gems 'tilt' and 'coderay' are installed.

== Setup

Clone the source from GitHub:

 $ git clone --recurse-submodules https://github.com/nerk/asciidoctor-bs-themes
 
NOTE: If you don't want to use GIT, you may also download the code as a +.zip+ file and unpack it 
to a local directory.

Next, switch to the 'asciidoctor-bs-themes' directory and generate the CSS files:

 $ cd asciidoctor-bs-themes
 $ ./buildcss

This creates the following CSS files in directory +css+:

-----
bootstrap_amelia.css
bootstrap_cerulean.css
bootstrap_cosmo.css
bootstrap_cyborg.css
bootstrap_default.css
bootstrap_flatly.css
bootstrap_journal.css
bootstrap_readable.css
bootstrap_slate.css
bootstrap_spacelab.css
bootstrap_yeti.css
-----

You may test your created themes by generating some example documents from directory +test+:

 $ cd test
 $ ./gendoc
 
This compiles the original AsciiDoc User Guide by <NAME> and a file named 'test.adoc'
for each of the generated styles and puts the HTML output into directory 'output'.

== Using Generated Styles

To create HTML from an AsciiDoc source using a generated style, you may specify the CSS stylesheet 
from the command line. For example, to use the +bootstrap_flatly+ style, invoke:

 asciidoctor -a stylesheet="css/bootstrap_flatly.css" thedocument.adoc

Rather than using 'asciidoctor', you may also use Stuart Rackham's http://www.asciidoc.org[asciidoc] instead:
 
 asciidoc -a stylesheet="`pwd`/css/bootstrap_flatly.css" thedocument.adoc
 
NOTE: +asciidoc+ (unlike +asciidoctor+) requires an absolute path to the stylesheet, if the stylesheet is
not globally installed.
 
Unless you specify the +linkcss+ attribute, the stylesheet is directly embedded into the generated document.
The reference to the stylesheet refers to its location on the file system at *compile time* of the document.

For including just a reference to the stylesheet, use:

 asciidoctor -a linkcss -a stylesheet="css/bootstrap_flatly.css" thedocument.adoc
 
Please note that in this case, the reference to the stylesheet is resolved when the generated
document is displayed in the browser.

If you want to tweak the generated output further or want to include additional JavaScript libraries
into the generated document, you may specify your own Asciidoctor templates.
You can find a modified +document.html.erb+ template under

 src/templates/html5/document.html.erb
 
This modified template will put references to +jQuery+ and +bootstrap.js+ into the generated document. 
When compiling your document, you must specify the location of the template directory:

 asciidoctor -T src/templates -a stylesheet="css/bootstrap_flatly.css" thedocument.adoc

NOTE: The included +document.html.erb+ template was tested with Asciidoctor 0.1.4 and may
not work with other versions.

== Custom Styles

If you want to create a custom style based on Bootstrap, do the following (we assume your
new style is named 'awesome'):

* Create a new file +variables_awesome.less+ and put it into folder +src/less+. 
   For example, you may use http://pikock.github.io/bootstrap-magic/index.html[Bootstrap Magic] 
   to create a theme and save the variables to a file.
   
* Create a new file named +styles_awesome.less+ with the following content:
+
----
@import url(http://raw.github.com/twbs/bootstrap/master/less/bootstrap.less);

@import "variables_awesome.less";

@import "adocvariables.less";
@import "asciidoc.less";
@import "awesome-icons.less";
@import "mixins.less";
----
   
* Invoke 
+
----
lessc src/less/styles_awesome.less css/bootstrap_awesome.css
----
from the toplevel directory to create the new CSS file.

== Using Special Bootstrap Markup

Bootstrap components use +class+ for additional styling. 

For example, Bootstrap tables may be styled by adding one or more of the following classes:

 * table-striped
 * table-bordered
 * table-hover
 * table-condensed
 
If you want to use these additional styles for your AsciiDoc tables, you
can use the 'role' attribute:

----
[role="table-striped table-hover",options="header,footer"]
|=======================
|Col 1|Col 2      |Col 3
|1    |Item 1     |a
|2    |Item 2     |b
|3    |Item 3     |c
|6    |Three items|d
|=======================
----

NOTE: Default tables in Bootstrap are not bordered and without grid lines by default. However, to be compatible with
default AsciiDoc behavior, the generated styles create fully bordered tables with grid lines. Grid lines and borders
may be explicitly switched off using the +grid+ and +frame+ attributes.

== Shortcomings

 * The dark themes in particular could use some additional tweaking.
 * The Google Fonts API is used for some of the themes. 
   On Webkit-based browsers like Chrome under Windows, they are not 
   rendered nicely. This is a known problem.
   
== Copyright

Copyright (C) 2014 <NAME>.
Free use of this software is granted under the terms of the MIT License.

See the {license}[LICENSE] file for details.
<commit_msg>Update regarding #2<commit_after>= Asciidoctor Bootstrap Themes
<NAME>
:idprefix:
:idseparator: -
:sources: https://github.com/nerk/asciidoctor-bs-themes
:license: https://github.com/nerk/asciidoctor-bs-themes/blob/master/LICENSE

Create style sheets to theme AsciiDoc HTML output using http://www.getbootstrap.com[Bootstrap] and free themes from http://bootswatch.com/[Bootswatch].

== Introduction

The AsciiDoc markup processor http://asciidoctor.org[Asciidoctor] already includes a good set of CSS style sheets based on http://foundation.zurb.com[Foundation].
However, if you would like to use themes based on Twitter's http://getbootstrap.com[Bootstrap] instead, this project is for you.

Bootstrap is using the http://www.lesscss.org/[Less] preprocessor to compile +.less+ style sheets into CSS files. Most of Bootstrap's
styling like sizes, fonts, and colors is defined in a file named +variables.less+. By modifying the contents of this 
file or overriding the values of the defined variables, you can create your own Bootstrap themes.

A popular site with free Bootstrap themes is http://bootswatch.com/[Bootswatch]. Fortunately, rather than downloading the final
CSS files, you can also just grab the +variables.less+ file for almost any of the themes.

This project uses the Bootstrap +.less+ sources, +variables.less+ files from Bootswatch, and additional 
styling specific to AsciiDoc to create AsciiDoc-enhanced versions of the Bootswatch themes. The 
AsciiDoc specific styling is based on Dan Allen's Asciidoctor SASS style sheets 
https://github.com/asciidoctor/asciidoctor-stylesheet-factory[asciidoctor-stylesheet-factory].

Rather than using Bootswatch themes, you may also create a custom theme by providing your own +variables.less+ file. 
A good online resource for creating your own style is http://pikock.github.io/bootstrap-magic/index.html[Bootstrap Magic].

You may conveniently save your +variables.less+ directly from the site.

== Prerequisites

The following software must be installed before you start:

  * http://www.lesscss.org/[Less]
  * http://asciidoctor.org[Asciidoctor]

NOTE: Make sure that the Ruby gems 'tilt' and 'coderay' are installed.

== Setup

Clone the source from GitHub:

 $ git clone --recurse-submodules https://github.com/nerk/asciidoctor-bs-themes
 
NOTE: If you don't want to use GIT, you may also download the code as a +.zip+ file and unpack it 
to a local directory.

Next, switch to the 'asciidoctor-bs-themes' directory and generate the CSS files:

 $ cd asciidoctor-bs-themes
 $ ./buildcss

This creates the following CSS files in directory +css+:

-----
bootstrap_amelia.css
bootstrap_cerulean.css
bootstrap_cosmo.css
bootstrap_cyborg.css
bootstrap_default.css
bootstrap_flatly.css
bootstrap_journal.css
bootstrap_readable.css
bootstrap_slate.css
bootstrap_spacelab.css
bootstrap_yeti.css
-----

You may test your created themes by generating some example documents from directory +test+:

 $ cd test
 $ ./gendoc
 
This compiles the original AsciiDoc User Guide by <NAME> and a file named 'test.adoc'
for each of the generated styles and puts the HTML output into directory 'output'.

== Using Generated Styles

To create HTML from an AsciiDoc source using a generated style, you may specify the CSS stylesheet 
from the command line. For example, to use the +bootstrap_flatly+ style, invoke:

 asciidoctor -a stylesheet="css/bootstrap_flatly.css" thedocument.adoc

Rather than using 'asciidoctor', you may also use St<NAME>ham's http://www.asciidoc.org[asciidoc] instead:
 
 asciidoc -a stylesheet="`pwd`/css/bootstrap_flatly.css" thedocument.adoc
 
NOTE: +asciidoc+ (unlike +asciidoctor+) requires an absolute path to the stylesheet, if the stylesheet is
not globally installed.
 
Unless you specify the +linkcss+ attribute, the stylesheet is directly embedded into the generated document.
The reference to the stylesheet refers to its location on the file system at *compile time* of the document.

For including just a reference to the stylesheet, use:

 asciidoctor -a linkcss -a stylesheet="css/bootstrap_flatly.css" thedocument.adoc
 
Please note that in this case, the reference to the stylesheet is resolved when the generated
document is displayed in the browser.

If you want to tweak the generated output further or want to include additional JavaScript libraries
into the generated document, you may specify your own Asciidoctor templates.
You can find a modified +document.html.erb+ template under

 src/templates/html5/document.html.erb
 
This modified template will put references to +jQuery+ and +bootstrap.js+ into the generated document. 
When compiling your document, you must specify the location of the template directory:

 asciidoctor -T src/templates -a stylesheet="css/bootstrap_flatly.css" thedocument.adoc

NOTE: The included +document.html.erb+ template was tested with Asciidoctor 0.1.4 and may
not work with other versions.

== Custom Styles

If you want to create a custom style based on Bootstrap, do the following (we assume your
new style is named 'awesome'):

* Create a new directory +src/less/styles/awesome+

* Inside +src/styles/awesome+, create a new file +variables.less+. 
   For example, you may use http://pikock.github.io/bootstrap-magic/index.html[Bootstrap Magic] 
   to create a theme and save the variables to a file.
   
* Inside +src/styles/awesome+, create a new file named +styles.less+ with the following content:
+
----
@import url(http://raw.github.com/twbs/bootstrap/master/less/bootstrap.less);

@import "variables.less";

@import "../../adocvariables.less";
@import "../../asciidoc.less";
@import "../../awesome-icons.less";
@import "../../mixins.less";
----
   
* Invoke 
+
----
lessc src/less/styles/awesome/styles.less css/bootstrap_awesome.css
----
from the toplevel directory to create the new CSS file.

== Using Special Bootstrap Markup

Bootstrap components use +class+ for additional styling. 

For example, Bootstrap tables may be styled by adding one or more of the following classes:

 * table-striped
 * table-bordered
 * table-hover
 * table-condensed
 
If you want to use these additional styles for your AsciiDoc tables, you
can use the 'role' attribute:

----
[role="table-striped table-hover",options="header,footer"]
|=======================
|Col 1|Col 2      |Col 3
|1    |Item 1     |a
|2    |Item 2     |b
|3    |Item 3     |c
|6    |Three items|d
|=======================
----

NOTE: Default tables in Bootstrap are not bordered and without grid lines by default. However, to be compatible with
default AsciiDoc behavior, the generated styles create fully bordered tables with grid lines. Grid lines and borders
may be explicitly switched off using the +grid+ and +frame+ attributes.

== Shortcomings

 * The dark themes in particular could use some additional tweaking.
 * The Google Fonts API is used for some of the themes. 
   On Webkit-based browsers like Chrome under Windows, they are not 
   rendered nicely. This is a known problem.
   
== Copyright

Copyright (C) 2014 <NAME>.
Free use of this software is granted under the terms of the MIT License.

See the {license}[LICENSE] file for details.

{'fraction_non_alphanumeric': 0.0859353023909986, 'fraction_numerical': 0.00260196905766526, 'mean_word_length': 4.380628074158154, 'pattern_counts': {'":': 0, '<': 10, '<?xml version=': 0, '>': 10, 'https://': 8, 'lorem ipsum': 0, 'www.': 8, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1138277', 'n_tokens_mistral': 4085, 'n_tokens_neox': 3910, 'n_words': 1724}