Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

Robert Muehsig

September 28, 2017
Tweet

More Decks by Robert Muehsig

Other Decks in Programming

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