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

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

34676b6e108d2752c33c33bf2f47972c?s=128

Robert Muehsig

September 28, 2017
Tweet

Transcript

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

  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
  3. Dokumentieren… … juhu… -.-

  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…“ ☺
  5. „Entwickler“-getriebene Dokumentation

  6. Jekyll!

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

    Server-Runtime
  8. Jekyll: „Simple“! •Deployment: Alles was HTML/CSS/JS ausliefert •Keine Datenbank •Keine

    „Updates“ •Keine Security Patches • Purer Content
  9. Jekyll: „Blog-aware“! •Ausgerichtet auf Blogs •„Posts“ • „Categories“ • „Permalinks“

    • ... • Aber nicht darauf beschränkt
  10. Jekyll – Demo • Am lebenden Beispiel kurz ein Blick

    drauf werfen…
  11. Jekyll – Demo – Recap: “Jekyll” $ cd /mnt/d/Temp/ $

    jekyll new my-awesome-site $ cd /my-awesome-site $ bundle exec jekyll serve
  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
  13. Jekyll Install Quick Start (Windows) – Via Bash on Ubuntu

    Jekyll $ gem install Jekyll bundler “gem” Package Manager in der Ruby Welt
  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
  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
  16. Jekyll – Content is King • *.md-Files • *.html-Files •

    *.* = alles was irgendwie Textbasiert ist
  17. Kurzausflug: Markdown # Überschrift – Hallo! Text _fetter Text_ und

    vll. ein [Link](http://...) * Liste 1 * Liste 2 <p>HTML geht auch!</p>
  18. Kurzausflug: Markdown - Referenzen • „Offiziell“: https://daringfireball.net/projects/markdown/ • Community: http://commonmark.org/

    • GitHub: https://guides.github.com/features/mastering-markdown/
  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/
  20. Jekyll – schauen wir mal genauer…

  21. Jekyll - Aufbau Post / Site / Whatever Layout Layout

    _includes “Data” …
  22. Jekyll Aufbau - Ordner = Blog Post Dir = Out

    Dir = Config = Statische Seite
  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
  24. Jekyll – Install… • Viele Wege führen nach Rom…

  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!
  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
  27. „The Bad Parts“ • Static Sites: • Keine (bzw. wenig)

    Dynamik (Menüs, Kommentare etc.) • Suchen … solala… • Markdown: mal so, mal so…
  28. Demo Time… • Getting started… • Variables • Mehrsprachigkeit •

    Client-Suche…
  29. Demo: docs.OneOffixx.com • Jekyll, gehostet auf GitHub Pages • Dokumentation

    im Markdown Format • Mehrsprachig • „Dev-Freundlich“ • https://github.com/Sevitec/oneoffixx-docs
  30. Demo: blog.codeinside.eu • Jekyll, gehostet auf GitHub Pages • Blogposts

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

    im Markdown Format • Navigation im YAML Header • https://www.einkoffervollerreisen.de/
  32. Alternative zu Jekyll? • https://www.staticgen.com/

  33. DocFX • Static Page Generator • X-Platform Doc Generator •

    „.NET-Affin“ • Swagger Support • „Mächtiger“, aber komplizierter
  34. DocFX – Quick Start • cinst docfx –y • docfx

    init –q • docfx docfx_project\docfx.json --serve