The following scenario describes how we can can setup a project using one of the option proposed by Hyla : Create, Generate, Watch, ... === Delete Temp directory rm -rf ~/hyla/MyBlankProject/ rm -rf ~/hyla/MyBookProject rm -rf ~/hyla/MyPdfProject/ rm -rf ~/hyla/MyTocProject/ rm -rf ~/hyla/MyTrainingProject/ rm -rf ~/hyla/MyTrainingExercisesProject/ rm -rf ~/hyla/MyDeckSlideShow/ rm -rf ~/hyla/MyRevealSlideShow/ rm -rf ~/hyla/MyEmailProject/ === Blank Project & Artifacts Using hyla we will create a new project (= directory) and add artifacts (article, audio, video, image, source, table) ==== Create a Blank Project (with or without --force option) hyla new --blank ~/hyla/MyBlankProject hyla new -b ~/hyla/MyBlankProject -f ==== Create a Blank Project without _config.yaml config file, add artifact - Clean and create a MyBlankProject (= directory) using --force option cd ~/hyla rm -rf MyBlankProject/ hyla new -b MyBlankProject -f - Create Asciidoc files from templates (book, article, image, audio, ...) hyla add --t asciidoc -a article -d ~/hyla/MyBlankProject hyla add --t asciidoc -a book -d ~/hyla/MyBlankProject hyla add --t asciidoc -a image -d ~/hyla/MyBlankProject hyla add --t asciidoc -a audio -d ~/hyla/MyBlankProject hyla add --t asciidoc -a video -d ~/hyla/MyBlankProject hyla add --t asciidoc -a source -d ~/hyla/MyBlankProject hyla add --t asciidoc -a table -d ~/hyla/MyBlankProject ==== Create a Blank Project using _config.yaml config file, add artefacts - Clean up project and create a MyBlankProject (= directory) using --force option cd ~/hyla rm -rf MyBlankProject/ # Create a Blank project but containing the yaml config file hyla new -b MyBlankProject cd MyBlankProject - Create Asciidoc files from samples (book, article, image, audio, ...) hyla add --a article hyla add --a book hyla add --a image hyla add --a audio hyla add --a video hyla add --a source hyla add --a table ==== Generate HTML Content of an existing project (asciidoc 2 html) hyla generate -r adoc2html -s ~/hyla/MyBlankProject/ -d ~/hyla/MyBlankProject/generated_content ==== Generate HTML Content of an existing project (asciidoc 2 html) with a different style Styles available : liberation, asciidoctor, colony, foundation, foundation-lime, foundation-potion, github, golo, iconic, maker, readthedocs, riak, rocket-panda, rubygems hyla generate -r adoc2html -s ~/hyla/MyBlankProject/ -d ~/hyla/MyBlankProject/generated_content --style liberation hyla generate -r adoc2html -s ~/hyla/MyBlankProject/ -d ~/hyla/MyBlankProject/generated_content --style github hyla generate -r adoc2html -s ~/hyla/MyBlankProject/ -d ~/hyla/MyBlankProject/generated_content --style foundation ==== Generate HTML Content within project hyla generate -r adoc2html -s . -d generated_content ==== Generate HTML Content within project & using Config File As destination directory is not longer '.' (which is the case when we add artefacts using `hyla add` command, then we must change the destination directory to `generated_content`. the original file is still available as it will backup by ruby ruby -i.bak -pe 'sub(%r{destination: .},"destination: generated_content")' _config.yaml hyla generate hyla generate -y foundation === Project from Template ==== Create a project using a template (training) cd ~/hyla hyla new --t training MyTrainingProject // TODO Refactor Training Exercises Template hyla new --t training-exercises MyTrainingExercisesProject // TODO - Add images hyla new --t book MyBookProject ==== Generate content and watch it cd ~/hyla/MyTrainingProject ruby -i.bak -pe 'sub(%r{destination: .},"destination: generated_content")' _config.yaml hyla generate hyla watch -s ~/hyla/MyTrainingProject/ -d ~/hyla/MyTrainingProject/generated_content === Table Of Content To asciidoc ==== Generate an asciidoctor project from a Table of Content The entry point of a Documentation 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 This is a sub chapter = 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. - Delete existing project cd ~/hyla rm -rf MyTocProject/ - Generate asciidoc files from a Table Of Content (= collection of folders and files) and next HTML hyla generate -r toc2adoc -p my-project -d ~/hyla/MyTocProject/ --toc ~/MyProjects/hyla/data/toc.adoc hyla generate -r adoc2html -s ~/hyla/MyTocProject/ -d ~/hyla/MyTocProject/generated_content Example about what is generated >> Project Name : my-project << >> Directory created : ~/hyla/MyTocProject/A_Introduction_module << = File created : 1_Chapter = File created : 2_Chapter = File created : 3_Chapter >> Directory created : ~/Temp/MyTocProject/B_Instruction_module << = File created : 1_Chapter >> Directory created : /Temp/MyTocProject/C_Installation_module << = File created : 1_Chapter = File created : 2_Chapter - Watch asciidoc files and generate new HTML content when a modification is detected 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 ~/hyla/MyTocProject/ -d ~/hyla/MyTocProject/generated_content ==== Generate an asciidoctor project from a Table of Content using YAML config file and watch content rm -rf ~/hyla/MyTocProject cd ~/hyla hyla new --blank MyTocProject cd MyTocProject hyla generate --r toc2adoc # Change destination in config files or pass info as option # cd ../MyTocProject/ # subl _config.yaml hyla generate -r adoc2html hyla watch -s ~/hyla/MyTocProject/ -d generated_content ==== Generate a DeckJS Slideshow for a module cd ~/hyla/MyTocProject hyla generate --backend deckjs -s A_Introduction_module/ -d A_Introduction_module/generated_content -r index2html ==== Generate a DeckJS Slideshow for a Project (all the TOC) cd ~/hyla/MyTocProject hyla generate --backend deckjs -s . -d generated_content -r index2html ==== Server content locally - HTTP Server 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 -b /hyla/ --out_dir ~/hyla/MyTrainingProject/generated_content/ === Generate a Slideshow ==== DeckJS rm -rf ~/hyla/MyDeckSlideShow cd ~/hyla hyla new -b MyDeckSlideShow hyla add --t slideshow -a deckjs -d MyDeckSlideShow hyla generate --backend deckjs -s ~/hyla/MyDeckSlideShow -d ~/hyla/MyDeckSlideShow/generated_content -r adoc2html ==== Different DeckJS Style options hyla generate --backend deckjs -s ~/hyla/MyDeckSlideShow -d ~/hyla/MyDeckSlideShow/generated_content -r adoc2html -a deckjs_theme=swiss,deckjs_transition=fade hyla generate --backend deckjs -s ~/hyla/MyDeckSlideShow -d ~/hyla/MyDeckSlideShow/generated_content -r adoc2html -a deckjs_theme=web-2.0,deckjs_transition=horizontal-slide ==== RevealJS rm -rf ~/hyla/MyRevealSlideShow cd ~/hyla hyla new -b MyRevealSlideShow hyla add --t slideshow -a revealjs -d MyRevealSlideShow cd MyRevealSlideShow hyla generate --backend revealjs -s . -d generated_content -r adoc2html === Generate a PDF A PDF document can be created using the rendering option `html2pdf`. To render the HTML file, Hyla uses the following Ruby libraries https://github.com/pdfkit/pdfkit[pdfkit] and https://github.com/wkhtmltopdf/wkhtmltopdf[wkhtmltopdf]. - Clean and create a MyPdfProject (= directory) cd ~/hyla rm -rf MyPdfroject/ hyla new -b MyPdfProject --force cd MyPdfProject - Create Asciidoc file from sample (book) hyla add -a book --t asciidoc -d . - Generate HTML content using foundation stylesheet hyla generate --style foundation - We change the rendering from adoc2html to html2pdf ruby -i.bak -pe 'sub(%r{rendering: adoc2html},"rendering: html2pdf")' _config.yaml - Source directory & Destination directory ruby -i.bak -pe 'sub(%r{source: .},"source: ./generated_content")' _config.yaml ruby -i.bak -pe 'sub(%r{destination: generated_content},"destination: ./generated_content/pdf")' _config.yaml - We will generate the PDF file for the image and book hyla generate -f asciidoc_book.html hyla generate -f asciidoc_image.html - Result can be opened and viewed open generated_content/pdf/asciidoc_book.pdf open generated_content/pdf/asciidoc_image.pdf === Send Email An email can be created using as attachment an HTML file based on the information, parameters provided into the _config.yaml file. These parameters will allow to populate the email message and add as attachment the HTML file generated from an asciidoc file. email_attributes: from: "Charles Moulliard " to: 'cmoulliard@apache.com' subject: "This is a beautiful HTML document created by Asciidoctor and Hyla Tool" # GMAIL smtp_server: 'smtp.gmail.com' port: '587' enable_starttls: 'true' user: 'your_gmail_user' password: 'your_gmail_password!' Two new options are required to process the request on the command line or using _config.yaml file source: ./generated_content file: name_of_html_file - Create a Blank project cd ~/hyla rm -rf MyEmailProject/ hyla new -b MyEmailProject --force cd MyEmailProject - Add an asciidoc file (report, doc, book, article) hyla add --a book --d . - Edit the _config.yaml file and add the parameters required (see previously) - Generate HTML content using foundation stylesheet hyla generate --style asciidoctor - Send email to the SMTP server defined hyla sendmail - Consult the message received in your mailbox image::image/email_send.png[]