| layout | title | date | modified_date | author_ids | categories | tags | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Blog Post Anleitung |
2017-08-10 10:25 |
2017-08-18 |
|
|
|
Wenn du das hier liest, bist du vermutlich daran interessiert einen Blog Post für den adesso Blog zu schreiben. Wir haben versucht, den Prozess der Veröffentlichung eines Blog Posts möglichst Entwickler-freundlich zu gestalten, indem wir Blog Posts wie Source Code behandeln. Diese Anleitung beschreibt, was dafür zu tun ist. Es sollte aber nahe an dem sein, was du aus deiner Erfahrung als Softwareentwickler bereits kennst :).
Schaue gerne vor dem Schreiben in die Best Practices zum Schreiben von Blogbeiträgen, wo einige Tipps für einen erfolgreichen Beitrag gesammelt wurden.
Sollte es noch fragen geben, kannst du dich an den Verteiler devblog@adesso.de wenden.
Ab dem Update 16.08.2022 wurden die Metadaten der Autoren angepasst.
Von nun an gibt es die Einträge github_username und github nicht mehr.
Bitte achtet bei euren Commits darauf, diesen Eintrag NICHT zu setzen.
Ab dem Update 09.05.2022 wurden die Metadaten der Autoren angepasst.
Von nun an gibt es den Eintrag email nicht mehr.
Dadurch reduzieren wir die in diesem öffentlichen Repository gespeicherten personenbezogenen Daten.
Bitte achtet bei euren Commits darauf, diesen Eintrag NICHT zu setzen.
Ab dem Update 23.08.2021 wurden die Metadaten der Artikel angepasst.
Von nun an gibt es den Eintrag author nicht mehr.
Stattdessen gibt es ein Array author_ids.
Diese Umstellung beruht auf einer Umstellung im adesso-Blog zur Anzeige mehrerer Autoren.
Bei einem Autor wird dieser als einziges Element in das Array eingefügt:
author_ids: [johndoe]Bei mehreren Autoren müsst ihr nun keinen Kombinationseintrag mehr anlegen, stattdessen werden beide Autoren in dem Array angegeben:
author_ids: [johndoe, janedoe]Um loszulegen, erstelle einen Fork des devblog Repositories und checke ihn lokal aus. Dann kannst du lokal einen Blog Post erstellen und ihn später als Pull Request einreichen. Solltest du mit dem Pull Request Vorgehen nicht vertraut sein, kannst du es im Abschnitt "GitHub Fork & Pull Prozess" weiter unten nachlesen.
Blog Posts werden im Markdown Format erstellt. Du kannst dich an der Datei orientieren, in der diese Anleitung steht. Am besten nimmst du die vorliegende Datei einfach als Template (wenn du dir diese Datei in der Github Weboberfläche anschaust, musst du vorher auf den "Raw"-Button klicken, um den Quelltext zu sehen). Im folgenden sind einige Aspekte des Formats aber auch nochmal beschrieben.
Alle Blog Posts müssen im Ordner _posts abgelegt werden und dem Namensschema
YYYY-MM-DD-titel-des-blog-posts.md folgen.
Wenn du deinen ersten Blog Post schreibst, musst du in der Datei _data/authors.yml einen Eintrag
mit deinen Informationen wie im folgenden Codebeispiel hinterlegen. Als key nimmst du am besten
deinen GitHub Benutzernamen.
johndoe:
first_name: John
last_name: Doe
bio: "2-3 Sätze als Kurzbiographie, die als Beschreibung unter deinen Blog-Posts erscheinen."
avatar_url: /assets/images/avatars/johndoe.pngJede Blog Post Markdown-Datei beginnt mit einem kurzen Abschnitt, in dem einige Metadaten enthalten sind.
Dieser Abschnitt ist mit --- vom eigentlichen Inhalt getrennt und ist als YAML formatiert.
Hier sind einige Pflichtfelder auszufüllen.
Schau dir einfach den Header dieser Datei als Beispiel an.
Damit die Reviewer ihre Kommentare und Verbesserungsvorschläge an konkreter Stelle hinterlassen können, sollte jeder Satz auf je eine Zeile verteilt sein. Da Absätze in Markdown erst bei zwei Zeilenumbrüchen entstehen, werden einzeilige Umbrüche zusammengefügt.
Bitte achtet beim Schreiben darauf, da der Reviewprozess somit beidseitig erleichtert wird.
Der erste Absatz (also alles bis zur ersten Leerzeile in der Markdown-Datei) wird als Einleitung / Teaser übernommen. Der erste Absatz sollte also höchstens ein paar Sätze lang sein und keine Überschriften beinhalten. Bitte keine Links im Teaser verwenden!
Es können bis zu 3 Überschriften-Ebenen genutzt werden:
# Erste Ebene (resultiert in einem h4 Tag)
## Zweite Ebene (resultiert in einem h5 Tag)
### Dritte Ebene (resultiert in einem h6 Tag)Alles über drei Rauten resultiert in einem h6 HTML-Tag. Die Überschriften-Ebenen h1 bis h3 sind für den Blog selbst nicht vorgegeben.
Markdown unterstützt Syntax-Highlighting. Für die Darstellung im Blog wird PrismJS eingesetzt, sodass du alle von PrismJS unterstützten Sprachen verwenden kannst. Beispiel für Java-Code:
public class HelloWorld {
public static final main(String[] args){
System.out.println("Hello World");
}
}Der devblog basiert auf Jekyll. Jekyll verwendet Liquid. Die Liquid-Syntax basiert auf doppelten geschweiften Klammern:
{% raw %}
{{ liquid.befehl }}
{% endraw %}
Daher müssen die Klammern escapet werden, um sie in euren Codesnippets darzustellen.
Verwendet dazu den raw-Tag.
Um ein Bild zu verwenden, lege die Bild-Datei im Ordner /assets/images/posts/titel-deines-blog-posts/ ab und verlinke sie dann in der Markdown-Datei wie in diesem Beispiel:
Hinweis: im Gegensatz zum Beispiel-Bild oben muss der Pfad zum Bild in einem Blog Post erst bei "assets" beginnen. Der Pfad müsste also so aussehen: "/assets/images/posts/titel-deines-blog-posts/bild.png". Wichtig dabei ist, dass der Pfad mit einem "/" beginnt, ansonsten funktionieren die Bilder zwar in der Vorschau, allerdings nicht im eigentlichen Blog. Wichtig ist auch, dass ihr bei den Bildern auf die Groß- und Kleinschreibung der Dateiendung achtet. In der Preview funktioniert beides, im eigentlichen Blog ist die Dateiendung case-sensitiv.
Solltest du noch nicht mit Pull Requests und dem GitHub-Workflow vertraut sein, hilft dir die folgende Anleitung weiter.
Um Änderungen am Source Code vorzunehmen, erzeugst du zunächst einen Fork dieses Repositories über den "Fork"-Button in der GitHub Weboberfläche.
Diesen Fork checkst du lokal aus (git clone) und machst die Änderungen am Source Code.
Die geänderten Dateien checkst du dann wieder in den Fork ein (git commit + git push).
Navigierst du im Browser in der GitHub Weboberfläche dann zu deinem Fork, wird dir ein Button angeboten, mit dem du einen Pull Request erstellen kannst.
Die Änderungen in deinem Pull Request werden dann von einem Entwickler/Architekten-Kollegen gereviewed. Ggf. werden Korrekturwünsche als Kommentare im Pull Request ergänzt, die du dann vornehmen und ebenfalls auf den Fork pushen kannst. Letztendlich wird der Pull Request dann vom Reviewer in den Haupt-Branch gemergt und dann automatisch veröffentlicht.
Detailliertere Informationen zu diesem Workflow sind hier zu finden:
Wenn ein Pull Request mit einem neuen Blog Post eingegangen ist, wird automatisch ein Build angestoßen, der eine Vorschau auf einem Vorschauserver bereitstellt. Um die Vorschau anzusehen, klicke auf den Pull Request in der Github GUI und dort auf den Link "Details" neben dem Check "deploy/netlify". Ggf. müssen die Checks erst über den Button "Show all checks" aufgeklappt werden.
Der Artikel im eingegangenen Pull Request wird von einem Kollegen gereviewt. Ggf. gibt es dann noch ein paar Verbesserungsvorschläge, die eingearbeitet werden müssen.
Vor der Freigabe leitet der Reviewer einige Infos an CCO weiter:
- Titel des Blogs
- das Kürzel des Autors aus der
authors.yml - die Kurz-Bio
Dann sollte noch ein Tag gewartet werden, damit CCO die Daten verarbeiten kann, bevor der Pull Request gemergt wird.
Nachdem der Pull Request gemergt ist, wird der Blog Post automatisch mit der nächsten Synchronisation in den adesso Blog integriert.
Um die Freigabe zu vereinfachen, sollte die folgende Checkliste verwendet werden. Diese ist auch in das Pull-Request-Template eingebunden, sodass du dort deine Änderungen bequem für alle Beteiligten sichtbar, abhaken kannst.
- Wurde der Github Fork- und Pullprozess beachtet?
- Dateien eingebunden
- Artikeldatei einbinden
- Autorenfoto: assets/images/avatars/mein_avatar.jpg/png
- Artikel-Bilder hinterlegt
- Dateien angepasst:
- Artikel überprüfen: Du musst alle Anforderungen aus dem Pull-Request-Template erfüllen. Dieses Template wird automatisch in deinen PR eingebunden, so kannst du die einzelnen Punkte ganz einfach abhaken.
Ein Member des Repos wird deinen PR zeitnah als neuen Blog Post kennzeichnen und reviewen. Dies kann ein paar Tage dauern, da wir alle auch noch in anderen Projekten tätig sind. Wenn du eine Review erhalten hast, werden viele Änderungen vom Reviewer direkt als Suggestion angemerkt. Um diese direkt zu übernehmen, verwende bitte das Feature "Add suggestion to batch" und committe alles, was du übernommen hast, in einem Commit. Das erleichtert uns das Nachvollziehen der Änderungen erheblich.
Wie der Name schon sagt, sind es Suggestions, also Vorschläge, wenn du bspw. mit einer Formulierungsänderung nicht zufrieden bist, musst du diese nicht übernehmen. Es wird allerdings einen Grund geben, dass eine Änderung vorgeschlagen wurde. Gib uns dazu an dem Kommentar gerne ein Feedback oder teile uns deinen eigenen Verbesserungsvorschlag mit.
Es können auch nach Veröffentlichung nachträglich Änderungen an einem Post durchgeführt werden, wenn beispielsweise Bilder nicht korrekt dargestellt werden oder sich ein Fehler im Text eingeschlichen hat, der vorher nicht aufgefallen ist.
Wenn dich interessiert, wie die Blog Posts aus einer Markdown-Datei im adesso Blog landen, kannst du dir das Projekt jekyll2cms anschauen. Diese Anwendung liest das Blog-Repository regelmäßig aus, prüft es auf Änderungen, transformiert die Markdown-Dateien in ein XML-Format und legt diese XML wieder ab. Die XML-Dateien werden dann von einem Job im adesso CMS ausgelesen und in den Blog integriert.
Die Zeilenumbrüche im Markdown-File sind wahrscheinlich im falschen Format. Als Zeilenumbruch wird \n erwartet.
\r\n führt dazu, dass der Teaser nicht extrahiert werden kann.
Um das Problem zu lösen, kann das Markdown-File mit einem Editor wie Notepad++ geöffnet werden.
Mit "Ansicht -> Symbole anzeigen -> Alle anzeigen" werden die Steuerzeichen aktiviert.
Als Nächstes kann man mit "Suchen und Ersetzen" in der aktuellen Datei alle \r durch einen blanken String ersetzen.
Die Änderungen werden anschließend committed.
Es kann passieren, dass die Nachricht eines Commits ein leerer String ist. Dies ist der Fall, wenn keine Dateien in dem Commit durch jekyll2cms entfernt oder hinzugefügt wurden.
In diesem Fall ist jekyll2cms wahrscheinlich nicht als Contributor mit Admin-Rechten in dem Repository. In den Settings kann der GitHub-Account jekyll2cms als Contributor hinzugefügt werden. Anschließend muss dieser die Einladung noch annehmen.
Im August 2021 hat GitHub die Authentifizierung via Nutzername und Passwort für das Pushen von Änderungen deaktiviert (vgl. Token authentication requirements for Git operations). Stattdessen muss der Access Token des Nutzers jekyll2cms verwendet werden.