image:https://raw.github.com/cmoulliard/asciidoctor-hyla/master/hyla_frog.jpg[Hyla, 100, 100, role="left"] **Hyla** is a command line tool to create a new documentation/training/blog/static web site project, add artefacts (articles, blog, audio, video, content, code source, ...), render it in HTML, SlideShow using asciidoc(tro) as markup language. It also support to watch files and render them on the fly for browser configured with Livereload. The content generated is served by a HTTP server.

The Hyla project name comes from an arborical http://en.wikipedia.org/wiki/Hyla[frog] living in equatorial regions of Europe, Asia or Americas. Its name was inspired by the companion of Hercule (Hylas) in Greek mythology.

== Prerequisites

- https://www.ruby-lang.org/en/[Ruby] > 1.9.3
- http://guides.rubygems.org/[RubyGems] to install Ruby Applications

== Installation

Add this line to your application's Gemfile:

    gem 'hyla'

And then execute:

    $ bundle

**Or** install it yourself as:

    $ gem install hyla

== For Developer's only

    gem build hyla.gemspec
    sudo gem install hyla-1.0.gem

== Usage

Open a terminal and move to the folder where you would like to create a new project or develop an existing. As Hyla is command line tool, it will be used with one of the following commands :

    create               Creates a new file from asciidoc artefacts for an existing project
    generate             Generate modules and asciidoc files from an asciidoc Table Of Content file
    help                 Display global or [command] help documentation.
    new                  Creates a new Hyla project using a template or blank to the PATH specified
    serve                Serve locally your site
    watch                Watch directories for any change, add or file deleted and render document (HTML5)

More info about options and commands available can be find by running the `command line tool`

    hyla --help

Here are some examples of commands to create a new project, add artefacts (asciidoc files) watch resources and serve it using HTTP Server

=== New project

A Blank project

    hyla new --blank ~/Temp/MyBlankProject


A  Sample Project using as template --> training

    hyla new --template_type training ~/Temp/MyTrainingProject


=== Add an artefact to a project

Asciidoc(tor) documents

    hyla create --t asciidoc --a article --d ~/Temp/MyBlankProject
    hyla create --t asciidoc  --a audio --d ~/Temp/MyBlankProject
    hyla create --t asciidoc  --a video --d ~/Temp/MyBlankProject
    hyla create --t asciidoc  --a source_highlight --d ~/Temp/MyBlankProject

Slideshow

    hyla create --t slideshow  --a deckjs --d ~/Temp/MyBlankProject

=== Generate Asciidoctor project from a Table of Content

The entry point of a Documention site, Training, Publication or Book will consist most of the time to create
a Table Of Content which is a collection of modules with chapters that we will develop. As this process to elaborate
the structure of the project will consume lot of time/effort, Hyla will simplify your life as it allows from a TOC file


    = A. Introduction module
    >> This is the module 'A. Introduction'
    == 1. Chapter
    This is a chapter about ...
    == 2. Chapter
    This is a Chapter about ...
    === 2.1. Section
    ...
    = B. Instruction module
    >> This is the module 'B. Instruction module'
    == 1. Chapter
    This is a Chapter about ...`

to generate a collection of folders (= modules) containing files which represent the chapters (== Titles of the TOC ).
For each module (= Module), an index file is also created including the files listed in a module. That can be serve to generate a
slideshow presentation using as backend (DeckJS, DZSlides, ...) later on

    hyla generate --p my-project --d ~/Temp/TocProject/  --r toc2html --toc ~/MyProjects/hyla/data/toc.adoc

    >> Project Name : my-project <<
    >> Directory created : ~/Temp/MyBookProject/A_Introduction_module <<
       = File created : 1_Chapter
       = File created : 2_Chapter
       = File created : 3_Chapter
    >> Directory created : ~/Temp/MyBookProject/B_Instruction_module <<
       = File created : 1_Chapter
    >> Directory created : /Users/chmoulli/Temp/MyBookProject/C_Installation_module <<
       = File created : 1_Chapter
       = File created : 2_Chapter

=== Generate HTML pages from Asciidoc

    hyla generate --s ~/Temp/MyTocProject/ --d ~/Temp/MyToCProject/generated_content/ --r adoc2html

=== Watch content Live

While you develop asciidoc(tor) documents, it is interesting to consult the files rendered in HTML. Hyla supports such option with LiverReload
as a WebSocket server is exposed for the browser. To watch files and let's asciidoctor to render them, simply open a terminal and provide as
 parameter the source directory containing the files to be watched.

    hyla watch --s ~/Temp/MyTocProject/ --d ~/Temp/MyTocProject/generated_content/

=== Serve your content locally

To simplify your life, a simple HTTP Server can be started by Hyla and will allow to consult/browse HTML files generated. In this case, start this
Hyla command in another Terminal

    hyla serve -P 4000 -H localhost --out_dir ~/Temp/MyTrainingProject/generated_content/ -b /hyla/