Add new features details

Add new features details

= Real-time collaborative editor for Asciidoc files
Maxime Greau <https://github.com/mgreau[@mgreau]>
:awestruct-layout: base
:imagesdir: ./doc/img
:idprefix:
:idseparator: -
:online-demo: http://wildfly-mgreau.rhcloud.com/ad-editor
:milestones: https://github.com/mgreau/when-websocket-met-asciidoctor/issues/milestones
:issues: https://github.com/mgreau/when-websocket-met-asciidoctor/issues
:asciidoctor-url: http://asciidoctor.org
:asciidoctorj-url: https://github.com/asciidoctor/asciidoctorj
:wildfly-url: http://download.jboss.org/wildfly/8.0.0.CR1/wildfly-8.0.0.CR1.zip

You can try the editor online at {online-demo} (running on OpenShift).

This project gives you the possibility to *work on the same AsciiDoc file with a team*.

It's based on the {asciidoctor-url}[Asciidoctor project] thanks to the Java API provided by {asciidoctor-url}[AsciidoctorJ].

image::ad-editor-0.1.0-alpha2.png[Patch feature example]

== 0.1.0-Alpha2 features

* Create a *new space* OR *join others author* with a spaceID
* *Browser storage* with HTML5 IndexedDB for backup (save and load AsciiDoc source)
* Fullscreen mode for HTML5 preview
* Improved UI Design
* Realtime HTML5 preview :
** *each key entered* if you have clicked on +Render On Change+
** *each time you press "Alt+R"* if you have clicked on +Render On Alt+R+ button
* *Patch feature* :
** if an other author send a version, you can click on +Compute Diff+ button to see differences between your adoc file and the last adoc file
** if the patch seems ok, click on +Apply Patch+ and you adoc source will be up to date

== Changelog

You can read all changes between each release in the link:CHANGELOG.adoc[changelog file].

== Roadmap

A lot of cool features are planned :) You can read all {issues}[open and closed issues] and {milestones}[milestones]

== Install on your laptop

[IMPORTANT]
.Prerequisites
====
* JDK 7
* Apache Maven 3.1
====

. Clone or download this github project (*+$APP_HOME+*)

. Installing the Java EE 7 Compliance App server
.. Download {wildfly-url}[WildFly 8.0.0-CR1] (*+$JBOSS_HOME+*)
.. Then you need to deploy the link:module/README.adoc[Asciidoctor module] into your WildFly app server

. Installing Bower
.. Bower depends on Node and npm. It's installed globally using npm:

  npm install -g bower

.. Installing the bower dependencies needed by this app

  cd $APP_HOME
  bower install

. Build the WAR and test it into WildFly AS with maven/arquillian :

   .. if the environement variable +$JBOSS_HOME+ is set :

   mvn clean package -Pwildfly-managed-arquillian

   .. if you haven't set the +$JBOSS_HOME+ env variable :

   mvn clean package -Pwildfly-managed-arquillian -DserverRoot=<path_to_the_server>

.  Deploy the app automatically with maven :

  .. if the app server is started

  mvn wildfly:deploy -Dmaven.test.skip=true

  .. if the app server isn't started

  mvn wildfly:run -Dmaven.test.skip=true -Djboss-as.home=<path_to_the_server>

. Launch your browser and enjoy :)

   *  http://localhost:8080/ad-editor

== Technology used

* Asciidoctor project
** AsciidoctorJ 0.1.4
* Java EE 7
** CDI 1.1
** WebSocket 1.0
** JSON-P 1.0
** EJB 3.2
* Web Client
** AngularJS 1.2.11
** Ace Editor
** Bootstrap 3.0
* Tests
** JUnit 4.8
** Arquillian 1.1.2
* Java EE 7 Compliance App server

= Real-time collaborative editor for Asciidoc files
Maxime Greau <https://github.com/mgreau[@mgreau]>
:awestruct-layout: base
:imagesdir: ./doc/img
:idprefix:
:idseparator: -
:online-demo: http://wildfly-mgreau.rhcloud.com/ad-editor
:milestones: https://github.com/mgreau/when-websocket-met-asciidoctor/issues/milestones
:issues: https://github.com/mgreau/when-websocket-met-asciidoctor/issues
:asciidoctor-url: http://asciidoctor.org
:asciidoctorj-url: https://github.com/asciidoctor/asciidoctorj
:wildfly-url: http://download.jboss.org/wildfly/8.0.0.CR1/wildfly-8.0.0.CR1.zip

You can try the editor online at {online-demo} (running on OpenShift).

This project gives you the possibility to *work on the same AsciiDoc file with a team*.

It's based on the {asciidoctor-url}[Asciidoctor project] thanks to the Java API provided by {asciidoctor-url}[AsciidoctorJ].

image::patch-demo.png[Patch feature example]

== 0.1.0-Alpha2 features

* By default when you click on +connect+, you are a +*reader*+ :
** It means that you can see what happens on HTML5 preview but you can't send any source version
* When you +add a name+ and click to +Enable editor+, you become a +*writer*+ :
** so you can update the asciidoc source in realtime and automatically view HTML 5 rendered :
*** *each time you write something* if you have clicked on +Send On Change+
*** *each time you press "Ctrl+S"* if you have clicked on +Send On Ctrl+S+ button
* You can *patch your file with the latest asciidoc source*:
** if an other author send a version, you can click on +Compute Diff+ button to see differences between your adoc file and the last adoc file
** if the patch seems ok, click on +Apply Patch+ and you adoc source will be up to date
* *Several people can work* on the same doc
** you can see the number of writers (people who send adoc file)
** you can see the name of the last author
** ypu can see the numbr of readers (people who don't send an asciidoc source)

== Changelog

You can read all changes between each release in the link:CHANGELOG.adoc[changelog file].

== Roadmap

A lot of cool features are planned :) You can read all {issues}[open and closed issues] and {milestones}[milestones]

== Install on your laptop

[IMPORTANT]
.Prerequisites
====
* JDK 7
* Apache Maven 3.1
====

. Clone or download this github project (*+$APP_HOME+*)

. Installing the Java EE 7 Compliance App server
.. Download {wildfly-url}[WildFly 8.0.0-CR1] (*+$JBOSS_HOME+*)
.. Then you need to deploy the link:module/README.adoc[Asciidoctor module] into your WildFly app server

. Installing Bower
.. Bower depends on Node and npm. It's installed globally using npm:

  npm install -g bower
  cd $APP_HOME
  bower install
  choose AngularJS 2.11

. Build the WAR and test it into WildFly AS with maven/arquillian :

   .. if the environement variable +$JBOSS_HOME+ is set :

   mvn clean package -Pwildfly-managed-arquillian

   .. if you haven't set the +$JBOSS_HOME+ env variable :

   mvn clean package -Pwildfly-managed-arquillian -DserverRoot=<path_to_the_server>

.  Deploy the app automatically with maven :

  .. if the app server is started

  mvn wildfly:deploy -Dmaven.test.skip=true

  .. if the app server isn't started

  mvn wildfly:run -Djboss-as.home=<path_to_the_server>

. Launch your browser and enjoy :)

   *  http://localhost:8080/ad-editor

== Technology used

* Asciidoctor project
** AsciidoctorJ 0.1.4
* Java EE 7
** CDI 1.1
** WebSocket 1.0
** JSON-P 1.0
** EJB 3.2
* Web Client
** AngularJS 1.2.11
** Ace Editor
** Bootstrap 3.0
* Tests
** JUnit 4.8
** Arquillian 1.1.2
* Java EE 7 Compliance App server


explain the asciidoctor-pdf command in more detail

= Asciidoctor PDF: A native PDF converter for AsciiDoc
Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>
// Settings:
:compat-mode!:
:experimental:
:idprefix:
:idseparator: -
:icons: font
ifdef::env-github,env-browser[:outfilesuffix: .adoc]
:pagenums:
//:pdf-page-size: [8.25in, 11.69in]
//:pdf-page-size: A4
ifdef::env-browser[:toc: preamble]
// Aliases:
:project-name: Asciidoctor PDF
:project-handle: asciidoctor-pdf
// URIs:
//ifdef::env-github[:relfileprefix: /blob/master/]
:uri-project: https://github.com/asciidoctor/asciidoctor-pdf
:uri-project-repo: {uri-project}
:uri-project-issues: {uri-project-repo}/issues
:uri-project-list: http://discuss.asciidoctor.org
:uri-prawn: http://prawn.majesticseacreature.com
:uri-rvm: http://rvm.io
:uri-asciidoctor: http://asciidoctor.org

_Lo and behold_, a native PDF converter for AsciiDoc built with {uri-asciidoctor}[Asciidoctor] and {uri-prawn}[Prawn]! +
_No more middleman._ +
_No more DocBook toolchain._ +
It's AsciiDoc straight to PDF!

[caption=Status]
CAUTION: {project-name} is currently _alpha_ software.
While the converter handles most AsciiDoc content, there's still work needed to fill in gaps where conversion is incomplete, incorrect or not implemented.
See the milestone v1.5.0 in the {uri-project-issues}[issue tracker] for details.

== Prawn, the majestic PDF generator

{uri-project}[{project-name}] is made possible by an amazing Ruby gem named Prawn.
And what a gem it is!

{uri-prawn}[Prawn] is a nimble PDF writer for Ruby.
More important, it's a hackable platform that offers both high level APIs for the most common needs and low level APIs for bending the document model to accommodate special circumstances.

With Prawn, you can write text, draw lines and shapes and place images _anywhere_ on the page and add as much color as you like.
In addition, it brings a fluent API and aggressive code re-use to the printable document space.

Here's an example that demonstrates how to use Prawn to create a basic PDF document.

.Create a basic PDF document using Prawn
[source,ruby]
----
require 'prawn'

Prawn::Document.generate 'output.pdf' do
  text 'Hello, PDF creation!'
end
----

It's that easy.
And that's just the beginning.
Skip ahead to <<getting-started,Getting started>> to start putting it use.

Prawn is the _killer library_ for PDF generation we've needed to close this critical gap in Asciidoctor.
It absolutely takes the pain out of creating printable documents.
Picking up from there, {project-name} takes the pain out of creating PDF documents _from AsciiDoc_.

== Features

=== Notable features

* Direct AsciiDoc to PDF conversion
* <<docs/theming-guide.adoc#,Configuration-driven style and layout>>
* PDF document outline (i.e., bookmarks)
* Table of contents page(s)
* Document metadata (title, authors, subject, keywords, etc)
* Internal cross reference links
* Syntax highlighting with CodeRay or Pygments
* Page numbering
* Customizable running content (header and footer)
* “Keep together” blocks (i.e., page breaks avoided in certain block content)
* Orphan section titles avoided
* Table border settings honored
* Font-based icons
* Custom fonts

=== Missing features

See <<WORKLOG.adoc#,WORKLOG>>.

== Prerequisites

All that's needed is Ruby (1.9.3 or above; 2.2.x recommended) and a few Ruby gems, which we explain how to install in the next section.

[WARNING]
====
Prawn 2.0.0 and above requires Ruby >= 2.0.0 at installation (though it still works with Ruby 1.9.3 once you get beyond installation).
If you need to use Asciidoctor PDF with Ruby 1.9.3, you must first install Prawn 1.3.0 using:

  $ gem install prawn --version 1.3.0

You can then proceed with installation of Asciidoctor PDF.
====

To check you have Ruby available, use the `ruby` command to query the version installed:

 $ ruby --version

== Getting started

You can get {project-name} by <<install-the-published-gem,installing the published gem>> or <<development,running the code from source>>.

=== Install the published gem

{project-name} is published in pre-release on RubyGems.org.
You can install the published gem using the following command:

 $ gem install --pre asciidoctor-pdf

If you want to syntax highlight source listings, you'll also want to install CodeRay, Rouge or Pygments.
Choose one (or more) of the following:

.CodeRay
 $ gem install coderay

.Rouge
 $ gem install rouge

.Pygments
 $ gem install pygments.rb

You then activate syntax highlighting for a given document by adding the following attribute to the document header (CodeRay shown):

[source,asciidoc]
----
:source-highlighter: coderay
----

Assuming all the required gems install properly, verify you can run the `asciidoctor-pdf` script:

 $ asciidoctor-pdf -v

If you see the version of {project-name} printed, you're ready to use {project-name}.

Let's grab an AsciiDoc document to distill and start putting {project-name} to use!

=== An example AsciiDoc document

If you don't already have an AsciiDoc document, you can use the [file]_basic-example.adoc_ file found in the examples directory of this project.

ifeval::[{safe-mode-level} >= 20]
See <<examples/basic-example.adoc#,basic-example.adoc>>.
endif::[]
ifeval::[{safe-mode-level} < 20]
.basic-example.adoc
[source,asciidoc]
....
include::examples/basic-example.adoc[]
....
endif::[]

It's time to convert the AsciiDoc document directly to PDF.

=== Convert AsciiDoc to PDF

IMPORTANT: You'll need the `coderay` gem installed to run this example since it uses the `source-highlighter` attribute with the value of `coderay`.

Converting to PDF is a simple as running the `asciidoctor-pdf` script using Ruby and passing our AsciiDoc document as the first argument.

 $ asciidoctor-pdf basic-example.adoc

This command is just a shorthand way of running:

 $ asciidoctor -r asciidoctor-pdf -b pdf basic-example.adoc

The `asciidoctor-pdf` command just saves you from having to remember all those flags.
That's why we created it.

When the script completes, you should see the file [file]_basic-example.pdf_ in the same directory.
Open the [file]_basic-example.pdf_ file with a PDF viewer to see the result.

.Example PDF document rendered in a PDF viewer
image::examples/example-pdf-screenshot.png[Screenshot of PDF document,width=800,scaledwidth=100%]

You're also encouraged to try converting this <<README#,README>> as well as the documents in the examples directory to see more of what {project-name} can do.

The pain of the DocBook toolchain should be melting away about now.

== Themes

The layout and styling of the PDF is driven by a YAML configuration file.
To learn how the theming system works and how to create and apply custom themes, refer to the <<docs/theming-guide.adoc#,Asciidoctor PDF Theme Guide>>.
You can use the built-in theme files, which you can find in the [file]_data/themes_ directory, as examples.

== Font-based Icons

You can use icons in your PDF document using any of the following icon sets:

* *fa* - https://fortawesome.github.io/Font-Awesome/[Font Awesome^] (default)
* *octicon* - https://octicons.github.com/[Octicons^]
* *fi* - http://zurb.com/playground/foundation-icon-fonts-3[Foundation Icons^]
* *pf* - http://paymentfont.io/[Payment font^]

You can enable font-based icons by setting the following attribute in the header of your document:

[source,asciidoc]
----
:icons: font
----

If you want to override the font set globally, also set the `icon-set` attribute:

[source,asciidoc]
----
:icons: font
:icon-set: pf
----

Here's an example that shows how to use the Amazon icon from the payment font (pf) icon set in a sentence:

[source,asciidoc]
----
Available now at icon:amazon[].
----

You can use the `set` attribute on the icon macro to override the icon set for a given icon.

[source,asciidoc]
----
Available now at icon:amazon[set=pf].
----

In addition to the sizes supported in the HTML backend (lg, 1x, 2x, etc), you can enter any relative value in the size attribute (e.g., 1.5em, 150%, etc).

[source,asciidoc]
----
icon:android[size=40em]
----

You can enable use of fonts during PDF generation (instead of in the document header) by passing the `icons` attribute to the `asciidoctor-pdf` command.

 $ asciidoctor-pdf -a icons=font -a icon-set=octicon sample.adoc

Icon-based fonts are handled by the `prawn-icon` gem.
To find a complete list of available icons, consult the https://github.com/jessedoyle/prawn-icon/tree/master/data/fonts[prawn-icon] repository.

== Optional scripts

{project-name} also provides a shell script that invokes GhostScript (`gs`) to optimize and compress the generated PDF with minimal impact on quality.
You must have Ghostscript installed to use it.

Here's an example usage:

 $ ./bin/optimize-pdf basic-example.pdf

The command will generate the file [file]_example-optimized.pdf_ in the current directory.

WARNING: The `optimize-pdf` script currently requires a Bash shell (Linux, OSX, etc).
We plan to rewrite the script in Ruby so it works across platforms (see https://github.com/asciidoctor/asciidoctor-pdf/issues/1[issue #1])

IMPORTANT: The `optimize-pdf` script relies on Ghostscript >= 9.10.
Otherwise, it may actually make the PDF larger.
Also, you should only consider using it if the file size of the original PDF is > 5MB.

If a file is found with the extension `.pdfmarks` and the same rootname as the input file, it is used to add metadata to the generated PDF document.
This file is necessary to preserve the document metadata since Ghostscript will otherwise drop it.
That's why {project-name} always creates this file in addition to the PDF.

== Contributing

In the spirit of free software, _everyone_ is encouraged to help improve this project.

To contribute code, simply fork the project on GitHub, hack away and send a pull request with your proposed changes.

Feel free to use the {uri-project-issues}[issue tracker] or {uri-project-list}[Asciidoctor mailing list] to provide feedback or suggestions in other ways.

== Development

To help develop {project-name}, or to simply use the development version, you need to get the source from GitHub.
Follow the instructions below to learn how to clone the source and run it from your local copy.

=== Retrieve the source code

You can retrieve the source of {project-name} in one of two ways:

. Clone the git repository
. Download a zip archive of the repository

==== Option 1: Fetch using git clone

If you want to clone the git repository, simply copy the {uri-project-repo}[GitHub repository URL] and pass it to `git clone` command:

 $ git clone https://github.com/asciidoctor/asciidoctor-pdf

Next, change to the project directory:

 $ cd asciidoctor-pdf

==== Option 2: Download the archive

If you want to download a zip archive, click the btn:[Download Zip] button on the right-hand side of the repository page on GitHub.
Once the download finishes, extract the archive, open a console and change to that directory.

TIP: Instead of working out of the {project-handle} directory, you can simply add the absolute path of the [path]_bin_ directory to your `PATH` environment variable.

We'll leverage the project configuration to install the necessary dependencies.

=== Install dependencies

If you're using {uri-rvm}[RVM], we recommend creating a new gemset to work with {project-name}:

 $ rvm use 2.2@asciidoctor-pdf --create

We like RVM because it keeps the dependencies required by various projects isolated.

The dependencies needed to use {project-name} are defined in the [file]_Gemfile_ at the root of the project.
We can use Bundler to install the dependencies for us.

To check you have Bundler available, use the `bundle` command to query the version installed:

 $ bundle --version

If it's not installed, use the `gem` command to install it.

 $ gem install bundler

Then use the `bundle` command to install the project dependencies:

 $ bundle

NOTE: You need to call `bundle` from the project directory so that it can find the [file]_Gemfile_.

Assuming all the required gems install properly, verify you can run the `asciidoctor-pdf` script using Ruby:

 $ ruby ./bin/asciidoctor-pdf -v

or

 $ bundle exec ./bin/asciidoctor-pdf -v

If you see the version of {project-name} printed, you're ready to use {project-name}!

CAUTION: If you get an error message--and you're not using a Ruby manager like RVM--you may need to invoke the script through `bundle exec`:
For best results, be sure to always use `bundle exec` whenever invoking the `./bin/asciidoctor-pdf` script in development mode.

[[resources,Links]]
== Resources

* https://groups.google.com/forum/#!msg/prawn-ruby/MbMsCx862iY/6ImCsvLGfVcJ[Discussion about image quality in PDFs]

== Authors

{project-name} was written by https://github.com/mojavelinux[Dan Allen] and https://github.com/graphitefriction[Sarah White] of OpenDevise Inc. on behalf of the Asciidoctor Project.

== Copyright

Copyright (C) 2014-2015 OpenDevise Inc. and the Asciidoctor Project.
Free use of this software is granted under the terms of the MIT License.

For the full text of the license, see the <<LICENSE.adoc#,LICENSE>> file.
Refer to the <<NOTICE.adoc#,NOTICE>> file for information about third-party Open Source software in use.

= Asciidoctor PDF: A native PDF converter for AsciiDoc
Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>
// Settings:
:compat-mode!:
:experimental:
:idprefix:
:idseparator: -
:icons: font
ifdef::env-github,env-browser[:outfilesuffix: .adoc]
:pagenums:
//:pdf-page-size: [8.25in, 11.69in]
//:pdf-page-size: A4
ifdef::env-browser[:toc: preamble]
// Aliases:
:project-name: Asciidoctor PDF
:project-handle: asciidoctor-pdf
// URIs:
//ifdef::env-github[:relfileprefix: /blob/master/]
:uri-project: https://github.com/asciidoctor/asciidoctor-pdf
:uri-project-repo: {uri-project}
:uri-project-issues: {uri-project-repo}/issues
:uri-project-list: http://discuss.asciidoctor.org
:uri-prawn: http://prawn.majesticseacreature.com
:uri-rvm: http://rvm.io
:uri-asciidoctor: http://asciidoctor.org

_Lo and behold_, a native PDF converter for AsciiDoc built with {uri-asciidoctor}[Asciidoctor] and {uri-prawn}[Prawn]! +
_No more middleman._ +
_No more DocBook toolchain._ +
It's AsciiDoc straight to PDF!

[caption=Status]
CAUTION: {project-name} is currently _alpha_ software.
While the converter handles most AsciiDoc content, there's still work needed to fill in gaps where conversion is incomplete, incorrect or not implemented.
See the milestone v1.5.0 in the {uri-project-issues}[issue tracker] for details.

== Prawn, the majestic PDF generator

{uri-project}[{project-name}] is made possible by an amazing Ruby gem named Prawn.
And what a gem it is!

{uri-prawn}[Prawn] is a nimble PDF writer for Ruby.
More important, it's a hackable platform that offers both high level APIs for the most common needs and low level APIs for bending the document model to accommodate special circumstances.

With Prawn, you can write text, draw lines and shapes and place images _anywhere_ on the page and add as much color as you like.
In addition, it brings a fluent API and aggressive code re-use to the printable document space.

Here's an example that demonstrates how to use Prawn to create a basic PDF document.

.Create a basic PDF document using Prawn
[source,ruby]
----
require 'prawn'

Prawn::Document.generate 'output.pdf' do
  text 'Hello, PDF creation!'
end
----

It's that easy.
And that's just the beginning.
Skip ahead to <<getting-started,Getting started>> to start putting it use.

Prawn is the _killer library_ for PDF generation we've needed to close this critical gap in Asciidoctor.
It absolutely takes the pain out of creating printable documents.
Picking up from there, {project-name} takes the pain out of creating PDF documents _from AsciiDoc_.

== Features

=== Notable features

* Direct AsciiDoc to PDF conversion
* <<docs/theming-guide.adoc#,Configuration-driven style and layout>>
* PDF document outline (i.e., bookmarks)
* Table of contents page(s)
* Document metadata (title, authors, subject, keywords, etc)
* Internal cross reference links
* Syntax highlighting with CodeRay or Pygments
* Page numbering
* Customizable running content (header and footer)
* “Keep together” blocks (i.e., page breaks avoided in certain block content)
* Orphan section titles avoided
* Table border settings honored
* Font-based icons
* Custom fonts

=== Missing features

See <<WORKLOG.adoc#,WORKLOG>>.

== Prerequisites

All that's needed is Ruby (1.9.3 or above; 2.2.x recommended) and a few Ruby gems, which we explain how to install in the next section.

[WARNING]
====
Prawn 2.0.0 and above requires Ruby >= 2.0.0 at installation (though it still works with Ruby 1.9.3 once you get beyond installation).
If you need to use Asciidoctor PDF with Ruby 1.9.3, you must first install Prawn 1.3.0 using:

  $ gem install prawn --version 1.3.0

You can then proceed with installation of Asciidoctor PDF.
====

To check you have Ruby available, use the `ruby` command to query the version installed:

 $ ruby --version

== Getting started

You can get {project-name} by <<install-the-published-gem,installing the published gem>> or <<development,running the code from source>>.

=== Install the published gem

{project-name} is published in pre-release on RubyGems.org.
You can install the published gem using the following command:

 $ gem install --pre asciidoctor-pdf

If you want to syntax highlight source listings, you'll also want to install CodeRay, Rouge or Pygments.
Choose one (or more) of the following:

.CodeRay
 $ gem install coderay

.Rouge
 $ gem install rouge

.Pygments
 $ gem install pygments.rb

You then activate syntax highlighting for a given document by adding the following attribute to the document header (CodeRay shown):

[source,asciidoc]
----
:source-highlighter: coderay
----

Assuming all the required gems install properly, verify you can run the `asciidoctor-pdf` script:

 $ asciidoctor-pdf -v

If you see the version of {project-name} printed, you're ready to use {project-name}.

Let's grab an AsciiDoc document to distill and start putting {project-name} to use!

=== An example AsciiDoc document

If you don't already have an AsciiDoc document, you can use the [file]_basic-example.adoc_ file found in the examples directory of this project.

ifeval::[{safe-mode-level} >= 20]
See <<examples/basic-example.adoc#,basic-example.adoc>>.
endif::[]
ifeval::[{safe-mode-level} < 20]
.basic-example.adoc
[source,asciidoc]
....
include::examples/basic-example.adoc[]
....
endif::[]

It's time to convert the AsciiDoc document directly to PDF.

=== Convert AsciiDoc to PDF

IMPORTANT: You'll need the `coderay` gem installed to run this example since it uses the `source-highlighter` attribute with the value of `coderay`.

Converting to PDF is a simple as running the `asciidoctor-pdf` script using Ruby and passing our AsciiDoc document as the first argument.

 $ asciidoctor-pdf basic-example.adoc

This command is just a shorthand way of running:

 $ asciidoctor -r asciidoctor-pdf -b pdf basic-example.adoc

When the script completes, you should see the file [file]_basic-example.pdf_ in the same directory.
Open the [file]_basic-example.pdf_ file with a PDF viewer to see the result.

.Example PDF document rendered in a PDF viewer
image::examples/example-pdf-screenshot.png[Screenshot of PDF document,width=800,scaledwidth=100%]

You're also encouraged to try converting this <<README#,README>> as well as the documents in the examples directory to see more of what {project-name} can do.

The pain of the DocBook toolchain should be melting away about now.

== Themes

The layout and styling of the PDF is driven by a YAML configuration file.
To learn how the theming system works and how to create and apply custom themes, refer to the <<docs/theming-guide.adoc#,Asciidoctor PDF Theme Guide>>.
You can use the built-in theme files, which you can find in the [file]_data/themes_ directory, as examples.

== Font-based Icons

You can use icons in your PDF document using any of the following icon sets:

* *fa* - https://fortawesome.github.io/Font-Awesome/[Font Awesome^] (default)
* *octicon* - https://octicons.github.com/[Octicons^]
* *fi* - http://zurb.com/playground/foundation-icon-fonts-3[Foundation Icons^]
* *pf* - http://paymentfont.io/[Payment font^]

You can enable font-based icons by setting the following attribute in the header of your document:

[source,asciidoc]
----
:icons: font
----

If you want to override the font set globally, also set the `icon-set` attribute:

[source,asciidoc]
----
:icons: font
:icon-set: pf
----

Here's an example that shows how to use the Amazon icon from the payment font (pf) icon set in a sentence:

[source,asciidoc]
----
Available now at icon:amazon[].
----

You can use the `set` attribute on the icon macro to override the icon set for a given icon.

[source,asciidoc]
----
Available now at icon:amazon[set=pf].
----

In addition to the sizes supported in the HTML backend (lg, 1x, 2x, etc), you can enter any relative value in the size attribute (e.g., 1.5em, 150%, etc).

[source,asciidoc]
----
icon:android[size=40em]
----

You can enable use of fonts during PDF generation (instead of in the document header) by passing the `icons` attribute to the `asciidoctor-pdf` command.

 $ asciidoctor-pdf -a icons=font -a icon-set=octicon sample.adoc

Icon-based fonts are handled by the `prawn-icon` gem.
To find a complete list of available icons, consult the https://github.com/jessedoyle/prawn-icon/tree/master/data/fonts[prawn-icon] repository.

== Optional scripts

{project-name} also provides a shell script that invokes GhostScript (`gs`) to optimize and compress the generated PDF with minimal impact on quality.
You must have Ghostscript installed to use it.

Here's an example usage:

 $ ./bin/optimize-pdf basic-example.pdf

The command will generate the file [file]_example-optimized.pdf_ in the current directory.

WARNING: The `optimize-pdf` script currently requires a Bash shell (Linux, OSX, etc).
We plan to rewrite the script in Ruby so it works across platforms (see https://github.com/asciidoctor/asciidoctor-pdf/issues/1[issue #1])

IMPORTANT: The `optimize-pdf` script relies on Ghostscript >= 9.10.
Otherwise, it may actually make the PDF larger.
Also, you should only consider using it if the file size of the original PDF is > 5MB.

If a file is found with the extension `.pdfmarks` and the same rootname as the input file, it is used to add metadata to the generated PDF document.
This file is necessary to preserve the document metadata since Ghostscript will otherwise drop it.
That's why {project-name} always creates this file in addition to the PDF.

== Contributing

In the spirit of free software, _everyone_ is encouraged to help improve this project.

To contribute code, simply fork the project on GitHub, hack away and send a pull request with your proposed changes.

Feel free to use the {uri-project-issues}[issue tracker] or {uri-project-list}[Asciidoctor mailing list] to provide feedback or suggestions in other ways.

== Development

To help develop {project-name}, or to simply use the development version, you need to get the source from GitHub.
Follow the instructions below to learn how to clone the source and run it from your local copy.

=== Retrieve the source code

You can retrieve the source of {project-name} in one of two ways:

. Clone the git repository
. Download a zip archive of the repository

==== Option 1: Fetch using git clone

If you want to clone the git repository, simply copy the {uri-project-repo}[GitHub repository URL] and pass it to `git clone` command:

 $ git clone https://github.com/asciidoctor/asciidoctor-pdf

Next, change to the project directory:

 $ cd asciidoctor-pdf

==== Option 2: Download the archive

If you want to download a zip archive, click the btn:[Download Zip] button on the right-hand side of the repository page on GitHub.
Once the download finishes, extract the archive, open a console and change to that directory.

TIP: Instead of working out of the {project-handle} directory, you can simply add the absolute path of the [path]_bin_ directory to your `PATH` environment variable.

We'll leverage the project configuration to install the necessary dependencies.

=== Install dependencies

If you're using {uri-rvm}[RVM], we recommend creating a new gemset to work with {project-name}:

 $ rvm use 2.2@asciidoctor-pdf --create

We like RVM because it keeps the dependencies required by various projects isolated.

The dependencies needed to use {project-name} are defined in the [file]_Gemfile_ at the root of the project.
We can use Bundler to install the dependencies for us.

To check you have Bundler available, use the `bundle` command to query the version installed:

 $ bundle --version

If it's not installed, use the `gem` command to install it.

 $ gem install bundler

Then use the `bundle` command to install the project dependencies:

 $ bundle

NOTE: You need to call `bundle` from the project directory so that it can find the [file]_Gemfile_.

Assuming all the required gems install properly, verify you can run the `asciidoctor-pdf` script using Ruby:

 $ ruby ./bin/asciidoctor-pdf -v

or

 $ bundle exec ./bin/asciidoctor-pdf -v

If you see the version of {project-name} printed, you're ready to use {project-name}!

CAUTION: If you get an error message--and you're not using a Ruby manager like RVM--you may need to invoke the script through `bundle exec`:
For best results, be sure to always use `bundle exec` whenever invoking the `./bin/asciidoctor-pdf` script in development mode.

[[resources,Links]]
== Resources

* https://groups.google.com/forum/#!msg/prawn-ruby/MbMsCx862iY/6ImCsvLGfVcJ[Discussion about image quality in PDFs]

== Authors

{project-name} was written by https://github.com/mojavelinux[Dan Allen] and https://github.com/graphitefriction[Sarah White] of OpenDevise Inc. on behalf of the Asciidoctor Project.

== Copyright

Copyright (C) 2014-2015 OpenDevise Inc. and the Asciidoctor Project.
Free use of this software is granted under the terms of the MIT License.

For the full text of the license, see the <<LICENSE.adoc#,LICENSE>> file.
Refer to the <<NOTICE.adoc#,NOTICE>> file for information about third-party Open Source software in use.


make heading bold

make heading bold

= IntelliJ AsciiDoc Plugin
Erik Pragt
:experimental:

A plugin for the IntelliJ platform (IntelliJ IDEA, RubyMine, etc) that provides support for the http://www.asciidoc.org[AsciiDoc] markup language. You can install the plugin (named "AsciiDoc") from the plugins section inside your Jetbrains IDE or download it from the https://plugins.jetbrains.com/plugin/7391[Jetbrains Plugin Repository].

image::https://hacktoberfest.digitalocean.com/assets/logo-hacktoberfest-658b5aa2bd34e782d29c40bf6afbdff00f20fe1328efa6da17743878ba8db66f.png[float=left,width=200]

*This plugin joined https://hacktoberfest.digitalocean.com/[Hacktoberfest]!
Issues that can give you a start are https://github.com/asciidoctor/asciidoctor-intellij-plugin/issues?q=is%3Aissue+is%3Aopen+label%3AHacktoberfest[marked with the label "Hacktoberfest"], but you can choose any ticket you want to participate (and even create pull requests without a prior ticket).
If you want to discuss ideas and create pull requests you can meet Alexander, one of the maintainers, at the https://www.eventbrite.com/e/hacktoberfest-frankfurt-2018-tickets-50225231018[Frankfurt/Main Hacktober Fest in Germany on October 12th].*

If you want to use the JavaFX instead of the Swing preview, you'll need to run IntelliJ with 64bit Java.
From 2017.1 onwards 64bit Java is included even in the Windows versions.
Please only use the JDK provided by JetBrains, as the JavaFX rendering seems to be most stable in the JetBrains JDK.

== Release notes

=== 0.21.1

- allow attributes to be pre-defined in plugin settings (#216)

=== 0.21.0 (preview, available from Github releases)

- Update to AsciidoctorJ 1.5.7 and Asciidoctor Diagram 1.5.9
- Treat "line must be non negative" only as a warning (#212)

=== 0.20.6

- Display all PlantUML graphics as PNG for preview (#170)

=== 0.20.5

- Adding hiDPI support for JavaFX preview (#125)

=== 0.20.4

- Requiring 2017.1 as minimum for this plugin (#207)

=== 0.20.3 (preview, available from Github releases)

- Avoiding deadlock on JavaFX initialization (#207)
- Requiring 2017.2 as minimum for this plugin

=== 0.20.2

- Dejavu fonts now display chinese characters within tables (#203)

=== 0.20.1

- Upgrading to asciidoctorj-diagram 1.5.8
- Dejavu fonts now display chinese characters (#203)

=== 0.20.0

- Add MathJax support in JavaFX preview #201
- JavaFX preview is now the default for new installations of the plugin
- Include DejaVu fonts for improved and consistent preview #184

=== 0.19.2

- Fix NullPointerExceptions when used with IntelliJ Language Injection and Fragment Editor #194

=== 0.19.1

- Support inspections to convert markdown and old style AsciiDoc headings to modern AsciiDoc headings #185
- JRuby runtime updated to 9.1.8.0 to work with recent JDK versions (still, internal Jetbrains JRE is the only supported version) #187

=== 0.19.0

- Support Icon fonts (thanks to @matthiasbalke) / #182
- Update to asciidoctorj-1.5.6 (aka asciidoctor-1.5.6.1) and asciidoctorj-diagram-1.5.4.1
- Support "search everywhere" (double Shift) and "goto by name - Symbol..." (Ctrl+Shift+Alt+N) for all AsciiDoc section headings - just enter a part of the heading
- Support Markdown style sections (starting with '#') in syntax highlighting

=== 0.18.2 (preview, available from Github releases)

- Headings in Darcula theme preview are now light grey for better readability

=== 0.18.1

- Improved handling for non-printable characters in syntax highlighting

=== 0.18.0 (preview, available from Github releases)

- Update to asciidoctor 1.5.5/asciidoctor-diagram 1.5.4
- Capture Asciidoctor messages on stdout/stderr and write them to IDE notifications
- Close files when images are shown in preview
- Set focus in editor when re-opening file
- Fix "line must be non negative" error when clicking on preview

=== 0.17.3

- Make click-on-link-to-open and click-on-preview-to-set-cursor in JavaFX preview compatible with Java 8 u111+
- Formatting actions from the toolbar should not throw exceptions when triggered at the beginning or end of the document

=== 0.17.2

- Plugin is now build using the https://gradle.org/[Gradle] and https://github.com/JetBrains/gradle-intellij-plugin[gradle-intellij-plugin]
This should make contributing and releasing easier. Thanks Jiawen Geng!
- Asciidoctor's temporary files are now created in a temporary folder per opened document. Thanks @agorges!

=== 0.17.1 (preview, available from Github releases)

- Improved handling of trailing spaces in syntax highlighting.
- Fixed code/preview sync for nested HTML (i.e. NOTE)

=== 0.17.0 (preview, available from Github releases)

- Updated block parsing to support two styles of headings.
- Block starts and ends are need to be aligned in length and shape when parsed.

=== 0.16.4

- Improved darcula support for JavaFX. More block types are using proper dark background and light text colors.

=== 0.16.3

- Theme in preview can be switched from light to darcula independent of IDE theme

=== 0.16.2

- Handling of Linux and MacOS file names for image preview in JavaFX

=== 0.16.1

- Added darcula theme for JavaFX preview
- Clicking on JavaFX preview will set cursor position in editor (thanks to @kastork for the idea)

=== 0.15.4

- setScene now called from FxThread instead of AWT thread to avoid blocking GUI on MacOS

=== 0.15.3

- Initialization message appears only during initialization
- No error message if user switches to a setup where JavaFX preview is no longer available.

=== 0.15.2 (preview, available from Github releases)

- fixed detection of Mac 64 JVM to be able to activate JavaFX preview
- click-on-url for JavaFX improved, when slow-loading external images are referenced

=== 0.15.1 (preview, available from Github releases)

- revised constrained/unconstrained detection
- Fix problem in syntax highlighting leading to PSI Parser Exceptions
- refreshing images on JavaFX only if their content has changed to save memory consumption
- Limiting JavaFX preview to 64bit platforms due to problems especially with Windows OpenJDK 32bit (as default on Windows).

=== 0.15.0 (preview, available from Github releases)

- correct usage of constrained/unconstrained AsciiDoc formatting
- JavaFX Preview will automatically scroll to the cursor position of the editor
- JavaFX preview will automatically open links in the systems's default browser
- Caching rendering instances of Asciidoctor for better performance

IntelliJ 15 (including AppCode 3.3, CLion 1.2, DataGrip 1.0, PhpStorm 10, PyCharm 5, RubyMine 8, WebStorm 11) is the new minimum version required for this release.

=== 0.14.3

- Fix problem in syntax highlighting leading to PSI Parser Exceptions
- disable automatically refreshing images on JavaFX (to be re-enabled in 0.15.x)

=== 0.14.2

- Performance improvement: render preview only when visible
- Don't show AsciiDoc preview actions in other Editors
- additional compatibility fixes for IntelliJ 15.x

=== 0.14.1

- make compatible with IntelliJ 15.x again. +
  This should include: AppCode 3.3, CLion 1.2, DataGrip 1.0, PhpStorm 10, PyCharm 5, RubyMine 8, WebStorm 11

=== 0.14

- New JavaFX preview and real split view
- Update to asciidoctorj 1.5.4.1 and asciidoctorj-diagram 1.5.0

=== 0.13

- Updated to asciidoctorj 1.5.3.2, added support for asciidoctor-diagram

=== 0.12

- Bugfixes, new makelink action, table generation improvement, etc.

=== 0.11

- Removed AsciiDoc item in right click menu thanks to Dmitry Jemerov.
- Added 'Open in Browser' menu item.
- Added 40+ live template (access them by pressing Cmd+J, or type 'ad-')

== Features

* Since 0.8 Fixed incompatibility with non-IDEA IDE's, thanks to Harro Lissenberg
* Since 0.7: Right click on a document to apply basic formatting or create tables.
* Since 0.6: refactor Markdown to AsciiDoc. Right click on a file, or use the Refactor menu, and the Markdown document
will be replaced by the AsciiDoc equivalent. Also supports undo, in case you're not happy with the result!
* Since 0.4: recognizes the AsciiDoc file extension (.adoc, .asciidoc, .ad)
* Since 0.4: provides a two-pane AsciiDoc preview editor based on https://github.com/asciidoctor/asciidoctorj[AsciidoctorJ] with Live preview.

If you are missing features, please don't hesitate to let me know on Twitter: http://www.twitter.com/epragt[@epragt] or make an issue in the issue tracker!

== Dependencies

This project uses AsciiDoctorJ and JRuby for the rendering of the AsciiDoc content.

For the conversion of Markdown to AsciiDoc, we use Pegdown and the https://github.com/bodiam/markdown-to-asciidoc[Markdown to AsciiDoc] converter.

== Build

This plugin is built using Gradle.
If you build or run it the first time it will download the community edition of IntelliJ automatically.

If you have developed the plugin before it changed to Gradle you might want to remove the contents of your `.idea` folder to trigger a re-import of the Gradle project.

To build this plugin, you need to run:

----
./gradlew -Dfile.encoding=UTF-8 buildPlugin
----

The ZIP file with plugin to distribute will be located in `build/distributions`.

To run the plugin for development you'll need to start

----
./gradlew -Dfile.encoding=UTF-8 runIde
----

== Copyright and Licensing

Copyright (C) 2013-2017 Julien Viet and Erik Pragt.
Released under the Apache License, Version 2.0 (see link:LICENSE[LICENSE]).

== Credits

This plugin is based on the https://github.com/nicoulaj/idea-markdown[Intellij Markdown plugin by Julien Nicoulaud].

Also, great help was received from Harro Lissenberg, Alexander Schwartz and Dan Allen. Thank you all for your support!

= IntelliJ AsciiDoc Plugin
Erik Pragt
:experimental:

A plugin for the IntelliJ platform (IntelliJ IDEA, RubyMine, etc) that provides support for the http://www.asciidoc.org[AsciiDoc] markup language. You can install the plugin (named "AsciiDoc") from the plugins section inside your Jetbrains IDE or download it from the https://plugins.jetbrains.com/plugin/7391[Jetbrains Plugin Repository].

image::https://hacktoberfest.digitalocean.com/assets/logo-hacktoberfest-658b5aa2bd34e782d29c40bf6afbdff00f20fe1328efa6da17743878ba8db66f.png[float=left,width=200]

This plugin joined https://hacktoberfest.digitalocean.com/[Hacktoberfest]!
Issues that can give you a start are https://github.com/asciidoctor/asciidoctor-intellij-plugin/issues?q=is%3Aissue+is%3Aopen+label%3AHacktoberfest[marked with the label "Hacktoberfest"], but you can choose any ticket you want to participate (and even create pull requests without a prior ticket).
If you want to discuss ideas and create pull requests you can meet Alexander, one of the maintainers, at the https://www.eventbrite.com/e/hacktoberfest-frankfurt-2018-tickets-50225231018[Frankfurt/Main Hacktober Fest in Germany on October 12th].

If you want to use the JavaFX instead of the Swing preview, you'll need to run IntelliJ with 64bit Java.
From 2017.1 onwards 64bit Java is included even in the Windows versions.
Please only use the JDK provided by JetBrains, as the JavaFX rendering seems to be most stable in the JetBrains JDK.

== Release notes

=== 0.21.1

- allow attributes to be pre-defined in plugin settings (#216)

=== 0.21.0 (preview, available from Github releases)

- Update to AsciidoctorJ 1.5.7 and Asciidoctor Diagram 1.5.9
- Treat "line must be non negative" only as a warning (#212)

=== 0.20.6

- Display all PlantUML graphics as PNG for preview (#170)

=== 0.20.5

- Adding hiDPI support for JavaFX preview (#125)

=== 0.20.4

- Requiring 2017.1 as minimum for this plugin (#207)

=== 0.20.3 (preview, available from Github releases)

- Avoiding deadlock on JavaFX initialization (#207)
- Requiring 2017.2 as minimum for this plugin

=== 0.20.2

- Dejavu fonts now display chinese characters within tables (#203)

=== 0.20.1

- Upgrading to asciidoctorj-diagram 1.5.8
- Dejavu fonts now display chinese characters (#203)

=== 0.20.0

- Add MathJax support in JavaFX preview #201
- JavaFX preview is now the default for new installations of the plugin
- Include DejaVu fonts for improved and consistent preview #184

=== 0.19.2

- Fix NullPointerExceptions when used with IntelliJ Language Injection and Fragment Editor #194

=== 0.19.1

- Support inspections to convert markdown and old style AsciiDoc headings to modern AsciiDoc headings #185
- JRuby runtime updated to 9.1.8.0 to work with recent JDK versions (still, internal Jetbrains JRE is the only supported version) #187

=== 0.19.0

- Support Icon fonts (thanks to @matthiasbalke) / #182
- Update to asciidoctorj-1.5.6 (aka asciidoctor-1.5.6.1) and asciidoctorj-diagram-1.5.4.1
- Support "search everywhere" (double Shift) and "goto by name - Symbol..." (Ctrl+Shift+Alt+N) for all AsciiDoc section headings - just enter a part of the heading
- Support Markdown style sections (starting with '#') in syntax highlighting

=== 0.18.2 (preview, available from Github releases)

- Headings in Darcula theme preview are now light grey for better readability

=== 0.18.1

- Improved handling for non-printable characters in syntax highlighting

=== 0.18.0 (preview, available from Github releases)

- Update to asciidoctor 1.5.5/asciidoctor-diagram 1.5.4
- Capture Asciidoctor messages on stdout/stderr and write them to IDE notifications
- Close files when images are shown in preview
- Set focus in editor when re-opening file
- Fix "line must be non negative" error when clicking on preview

=== 0.17.3

- Make click-on-link-to-open and click-on-preview-to-set-cursor in JavaFX preview compatible with Java 8 u111+
- Formatting actions from the toolbar should not throw exceptions when triggered at the beginning or end of the document

=== 0.17.2

- Plugin is now build using the https://gradle.org/[Gradle] and https://github.com/JetBrains/gradle-intellij-plugin[gradle-intellij-plugin]
This should make contributing and releasing easier. Thanks Jiawen Geng!
- Asciidoctor's temporary files are now created in a temporary folder per opened document. Thanks @agorges!

=== 0.17.1 (preview, available from Github releases)

- Improved handling of trailing spaces in syntax highlighting.
- Fixed code/preview sync for nested HTML (i.e. NOTE)

=== 0.17.0 (preview, available from Github releases)

- Updated block parsing to support two styles of headings.
- Block starts and ends are need to be aligned in length and shape when parsed.

=== 0.16.4

- Improved darcula support for JavaFX. More block types are using proper dark background and light text colors.

=== 0.16.3

- Theme in preview can be switched from light to darcula independent of IDE theme

=== 0.16.2

- Handling of Linux and MacOS file names for image preview in JavaFX

=== 0.16.1

- Added darcula theme for JavaFX preview
- Clicking on JavaFX preview will set cursor position in editor (thanks to @kastork for the idea)

=== 0.15.4

- setScene now called from FxThread instead of AWT thread to avoid blocking GUI on MacOS

=== 0.15.3

- Initialization message appears only during initialization
- No error message if user switches to a setup where JavaFX preview is no longer available.

=== 0.15.2 (preview, available from Github releases)

- fixed detection of Mac 64 JVM to be able to activate JavaFX preview
- click-on-url for JavaFX improved, when slow-loading external images are referenced

=== 0.15.1 (preview, available from Github releases)

- revised constrained/unconstrained detection
- Fix problem in syntax highlighting leading to PSI Parser Exceptions
- refreshing images on JavaFX only if their content has changed to save memory consumption
- Limiting JavaFX preview to 64bit platforms due to problems especially with Windows OpenJDK 32bit (as default on Windows).

=== 0.15.0 (preview, available from Github releases)

- correct usage of constrained/unconstrained AsciiDoc formatting
- JavaFX Preview will automatically scroll to the cursor position of the editor
- JavaFX preview will automatically open links in the systems's default browser
- Caching rendering instances of Asciidoctor for better performance

IntelliJ 15 (including AppCode 3.3, CLion 1.2, DataGrip 1.0, PhpStorm 10, PyCharm 5, RubyMine 8, WebStorm 11) is the new minimum version required for this release.

=== 0.14.3

- Fix problem in syntax highlighting leading to PSI Parser Exceptions
- disable automatically refreshing images on JavaFX (to be re-enabled in 0.15.x)

=== 0.14.2

- Performance improvement: render preview only when visible
- Don't show AsciiDoc preview actions in other Editors
- additional compatibility fixes for IntelliJ 15.x

=== 0.14.1

- make compatible with IntelliJ 15.x again. +
  This should include: AppCode 3.3, CLion 1.2, DataGrip 1.0, PhpStorm 10, PyCharm 5, RubyMine 8, WebStorm 11

=== 0.14

- New JavaFX preview and real split view
- Update to asciidoctorj 1.5.4.1 and asciidoctorj-diagram 1.5.0

=== 0.13

- Updated to asciidoctorj 1.5.3.2, added support for asciidoctor-diagram

=== 0.12

- Bugfixes, new makelink action, table generation improvement, etc.

=== 0.11

- Removed AsciiDoc item in right click menu thanks to Dmitry Jemerov.
- Added 'Open in Browser' menu item.
- Added 40+ live template (access them by pressing Cmd+J, or type 'ad-')

== Features

* Since 0.8 Fixed incompatibility with non-IDEA IDE's, thanks to Harro Lissenberg
* Since 0.7: Right click on a document to apply basic formatting or create tables.
* Since 0.6: refactor Markdown to AsciiDoc. Right click on a file, or use the Refactor menu, and the Markdown document
will be replaced by the AsciiDoc equivalent. Also supports undo, in case you're not happy with the result!
* Since 0.4: recognizes the AsciiDoc file extension (.adoc, .asciidoc, .ad)
* Since 0.4: provides a two-pane AsciiDoc preview editor based on https://github.com/asciidoctor/asciidoctorj[AsciidoctorJ] with Live preview.

If you are missing features, please don't hesitate to let me know on Twitter: http://www.twitter.com/epragt[@epragt] or make an issue in the issue tracker!

== Dependencies

This project uses AsciiDoctorJ and JRuby for the rendering of the AsciiDoc content.

For the conversion of Markdown to AsciiDoc, we use Pegdown and the https://github.com/bodiam/markdown-to-asciidoc[Markdown to AsciiDoc] converter.

== Build

This plugin is built using Gradle.
If you build or run it the first time it will download the community edition of IntelliJ automatically.

If you have developed the plugin before it changed to Gradle you might want to remove the contents of your `.idea` folder to trigger a re-import of the Gradle project.

To build this plugin, you need to run:

----
./gradlew -Dfile.encoding=UTF-8 buildPlugin
----

The ZIP file with plugin to distribute will be located in `build/distributions`.

To run the plugin for development you'll need to start

----
./gradlew -Dfile.encoding=UTF-8 runIde
----

== Copyright and Licensing

Copyright (C) 2013-2017 Julien Viet and Erik Pragt.
Released under the Apache License, Version 2.0 (see link:LICENSE[LICENSE]).

== Credits

This plugin is based on the https://github.com/nicoulaj/idea-markdown[Intellij Markdown plugin by Julien Nicoulaud].

Also, great help was received from Harro Lissenberg, Alexander Schwartz and Dan Allen. Thank you all for your support!


updated readme

updated readme

= WebApp Tutorial

This is tutorial material for building web apps with Spring Boot, Spring Data Rest, AnguluarJS and TypeScript.

== Used Technologies

* http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html[Java 8] for the REST services
* https://www.typescriptlang.org/[Typescript] for the web client
* http://stateless.co/hal_specification.html[HAL] (Hypertext Application Language) fpr hypermedia
* http://projects.spring.io/spring-boot/[Spring Boot] (+ Data, REST, HATEOAS)
* http://angular.io/[Angular 2] for web client
* http://junit.org/[JUnit] for Java unit and integration testing
* https://code.google.com/p/mockito/[Mockito] for Mocking
* http://www.gradle.org/[Gradle] as build system
* Node.js, npm, Bower, typings, webpack for the web client build

== Requirements

* Java 8 (JDK) installed

You don't need to install Node.js and all the JavaScript tooling,
since those tools are installed automatocally by the Gradle build.
But it would be convenient to have those tolls installed
if you want to use theme directly instead of using the Gradle wrapper tasks.

* Optional
** Node.js and npm installed
** TypeScript installed (npm install -g typescript)
** Bower installed (npm install -g bower)
** Typings installed (npm install -g typings)

In the vagrant directory you find a Vagrantfile to create a (German) development environment.

* Install Vagrant and VirtualBox
* Invoke "vagrant up" in a terminal
* Wait for 20 minutes letting Vagrant create the whole virtual machine
* In the VM, log in as vagrant/vagrant and then invoke: startx
* The latest Ubuntu with a simple desktop will start up
* You find this project at /home/vagrant/webapp-tutorial
* All Gradle and JavaScript dependencies are already in the VM
* You find an IntelliJ IDEA trial under /opt
* Before starting IntelliJ you have to configure the Java 8 JDK
* After starting IntelliJ you have to install the Lombok plugin manually.

== Getting Started

When you want to run the tutorial locally, prepare all the labs:

* ./gradlew prepareJs (installs all node modules, typings and other dependencies in all labs)
* ./gradlew clean build (builds all the tutorial labs (Java parts + JavaScript parts), runs all the Java tests)

= WebApp Tutorial

This is tutorial material for building web apps with Spring Boot, Spring Data Rest, AnguluarJS and TypeScript.

== Used Technologies

* Java 7 or 8
* http://stateless.co/hal_specification.html[HAL] (Hypertext Application Language)
* http://projects.spring.io/spring-boot/[Spring Boot] (+ Data, REST, HATEOAS)
* http://www.typescriptlang.org/[TypeScript] for web client
* http://angularjs.org/[AngularJS] for web client
* http://junit.org/[JUnit] for Java unit and integration testing
* https://code.google.com/p/mockito/[Mockito] for Mocking
* http://www.gradle.org/[Gradle] as build system
* NPM, Grunt, Bower, TSG for the web client build

== Requirements

* Java 7 or 8 (JDK) installed
* Node.js installed
** Grunt CLI installed (npm install -g grunt-cli)
** Bower installed (npm install -g bower)
** TSD installed (npm install -g tsd)

In the vagrant directory you find a Vagrantfile to create a (German) development environment.

* Install Vagrant and VirtualBox
* Invoke "vagrant up" in a terminal
* Wait for 20 minutes letting Vagrant create the whole virtual machine
* In the VM, log in as vagrant/vagrant and then invoke: startx
* The latest Ubuntu with a simple desktop will start up
* You find this project at /home/vagrant/webapp-tutorial
* All Gradle and JavaScript dependencies are already in the VM
* You find an IntelliJ IDEA trial under /opt
* Before starting IntelliJ you have to configure the Java 8 JDK
* After starting IntelliJ you have to install the Lombok plugin manually.

== Getting Started

When you want to run the tutorial locally, prepare all the labs:

* ./gradlew prepareJs (invokes npm install, bower install, tsd reinstall on all JavaScript projects)
* ./gradlew clean build (builds all the tutorial labs (Java parts), runs all the Java tests)


Updated documentation

Updated documentation

= assertj-swagger
:author: Robert Winkler
:version: 0.1.1
:hardbreaks:

image:https://travis-ci.org/RobWin/assertj-swagger.svg["Build Status", link="https://travis-ci.org/RobWin/assertj-swagger"] image:https://coveralls.io/repos/RobWin/assertj-swagger/badge.svg?branch=master["Coverage Status", link="https://coveralls.io/r/RobWin/assertj-swagger"] image:https://api.bintray.com/packages/robwin/maven/assertj-swagger/images/download.svg[link="https://bintray.com/robwin/maven/assertj-swagger/_latestVersion"] image:http://img.shields.io/badge/license-ASF2-blue.svg["Apache License 2", link="http://www.apache.org/licenses/LICENSE-2.0.txt"]

== Overview

assertj-swagger is a https://github.com/joel-costigliola/assertj-core[assertj] library which compares a contract-first https://github.com/swagger-api/swagger-spec[Swagger] YAML/JSON file with a code-first Swagger JSON output (e.g. from https://github.com/springfox/springfox[springfox] or https://github.com/swagger-api/swagger-core/wiki/Java-JAXRS-Quickstart[JAX-RS Swagger]). assertj-swagger allows to validate that the API implementation is in compliance with the contract specification. The library supports the Swagger 1.2 and 2.0 specification for the code-first Swagger JSON, but only 2.0 for the contract-first Swagger file.
assertj-swagger compares Swagger objects like Paths, Parameters and Definitions. It does not compare __unimportant__ Swagger objects like info, descriptions or summaries.

== Usage guide

=== Adding assertj-swagger to your project
The project is published in JCenter and Maven Central.

==== Maven

[source,xml]
----
<repositories>
    <repository>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
        <id>central</id>
        <name>bintray</name>
        <url>http://jcenter.bintray.com</url>
    </repository>
</repositories>

<dependency>
    <groupId>io.github.robwin</groupId>
    <artifactId>assertj-swagger</artifactId>
    <version>0.1.1</version>
</dependency>
----

==== Gradle

[source,groovy]
----
repositories {
    jcenter()
}

compile "io.github.robwin:assertj-swagger:0.1.1"
----

=== Using assertj-swagger in an integration test

Using assertj-swagger is simple. For example, if you are using https://github.com/spring-projects/spring-boot[Spring Boot] and https://github.com/springfox/springfox[springfox] or https://github.com/swagger-api/swagger-core/wiki/Java-JAXRS-Quickstart[JAX-RS Swagger], you can validate your Swagger JSON in an integration test.

[source, java]
----
@RunWith(SpringJUnit4ClassRunner.class)
@SpringApplicationConfiguration(classes = Application.class)
@IntegrationTest
@WebAppConfiguration
public class AssertjSwaggerTest {
    @Test
    public void validateThatImplementationFitsDesignSpecification(){
        String designFirstSwagger = SwaggerAssertTest.class.getResource("/swagger.yaml").getPath();
        SwaggerAssertions.assertThat("http://localhost:8080/v2/api-docs")
            .isEqualTo(designFirstSwagger);
    }
}
----

==== Example output

Assertj-swagger fails a test if it finds differences between the implementation and the specification.

[source]
----
The following 4 assertions failed:
1) [Checking Paths]
Expecting:
  <["/api/pet", "/api/pet/findByStatus", "/api/pet/findByTags", "/api/pet/{petId}", "/api/store/order", "/api/store/order/{orderId}", "/api/user", "/api/user/createWithArray", "/api/user/createWithList", "/api/user/login", "/api/user/logout", "/api/user/{username}"]>
to contain only:
  <["/pets", "/pets/findByStatus", "/pets/findByTags", "/pets/{petId}", "/stores/order", "/stores/order/{orderId}", "/users", "/users/createWithArray", "/users/createWithList", "/users/login", "/users/logout", "/users/{username}"]>
elements not found:
  <["/pets/findByTags", "/users/logout", "/users", "/stores/order", "/users/createWithArray", "/pets", "/users/createWithList", "/pets/findByStatus", "/pets/{petId}", "/users/{username}", "/stores/order/{orderId}", "/users/login"]>
and elements not expected:
  <["/api/store/order", "/api/user", "/api/user/createWithList", "/api/pet", "/api/pet/findByTags", "/api/user/createWithArray", "/api/user/login", "/api/pet/{petId}", "/api/store/order/{orderId}", "/api/user/{username}", "/api/pet/findByStatus", "/api/user/logout"]>

2) [Checking properties of definition 'Order']
Expecting:
  <["complete", "id", "identifier", "petId", "quantity", "shipDate", "status"]>
to contain only:
  <["id", "petId", "quantity", "shipDate", "status", "complete"]>
elements not found:
  <[]>
and elements not expected:
  <["identifier"]>

3) [Checking properties of definition 'User']
Expecting:
  <["email", "firstName", "id", "identifier", "lastName", "password", "phone", "userStatus", "username"]>
to contain only:
  <["id", "username", "firstName", "lastName", "email", "password", "phone", "userStatus"]>
elements not found:
  <[]>
and elements not expected:
  <["identifier"]>

4) [Checking properties of definition 'Pet']
Expecting:
  <["category", "id", "identifier", "name", "photoUrls", "status", "tags"]>
to contain only:
  <["id", "category", "name", "photoUrls", "tags", "status"]>
elements not found:
  <[]>
and elements not expected:
  <["identifier"]>
----

=== Using assertj-swagger in an unit test

If you are using the https://github.com/spring-projects/spring-framework[spring-framework] and https://github.com/springfox/springfox[springfox], Spring's MVC Test framework can also be used to validate the Swagger JSON output against your contract-first Swagger specification.
That way you can make sure that the implementation is in compliance with the design specification.

[source, java]
----
@Test
public void validateThatImplementationFitsDesignSpecification() throws Exception {
    String designFirstSwaggerLocation = Swagger2MarkupTest.class.getResource("/swagger.yaml").getPath();

    MvcResult mvcResult = this.mockMvc.perform(get("/v2/api-docs")
            .accept(MediaType.APPLICATION_JSON))
            .andExpect(status().isOk())
            .andReturn();

    String springfoxSwaggerJson = mvcResult.getResponse().getContentAsString();
    SwaggerAssertions.assertThat(Swagger20Parser.parse(springfoxSwaggerJson)).isEqualTo(designFirstSwaggerLocation);
}
----

== License

Copyright 2015 Robert Winkler

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

= assertj-swagger
:author: Robert Winkler
:version: 0.1.1
:hardbreaks:

image:https://travis-ci.org/RobWin/assertj-swagger.svg["Build Status", link="https://travis-ci.org/RobWin/assertj-swagger"] image:https://coveralls.io/repos/RobWin/assertj-swagger/badge.svg?branch=master["Coverage Status", link="https://coveralls.io/r/RobWin/assertj-swagger"] image:https://api.bintray.com/packages/robwin/maven/assertj-swagger/images/download.svg[link="https://bintray.com/robwin/maven/assertj-swagger/_latestVersion"] image:http://img.shields.io/badge/license-ASF2-blue.svg["Apache License 2", link="http://www.apache.org/licenses/LICENSE-2.0.txt"]

== Overview

assertj-swagger is a https://github.com/joel-costigliola/assertj-core[assertj] library which compares a contract-first https://github.com/swagger-api/swagger-spec[Swagger] YAML/JSON file with a code-first Swagger JSON output (e.g. from https://github.com/springfox/springfox[springfox] or https://github.com/swagger-api/swagger-core/wiki/Java-JAXRS-Quickstart[JAX-RS Swagger]). assertj-swagger allows to validate that the API implementation is in compliance with the contract specification. The library supports the Swagger 1.2 and 2.0 specification for the code-first Swagger JSON, but only 2.0 for the contract-first Swagger file.
assertj-swagger compares Swagger objects like Paths, Parameters and Definitions. It does not compare __unimportant__ Swagger objects like info, descriptions or summaries.

== Usage guide

=== Adding assertj-swagger to your project
The project is published in JCenter and Maven Central.

==== Maven

[source,xml]
----
<repositories>
    <repository>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
        <id>central</id>
        <name>bintray</name>
        <url>http://jcenter.bintray.com</url>
    </repository>
</repositories>

<dependency>
    <groupId>io.github.robwin</groupId>
    <artifactId>assertj-swagger</artifactId>
    <version>0.1.1</version>
</dependency>
----

==== Gradle

[source,groovy]
----
repositories {
    jcenter()
}

compile "io.github.robwin:assertj-swagger:0.1.1"
----

=== Using assertj-swagger in an integration test

Using assertj-swagger is simple. For example, if you are using https://github.com/spring-projects/spring-boot[Spring Boot] and https://github.com/springfox/springfox[springfox] or https://github.com/swagger-api/swagger-core/wiki/Java-JAXRS-Quickstart[JAX-RS Swagger], you can validate your Swagger JSON in an integration test.

[source, java]
----
@RunWith(SpringJUnit4ClassRunner.class)
@SpringApplicationConfiguration(classes = Application.class)
@IntegrationTest
@WebAppConfiguration
public class AssertjSwaggerTest {
    @Test
    public void validateThatImplementationFitsDesignSpecification(){
        String designFirstSwagger = SwaggerAssertTest.class.getResource("/swagger.yaml").getPath();
        SwaggerAssertions.assertThat("http://localhost:8080/v2/api-docs")
            .isEqualTo(designFirstSwagger);
    }
}
----

==== Example output

[source]
----
The following 4 assertions failed:
1) [Checking Paths]
Expecting:
  <["/api/pet", "/api/pet/findByStatus", "/api/pet/findByTags", "/api/pet/{petId}", "/api/store/order", "/api/store/order/{orderId}", "/api/user", "/api/user/createWithArray", "/api/user/createWithList", "/api/user/login", "/api/user/logout", "/api/user/{username}"]>
to contain only:
  <["/pets", "/pets/findByStatus", "/pets/findByTags", "/pets/{petId}", "/stores/order", "/stores/order/{orderId}", "/users", "/users/createWithArray", "/users/createWithList", "/users/login", "/users/logout", "/users/{username}"]>
elements not found:
  <["/pets/findByTags", "/users/logout", "/users", "/stores/order", "/users/createWithArray", "/pets", "/users/createWithList", "/pets/findByStatus", "/pets/{petId}", "/users/{username}", "/stores/order/{orderId}", "/users/login"]>
and elements not expected:
  <["/api/store/order", "/api/user", "/api/user/createWithList", "/api/pet", "/api/pet/findByTags", "/api/user/createWithArray", "/api/user/login", "/api/pet/{petId}", "/api/store/order/{orderId}", "/api/user/{username}", "/api/pet/findByStatus", "/api/user/logout"]>

2) [Checking properties of definition 'Order']
Expecting:
  <["complete", "id", "identifier", "petId", "quantity", "shipDate", "status"]>
to contain only:
  <["id", "petId", "quantity", "shipDate", "status", "complete"]>
elements not found:
  <[]>
and elements not expected:
  <["identifier"]>

3) [Checking properties of definition 'User']
Expecting:
  <["email", "firstName", "id", "identifier", "lastName", "password", "phone", "userStatus", "username"]>
to contain only:
  <["id", "username", "firstName", "lastName", "email", "password", "phone", "userStatus"]>
elements not found:
  <[]>
and elements not expected:
  <["identifier"]>

4) [Checking properties of definition 'Pet']
Expecting:
  <["category", "id", "identifier", "name", "photoUrls", "status", "tags"]>
to contain only:
  <["id", "category", "name", "photoUrls", "tags", "status"]>
elements not found:
  <[]>
and elements not expected:
  <["identifier"]>
----

=== Using assertj-swagger in an unit test

If you are using the https://github.com/spring-projects/spring-framework[spring-framework] and https://github.com/springfox/springfox[springfox], Spring's MVC Test framework can also be used to validate the Swagger JSON output against your contract-first Swagger specification.
That way you can make sure that the implementation is in compliance with the design specification.

[source, java]
----
@Test
public void validateThatImplementationFitsDesignSpecification() throws Exception {
    String designFirstSwaggerLocation = Swagger2MarkupTest.class.getResource("/swagger.yaml").getPath();

    MvcResult mvcResult = this.mockMvc.perform(get("/v2/api-docs")
            .accept(MediaType.APPLICATION_JSON))
            .andExpect(status().isOk())
            .andReturn();

    String springfoxSwaggerJson = mvcResult.getResponse().getContentAsString();
    SwaggerAssertions.assertThat(Swagger20Parser.parse(springfoxSwaggerJson)).isEqualTo(designFirstSwaggerLocation);
}
----

== License

Copyright 2015 Robert Winkler

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


Test commit #3

Test commit #3

:experimental:

image:https://travis-ci.org/jMonkeyEngine/wiki.svg?branch=master["Build Status", link="https://travis-ci.org/jMonkeyEngine/wiki"]

= jMonkeyEngine Documentation

see link:https://jmonkeyengine.github.io/wiki/documentation[https://jmonkeyengine.github.io/wiki/documentation]

The project to store, edit, and generate the documentation of http://jmonkeyengine.org[jMonkeyEngine].

The documentation (<<src/docs/asciidoc>>) is editable :

* online via github (Edit button located at top of the Wiki page + Pull Request)
* offline with Netbeans after local `git clone` + open
* offline with Atom editor, see link:https://jmonkeyengine.github.io/wiki/wiki/atom_editor.html[Atom Editor for Wiki Editing]

.Prerequisites
.  Have a link:https://github.com/[GitHub account].
.  Optional: Are a Wiki project member.

If you are not a member, you can fork the repository into your GitHub account and issue pull requests from there or
online via github. (Edit button located at top of the Wiki page + Pull Request)

To fork the Wiki repository into your GitHub Account:

*  In the menu at the top of the page, select the *Fork* button.

The syntax is asciidoc :

*  link:http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Asciidoc Syntax Quick Reference]
*  link:http://asciidoctor.org/docs/user-manual/#introduction-to-asciidoctor[Asciidoctor User Manual]

An easy to use primer for GitHub commands can be found here:

*  link:http://rogerdudler.github.io/git-guide/[git - the simple guide]

== Contribute

There are a few simple rules to follow when contributing.

. It's not required but it's a good idea to give a heads up you made a P/R on the link:https://hub.jmonkeyengine.org/[jMonkeyEngine Forum] under the `Documentation` topic.
.  When adding documents, make sure to always complete the header of your document first.
** see link:https://jmonkeyengine.github.io/wiki/wiki/wiki_header.html[Anatomy of a Wiki Header]
.  When linking to other Wiki pages, always use an "`Inter-Document Cross Reference`" with the format,
** ++<<path/to/wiki/page#,custom label text>>++ +
The `#` sign substitutes for the file extension. This type of link will first look for the `.adoc` file and if not found default to the `.html` version.
+
The path should be relative to the `asciidoc` folder.
+
For example: `++<<jme3/requirements#,Software and hardware requirements>>++` +
links to the `requirements.adoc` page, which lives in a sub-folder of `asciidoc` named `jme3`.
+
See link:http://asciidoctor.org/docs/user-manual/#inter-document-cross-references[http://asciidoctor.org/docs/user-manual/#inter-document-cross-references] for more info.
.  When linking to images stored in the wiki repository, always use an image prefix in front of the file name and square brackets after it with the format,
**  Image on its own line  - `image::path/to/image.jpg[image alt text,width=" ",height=" ", align=" "]`
+
For example: `++image::jme3/beginner/beginner-assets-models.png[beginner-assets-models.png,320,250,align="center"]++`
+
*  This image is on its own line.
*  Is stored in the `jme3/beginner` folder which lives in the `images` folder.
*  Is named `beginner-assets-models.png`.
*  Has a `alt text` name of `beginner-assets-models.png`.
*  Has a width of 320.
*  Has a height of 250.
*  Is aligned in the center of the page.
**  If you want to include an image inline, use the `image:` prefix instead (notice there is only one colon):
+
See link:http://asciidoctor.org/docs/user-manual/#images[http://asciidoctor.org/docs/user-manual/#images] for in depth instructions.

== Build

*  In Netbeans, convert the AsciiDoc to HTML5 by invoking the 'asciidoctor' goal:
+
[source]
----
 $ ./gradlew asciidoctor
----
+
Open the file _build/asciidoc/html5/index.html_  in your browser to see the generated HTML file.

*  In Atom, you see real time changes when using the `AsciiDoc Preview` (kbd:[ctrl]+kbd:[shift]+kbd:[A] or `menu:Packages[AsciiDoc Preview>Toggle Preview]`). No build is required.

== TODO

- [x] configure travis build
- [x] configure github + gradle + travis to publish on gh-pages branches
- [x] find and fixe conversion bug
- [x] complete conversion: note, warning, ...
- [x] fix warning during html's generation (should be fixed manually)
- [x] add meta info during conversion (doctitle, revision, tags, ...)
- [x] add a home page (index.html)
- [ ] add a navigation bar or a menu (?)
- [ ] customize html layout (header, footer, css)
- [x] transfer ownership to jMonkeyEngine org
- [x] complete Doc, how to contribute,...
- [ ] accept Pull Request
- [ ] write a post about the migration (the tools, why asciidoc, vs alternatives, how ...)
- [ ] generate sitemap
- [x] add search box
- [ ] add google analytics (?)
- [ ] support emoji
- [ ] support iframe block
- [x] fix slideshow of "Xxx for Dummies"
- [ ] optimize remove useless images
- [ ] optimize image, use smaller file, eg convert to jpg or to webp, resize
- [ ] organize i18n / lang
- [ ] use tags to create taxonomy