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!
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