Jbake workshop (Greach 2019)
•
2 recomendaciones•817 vistas
These slides were used as a guide for the workshop about Jbake at Greach 2019
Recomendados
Recomendados
Más contenido relacionado
La actualidad más candente
La actualidad más candente (19)
Similar a Jbake workshop (Greach 2019)
Similar a Jbake workshop (Greach 2019) (20)
Más de Mario García
Más de Mario García (16)
Último
Último (20)
Jbake workshop (Greach 2019)
- 2. Me ● Mario Garcia ● Working at Kaleidos.net ● Mostly Backend Developer (Java, Groovy) ● Some Frontend lately (React, Vue, CSS still not my thing)
- 3. Schedule ● What is JBake and use cases ● Installation ● Basic commands ● Blog ○ Create content ○ Templates ○ Custom content ○ Asciidoctor extensions ○ Push it to Github
- 4. Schedule ● Break (15 min) ● Project OSS ○ Some code in Gradle project ○ Configure bake ○ Include javadoc ○ Include asciidoctor doc
- 5. What is JBake “JBake is a Java based, open source, static site/blog generator for developers & designers”
- 6. Some features ● Self contained ● Integrated with other build tools (Gradle, Maven, SBT…) ● Content formats (asciidoctor, markdown, html) ● Multiple template support ● Draft support ● ….
- 7. Installation Who hasn’t installed JBaked yet ?
- 8. Installation Who hasn’t installed JBaked yet ?
- 9. ● Prerequisites ○ JDK 8 ● Three scenarios ○ Download BINARY directly ○ Install via SDKMAN command line (sdkman.io) ○ Integrate with your favourite BUILDING TOOL Installation
- 10. SDKMAN ● Install sdkman (https://sdkman.io/install) ● Then “sdk install jbake”
- 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. Integrate with your build tool We’ll see an example in the second part of this workshop with Gradle
- 13. Use your favourite IDE ● Use any IDE with syntax highlight for ○ Asciidoctor ○ Markdown ○ HTML ○ Groovy
- 14. Get used with the basics
- 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. 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. Create a new blog
- 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. 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
- 21. About Groovy templates ● No need for enclosing tag. Braces mark the scope
- 22. About Groovy templates ● Plain strings can be inserted using yield or yieldUnscaped
- 23. Lets create a new entry
- 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. 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. Create an entry for today ● Create an asciidoctor file ○ greachblog/content/2019/03/28/greach_jbake_workshop.adoc ● Copy the following content:
- 28. Then bake it and serve it locally ● Execute with -s (it does bake and serve altogether) ○ jbake -s
- 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. 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. 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. ● 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. Custom content
- 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. Videos
- 38. Asciidoctor extensions ● Add extra features to your entries adding extension such as: ○ Comments ○ Render mathematical formulas ○ Diagrams ○ QR Code ○ ...
- 39. Asciidoctor Diagram ● Already added to JBake ● We have to enable it in the jbake.properties
- 40. Create a diagram ● In your asciidoctor content files write a ditaa diagram:
- 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. More extensions ● Asciidoctor site extension list ○ https://asciidoctor.org/docs/extensions/ ● Puravida extensions ○ https://gitlab.com/puravida-software/asciidoctor-extensions
- 43. Add a site to our OSS project
- 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. 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. Clone project git clone https://github.com/mariogarcia/jbake_greach.git
- 47. Add JBake plugin ● In your build.gradle.kts
- 48. Add source code in site
- 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. Include source code in documentation ● Use asciidoctor include directive
- 51. Access javadoc from site
- 52. Include javadoc ● Generate javadoc ● Copy javadoc to jbake output dir ● Add link to javadoc index.html page
- 54. Include javadoc ● Link it from documentation.adoc ● It’s just a relative link to javadoc/index.html
- 55. Include javadoc
- 56. Add Disqus
- 57. Add Disqus ● Add Puravida Extensions
- 58. Add Disqus ● Add disqus directive to documentation.adoc ○ Check https://puravida-software.gitlab.io/asciidoctor-extensions
- 60. Asciidoctor user guide ● Add asciidoctor plugin
- 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. Asciidoctor
- 63. Asciidoctor
- 64. Summary
- 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