Basta 2017: Jekyll, Markdown & co. (DE)

Talk @ Basta 2017 in German about Jekyll, Markdown & co.

Demos: https://github.com/Code-Inside/Samples/tree/master/2017/jekyll-demo

Transcript

1. Jekyll, Markdown & co.
   Wir bauen uns eine Projektdokumentation!
   

   View Slide

2. Wer bin ich und was mach ich?
   • Robert Mühsig
   • Software Entwickler bei der Sevitec Informatik AG in der Schweiz
   • Microsoft MVP
   • Tech-Stack: „MSFT-lastig“ und Web-affin
   • Blog: https://blog.codeinside.eu
   • Twitter: @robert0muehsig
   

   View Slide

3. Dokumentieren…
   … juhu… -.-
   

   View Slide

4. Motivation für unser Produktteam:
   • „Uneinheitliche“ Dokumentation – Wiki, Word, TFS, OneNote...
   • Dokumentation für:
   • Endbenutzer
   • Support
   • Partner
   • Entwicklung
   „Uh… das war vor 2 Jahren als ich das Modul gebaut habe…“ ☺
   

   View Slide

5. „Entwickler“-getriebene Dokumentation
   

   View Slide

6. Jekyll!
   

   View Slide

7. Jekyll: „Static“!
   •„Statische“ Seiten werden generiert:
   •Pures HTML/CSS/JS
   • Keine Server-Runtime
   

   View Slide

8. Jekyll: „Simple“!
   •Deployment: Alles was HTML/CSS/JS ausliefert
   •Keine Datenbank
   •Keine „Updates“
   •Keine Security Patches
   • Purer Content
   

   View Slide

9. Jekyll: „Blog-aware“!
   •Ausgerichtet auf Blogs
   •„Posts“
   • „Categories“
   • „Permalinks“
   • ...
   • Aber nicht darauf beschränkt
   

   View Slide

10. Jekyll – Demo
    • Am lebenden Beispiel kurz ein Blick drauf werfen…
    

    View Slide

11. Jekyll – Demo – Recap: “Jekyll”
    $ cd /mnt/d/Temp/
    $ jekyll new my-awesome-site
    $ cd /my-awesome-site
    $ bundle exec jekyll serve
    

    View Slide

12. Jekyll Install
    Quick Start (Windows) – Via Bash on Ubuntu
    Make & GCC
    $ sudo -s
    $ apt update
    $ apt install make gcc
    Ruby
    $ apt-add-repository ppa:brightbox/ruby-ng
    $ apt update
    $ apt install ruby2.3 ruby2.3-dev ruby-switch
    

    View Slide

13. Jekyll Install
    Quick Start (Windows) – Via Bash on Ubuntu
    Jekyll
    $ gem install Jekyll bundler
    “gem”
    Package Manager in der Ruby Welt
    

    View Slide

14. Jekyll – Demo – Recap: Jekyll
    $ cd /mnt/d/Temp/
    $ jekyll new my-awesome-site
    $ cd /my-awesome-site
    $ bundle exec jekyll serve
    = Package-Manager (Package “gems”)in der Ruby Welt
    

    View Slide

15. Jekyll – Demo – Recap: Bundler
    $ cd /mnt/d/Temp/
    $ jekyll new my-awesome-site
    $ cd /my-awesome-site
    $ bundle exec jekyll serve
    = Package-Manager (Package “gems”)in der Ruby Welt
    

    View Slide

16. Jekyll – Content is King
    • *.md-Files
    • *.html-Files
    • *.* = alles was irgendwie Textbasiert ist
    

    View Slide

17. Kurzausflug: Markdown
    # Überschrift – Hallo!
    Text _fetter Text_ und vll. ein [Link](http://...)
    * Liste 1
    * Liste 2
    HTML geht auch!
    

    View Slide

18. Kurzausflug: Markdown - Referenzen
    • „Offiziell“: https://daringfireball.net/projects/markdown/
    • Community: http://commonmark.org/
    • GitHub: https://guides.github.com/features/mastering-markdown/
    

    View Slide

19. Kurzausflug: Markdown - Editoren
    • Typora (Win, macOS, Linux)
    https://typora.io/
    • VS Code (Win, macOS, Linux)
    • iA Writer (macOS, iOS, Android)
    https://ia.net/writer/
    

    View Slide

20. Jekyll – schauen wir mal genauer…
    

    View Slide

21. Jekyll - Aufbau
    Post / Site /
    Whatever
    Layout Layout
    _includes
    “Data”
    …
    

    View Slide

22. Jekyll Aufbau - Ordner
    = Blog Post Dir
    = Out Dir
    = Config
    = Statische Seite
    

    View Slide

23. Variables & Data
    {{ page.* }} Page Data im Header YAML
    {{ site.* }} _config.yml
    {{ site.data.* }} Daten aus _data
    {{ site.pages.* }}
    {{ site.posts.* }}
    {{ site. * }}
    Collections
    Posts & Pages sind immer dabei
    {{ content }} Page Content
    

    View Slide

24. Jekyll – Install…
    • Viele Wege führen nach Rom…
    

    View Slide

25. Quick Start on GH Pages
    • https://pages.github.com/
    • gh-page Branch für bestehende Projekte
    • /docs Folder
    • * Branch
    • GH Pages unterstützt nur wenige Plugins!
    

    View Slide

26. GH Pages: Features
    • Jekyll…
    • Automatischer Build
    • Custom Domains via CNAME
    • Achtung: SSL Support funktioniert nur mit GitHub.io Adressen
    • Workaround z.B. über Cloudflare
    

    View Slide

27. „The Bad Parts“
    • Static Sites:
    • Keine (bzw. wenig) Dynamik (Menüs, Kommentare etc.)
    • Suchen … solala…
    • Markdown: mal so, mal so…
    

    View Slide

28. Demo Time…
    • Getting started…
    • Variables
    • Mehrsprachigkeit
    • Client-Suche…
    

    View Slide

29. Demo: docs.OneOffixx.com
    • Jekyll, gehostet auf GitHub Pages
    • Dokumentation im Markdown Format
    • Mehrsprachig
    • „Dev-Freundlich“
    • https://github.com/Sevitec/oneoffixx-docs
    

    View Slide

30. Demo: blog.codeinside.eu
    • Jekyll, gehostet auf GitHub Pages
    • Blogposts im Markdown Format
    • Mehrsprachig, Clientseitige Suche
    • https://blog.codeinside.eu/
    

    View Slide

31. Demo: EinKofferVollerReisen.de
    • Jekyll, gehostet auf GitHub Pages
    • Blogposts im Markdown Format
    • Navigation im YAML Header
    • https://www.einkoffervollerreisen.de/
    

    View Slide

32. Alternative zu Jekyll?
    • https://www.staticgen.com/
    

    View Slide

33. DocFX
    • Static Page Generator
    • X-Platform Doc Generator
    • „.NET-Affin“
    • Swagger Support
    • „Mächtiger“, aber komplizierter
    

    View Slide

34. DocFX – Quick Start
    • cinst docfx –y
    • docfx init –q
    • docfx docfx_project\docfx.json --serve
    

    View Slide