Se ha denunciado esta presentación.
Utilizamos tu perfil de LinkedIn y tus datos de actividad para personalizar los anuncios y mostrarte publicidad más relevante. Puedes cambiar tus preferencias de publicidad en cualquier momento.

Jbake workshop (Greach 2019)

140 visualizaciones

Publicado el

These slides were used as a guide for the workshop about Jbake at Greach 2019

Publicado en: Software
  • Sé el primero en comentar

Jbake workshop (Greach 2019)

  1. 1. JBake Workshop Mario Garcia
  2. 2. Me ● Mario Garcia ● Working at Kaleidos.net ● Mostly Backend Developer (Java, Groovy) ● Some Frontend lately (React, Vue, CSS still not my thing)
  3. 3. Schedule ● What is JBake and use cases ● Installation ● Basic commands ● Blog ○ Create content ○ Templates ○ Custom content ○ Asciidoctor extensions ○ Push it to Github
  4. 4. Schedule ● Break (15 min) ● Project OSS ○ Some code in Gradle project ○ Configure bake ○ Include javadoc ○ Include asciidoctor doc
  5. 5. What is JBake “JBake is a Java based, open source, static site/blog generator for developers & designers”
  6. 6. Some features ● Self contained ● Integrated with other build tools (Gradle, Maven, SBT…) ● Content formats (asciidoctor, markdown, html) ● Multiple template support ● Draft support ● ….
  7. 7. Installation Who hasn’t installed JBaked yet ?
  8. 8. Installation Who hasn’t installed JBaked yet ?
  9. 9. ● Prerequisites ○ JDK 8 ● Three scenarios ○ Download BINARY directly ○ Install via SDKMAN command line (sdkman.io) ○ Integrate with your favourite BUILDING TOOL Installation
  10. 10. SDKMAN ● Install sdkman (https://sdkman.io/install) ● Then “sdk install jbake”
  11. 11. Download binary ● Go to https://jbake.org/download.html ● Click on the latest distribution ● Decompress the zip wherever you want ● Make sure the jbake command is available in your console path ○ If you’re in linux e.g. modify .bashrc to add jbake command to the $PATH
  12. 12. Integrate with your build tool We’ll see an example in the second part of this workshop with Gradle
  13. 13. Use your favourite IDE ● Use any IDE with syntax highlight for ○ Asciidoctor ○ Markdown ○ HTML ○ Groovy
  14. 14. Get used with the basics
  15. 15. Basic commands ● We’re still playing so create a temporary folder ○ Check JBake help ■ jbake --help ○ Create folder nameofproject ■ jbake -i <nameofproject> ○ Browse the structure with your favourite editor
  16. 16. Basic commands ● Bake content to get html ○ Get into the <nameoftheproject> folder then execute ■ jbake -b ○ That will produce the final output of the blog, to browse it as if it were published online, do: ■ jbake -s
  17. 17. Create a new blog
  18. 18. Create greachblog ● Create the new project using Groovy MTE as template engine ○ jbake -i -t groovy-mte greachblog ● Lets comment on the structure and templates a little bit
  19. 19. Structure ● Directories ○ assets: css, js, images… ○ content: asciidoctor, markdown or html files ○ templates: Templates to interpret content files and produce the final ouput result ● jbake.properties ○ JBake configuration
  20. 20. About Groovy templates
  21. 21. About Groovy templates ● No need for enclosing tag. Braces mark the scope
  22. 22. About Groovy templates ● Plain strings can be inserted using yield or yieldUnscaped
  23. 23. Lets create a new entry
  24. 24. Open the project in your favourite editor ● Mines are (the ones I can help you with) ○ Emacs ○ IntelliJ ● But any editor should work. ● Look for plugins/extensions that could help you rendering/highlighting Markdown or Asciidoctor syntax
  25. 25. Asciidoctor ● “A fast text processor & publishing toolchain for converting AsciiDoc to HTML5, DocBook & more”. ○ Asciidoctor: https://asciidoctor.org/ ○ Syntax Reference: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference
  26. 26. Create an entry for today ● Create an asciidoctor file ○ greachblog/content/2019/03/28/greach_jbake_workshop.adoc ● Copy the following content:
  27. 27. https://asciidoctor.org/docs/asciidoc-syntax-quick-reference
  28. 28. Then bake it and serve it locally ● Execute with -s (it does bake and serve altogether) ○ jbake -s
  29. 29. Modifying templates
  30. 30. I don’t see my name in the entry ● We would like all blog entries to show the name of the author ● What do we need ? ○ Know about the JBAKE DATA MODEL ○ Modify the template to add the property author ○ Bake it again
  31. 31. JBake Data Model ● Global variables: These data variables are available to all templates regardless of the type. ● Page / Post / Custom: Variables for predefined templates as well as any custom templates you created yourself ● Index: The index template has extra data variables available to it related to paging ● Tags: Data related to published tagged documents https://jbake.org/docs/2.6.4/#data_model
  32. 32. Add the author ● Task 1 ○ Go to post-brick.tpl and add the author somewhere ○ Check JBake post related variables https://jbake.org/docs/2.6.4/#data_model
  33. 33. ● Task 2 ○ I would like to write code in its own source file and then show it partially in the blog entry. I also want to be able to download the sample code ■ You can add a :metaproperty: in the asciidoc document header called attached with the name of the script ■ Add the script at the same place as the asciidoc document ■ Add an href in the header to “download” the attached document getting the name from the post headers Attach code to entry
  34. 34. Custom content
  35. 35. Pages, Posts, Tags… Videos ? ● Create a new template named videos.tpl ● The new content of type video should set it in the content file header :type: ● We will pass the youtube video id to the template via content header :video: ● If you want to add a new type of content you should associate the new type of templates in jbake.properties ○ template.<newtype>.tpl=<nameofthetemplate>
  36. 36. Videos
  37. 37. Asciidoctor Extensions
  38. 38. Asciidoctor extensions ● Add extra features to your entries adding extension such as: ○ Comments ○ Render mathematical formulas ○ Diagrams ○ QR Code ○ ...
  39. 39. Asciidoctor Diagram ● Already added to JBake ● We have to enable it in the jbake.properties
  40. 40. Create a diagram ● In your asciidoctor content files write a ditaa diagram:
  41. 41. Add Disqus ● Puravida extensions ○ https://puravida-software.gitlab.io/asciidoctor-extensions/ ● Add the following inline directive to your content file Replace asciidoctor-extensions with the id you registered in Disqus.com
  42. 42. More extensions ● Asciidoctor site extension list ○ https://asciidoctor.org/docs/extensions/ ● Puravida extensions ○ https://gitlab.com/puravida-software/asciidoctor-extensions
  43. 43. Add a site to our OSS project
  44. 44. JBake integrates with build tools ● I’ve got an OSS project and I would like to create the project’s site ○ The project is already using a build tool ○ The project already generates different types of docs you’d like to link from the site ■ Javadocs, using guides...etc ● In this case I’ll be using Gradle ○ www.gradle.org
  45. 45. OSS Project ● Simple Gradle Java Project ○ Site ○ Javadoc ● I would like it to have its own site and integrate the javadoc in it ● Show some source code in the web site
  46. 46. Clone project git clone https://github.com/mariogarcia/jbake_greach.git
  47. 47. Add JBake plugin ● In your build.gradle.kts
  48. 48. Add source code in site
  49. 49. Make asciidoctor content files aware... ● You need to pass where the source files are to being able to include them in the web page ○ Set configuration.asciidoctor.attributes
  50. 50. Include source code in documentation ● Use asciidoctor include directive
  51. 51. Access javadoc from site
  52. 52. Include javadoc ● Generate javadoc ● Copy javadoc to jbake output dir ● Add link to javadoc index.html page
  53. 53. Include javadoc (cont.)
  54. 54. Include javadoc ● Link it from documentation.adoc ● It’s just a relative link to javadoc/index.html
  55. 55. Include javadoc
  56. 56. Add Disqus
  57. 57. Add Disqus ● Add Puravida Extensions
  58. 58. Add Disqus ● Add disqus directive to documentation.adoc ○ Check https://puravida-software.gitlab.io/asciidoctor-extensions
  59. 59. Integrate asciidoc
  60. 60. Asciidoctor user guide ● Add asciidoctor plugin
  61. 61. Asciidoctor ● Generate content (modify src/main/index.adoc) and then ○ ./gradlew ascii ● Copy generated output to jbake output ○ from build/asciidoc/html5 ○ into build/jbake/guide ● Include relative link to user guide in documentation.adoc
  62. 62. Asciidoctor
  63. 63. Asciidoctor
  64. 64. Summary
  65. 65. Summary ● Jbake great for create blog content or micro sites ● Good integration with existing build tools ● Good integration with asciidoctor ● I hope you liked it

×