Einführung

Overview

Teaching: 0 min
Exercises: 0 min

Questions

What is static web content?

Why should I use GitHub or GitLab Pages to create my website?

Objectives

Explain what a static site generator does.

Choose the appropriate tool for your website/project.

Wie Websites funktionieren

Wenn wir einen Webbrowser verwenden, um eine Seite im World-Wide-Web zu besuchen, fordert der Browser Informationen von einem Server an - einem Computer, der die für die Website relevanten Daten speichert und so konfiguriert ist, dass er Anfragen nach diesen Daten empfängt und beantwortet. Unter der Annahme, dass es in dieser Phase keine Probleme gab (z. B. die Anfrage nach einer Seite, die nicht existiert, oder die Unmöglichkeit, den Server zu erreichen), empfängt und interpretiert unser Browser diese Informationen, um die Webseite auf unserem Bildschirm darzustellen.

Ein Webentwickler wäre wahrscheinlich entsetzt, wenn er eine solch grobe Vereinfachung lesen würde, was nur ein Grund dafür ist, dass Webentwickler nicht die Zielgruppe dieses Lehrgangs sind.

Die vom Webbrowser angezeigte Seite ist das Ergebnis der Kombination von HTML - einem hierarchischen Format, das die Strukturelemente der Seite und ihren Rohinhalt beschreibt - mit CSS - einem geordneten Satz von Styling-Anweisungen, die dem Browser mitteilen, wie der Inhalt organisiert und formatiert werden soll - und allen Bildern, die in die Seite eingebettet werden sollen. Andere Informationen, die vom Server empfangen, aber vom Browser nicht angezeigt werden, umfassen Metadaten, Cookies und andere nicht sichtbare Elemente im HTML - Informationen über die Website, die für einen Computer relevant sein könnten, aber wahrscheinlich für einen Menschen nicht interessant sind (es gibt [Ausnahmen][qwantz-easter-egg-ext] dazu) - und Skripte, die der Browser als Reaktion auf verschiedene Auslöser ausführen kann.

Hallo Welt in HTML

Wenn Sie eine neue Programmiersprache lernen, finden Sie oft einen Verweis auf das beliebte Hello world-Beispiel. Diese Beispiele erfassen typischerweise den einfachsten Code, der den Text “Hello, World!” erzeugen und auf dem Bildschirm anzeigen kann.

Da HTML das Vorhandensein bestimmter Tags voraussetzt und diese fast immer in übereinstimmenden Paaren vorkommen müssen (öffnendes <tag> und schließendes </tag>), neigen HTML-Dokumente dazu, ziemlich schnell langatmig zu werden.

Das einfachste, gültige HTML Hello world ist:

<!DOCTYPE html>
<html>
  <head>
    <title>Page title</title>
  </head>
  <body>
    <p>Hello, World!</p>
  </body>
</html>

Wie Sie sich vorstellen können, ist es ziemlich mühsam, lange HTML-Dokumente von Hand zu schreiben. Beachten Sie, dass wir keine Angaben darüber gemacht haben, wie und wo der Text angezeigt werden soll.

Um dies zu erreichen, müssten wir zusätzlich stilisierte Tags oder Cascading Style Sheets (CSS)-Anweisungen einfügen. Wenn Sie keine CSS-Anweisungen bereitstellen (entweder innerhalb Ihres HTML-Dokuments oder als separate Datei), wird ein Webbrowser das Layout der HTML-Elemente auf der Seite auf der Grundlage seiner Standardeinstellungen nach bestem Wissen und Gewissen festlegen.

Die vielen Tags in HTML

In dem obigen Beispiel Hello world werden 5 verschiedene Tags verwendet (html, head, title, body und p) in ihrer offenen <> und geschlossenen </> Form. Wir sehen auch den speziellen doctype-Tag, der das Format und die Version des Dokuments angibt, in diesem Fall, [HTML(5)][html5-wikipedia].

Es gibt viele weitere Tags zur Definition:

strukturelle Elemente, wie table, div, span, nav, section;

Listen, wie ul (für ungeordnete Listen) und or (für geordnete Listen);

stilisierte Elemente, wie z.B. i/em (für Kursivschrift/Hervorhebungen), b/strong (für fett) und u (für unterstrichenen Text);

Überschriften, nummeriert von h1 bis h6 für Überschriften und zunehmend kleinere Unterüberschriften;

Medienelemente, wie img, video, audio zum Einbetten von Rich-Media-Inhalten; und

Links, wobei das wichtige a (Anker)-Tag verwendet wird, um auf Abschnitte auf derselben Seite oder auf andere Seiten innerhalb derselben oder externer Websites zu verweisen.

Die [Liste der gültigen HTML-Tags][html5-tags] ist ziemlich umfangreich und deckt eine Vielzahl von Funktionen ab, die das heutige World Wide Web ausmachen.

Übung: Grundlegendes HTML schreiben

Gegeben sei der stilisierte Text:

Hello, World!

Schreiben Sie den HTML-Code, der das gleiche Ergebnis liefert. Tipp Die große Schrift wird durch die Verwendung einer Überschrift erreicht.
Lösung
<h1><em>Hello</em>, World!</h1>

Schreiben wir ein komplexeres HTML-Beispiel mit einer Tabelle, die den “Hello, World!”-Text in verschiedenen Sprachen zeigt und wie folgt gerendert wird HTML
Tabellenbeispiel

Der HTML-Code für eine solche Tabelle sieht folgendermaßen aus (Sie können den Ausschnitt in die HTML-Datei kopieren und einfügen, die Sie im vorherigen Beispiel erstellt haben):

<table>
    <tr><th>Language</th><th>Text</th></tr>
    <tr><td>English</td><td>Hello, World!</td></tr>
    <tr><td>French</td><td>Bonjour, le monde!</td></tr>
    <tr><td>Portuguese</td><td>Olá, Mundo!</td></tr>
    <tr><td>Serbian</td><td>Zdravo, svete!</td></tr>
</table>

Jede Zeile ist zwischen den Tags table row <tr> und </tr> eingeschlossen. Innerhalb einer Zeile werden die Tags <th> und </th> verwendet, um table headings (spezielle Tabellenzellen, die in fetter Schrift dargestellt werden) zu enthalten, während normale table data-Zellen in den Tags <td> und </td> enthalten sind.

Ein ähnliches Beispiel, das mit HTML-Listen geschrieben wurde, würde wie folgt aussehen: HTML-Listenbeispiel

<ul>
    <li>English: Hello, World!</li>
    <li>French: Bonjour, le monde!</li>
    <li>Portuguese: Olá, Mundo!</li>
    <li>Serbian: Zdravo, svete!</li>
</ul>

Hier haben wir die unordered list-Tags <ul> und </ul> verwendet, um eine Liste mit 4 Elementen zu definieren, die wiederum in einzelne list item (<li> und </li>) Tags verpackt sind.

Statische vs. dynamische Sites

Statische Seiten sind Seiten, deren Inhalt auf einem Server gespeichert ist und an jeden Benutzer gesendet werden kann, der eine Anfrage für diese Webseite stellt. Bei einer Anfrage braucht der Server nur die Informationen zu senden, aus denen die Webseite besteht (wie HTML und CSS). Websites, die sich nicht oft ändern, wie z. B. eine Website mit dem eigenen Lebenslauf, werden oft als statische Websites gespeichert.

Im Gegensatz dazu sind dynamische Sites solche, deren Seiten generiert werden, wenn ein Benutzer eine Anfrage für eine Webseite stellt. Je nachdem, wann die Anfrage gestellt wird, kann sich der Inhalt ändern; wenn man zum Beispiel bei einer Diskussion in einem Webforum auf Aktualisieren klickt, können neue Kommentare erscheinen. Der Hauptunterschied besteht darin, dass statische Seiten nur einmal generiert werden müssen und danach unverändert auf dem Server verbleiben, im Gegensatz zu dynamischen Seiten, die von einem Server jedes Mal neu generiert werden, wenn er eine Anfrage erhält.

Beispiele aus dem Bereich der Biowissenschaften

Ein typisches Beispiel für eine statische Website im Bereich der Biowissenschaften wäre die Dokumentation eines Werkzeugs oder eines Dateiformats, wie diese Seite auf wwpdb.org.

Die Einstiegsseiten der [PDB-Datenbank] (https://www.rcsb.org/) laden den Inhalt auf der Grundlage der vom Benutzer gewählten Visualisierungswerkzeuge und -optionen unterschiedlich. Eine Datenbank oder ein Webserver ist normalerweise eine dynamische Website.

Diese Lektion konzentriert sich auf statische Websites und Tools, die zu ihrer Erstellung verwendet werden können, die sogenannten Static Site Generators.

Einer der Vorteile des Einsatzes von Generatoren für statische Seiten ist, dass sie uns die manuelle Erstellung einer Menge HTML ersparen, so dass wir uns auf den für Menschen lesbaren Inhalt unserer Seiten konzentrieren können. Allerdings müssen wir dem Generator noch mitteilen, wie unsere Inhalte aussehen sollen, wenn sie im Browser angezeigt werden. Dazu verwenden wir ein Werkzeug namens Markdown, das wir in einer der nächsten Folgen kennenlernen werden.

Abbildung 1.1: Alternativen der Seitenerstellung. Diese Abbildung ist eine modifizierte Version des Originals, das in [JavaScript for Data Science][js4ds] veröffentlicht wurde, und wird hier mit Genehmigung des Autors wiedergegeben.

Statische Websites sind eine gute Wahl, wenn die Informationen, die Sie auf einer Website anzeigen möchten, immer gleich sind, unabhängig davon, wer Ihre Website besucht und wann, und wenn sich der Inhalt Ihrer Seiten wahrscheinlich nicht sehr oft ändern muss. Daher sind statische Seitengeneratoren eine gute Wahl für Websites, die Dokumentationen oder Lehrinhalte wie diese Seite bereitstellen: Das Ziel der Seite ist es, jedem Besucher dieselben Informationen zu liefern. Der Besucher kommt an, findet und liest (hoffentlich), was er braucht, und verlässt die Seite mit einem zufriedenen und erfüllten Gefühl.

Dynamische Seiten bieten viel mehr Möglichkeiten zur Bereitstellung von Interaktivität und personalisierten oder aktuellen Inhalten. Ihre Erstellung ist jedoch um einiges komplizierter und stellt auch eine erhebliche zusätzliche Belastung für den Server dar, nicht zuletzt im Hinblick auf die Rechenanforderungen und Sicherheitsaspekte. Dies bedeutet unter anderem, dass Sie im Gegensatz zu statischen Seiten (siehe den Rest dieser Lektion) kaum kostenlose Plattformen finden werden, die Ihnen bei der Bereitstellung dynamischer Inhalte helfen.

Übung: Das perfekte Werkzeug für den Job

Begründen Sie anhand der folgenden Website-Typen, ob ein statischer Website-Generator eine geeignete Lösung für ihre Umsetzung ist.

(1) Eine persönliche Website mit den Abschnitten Über und Projekte

(2) Ein Forum oder eine Diskussionsplattform

(3) Ein Gemeinschaftsblog oder eine Nachrichten-Website

(4) Eine Suchmaschine (wie google.com)

(5) Ein Wiki (wie z.B. wikipedia.com)

(6) Ein Online-Buch

Lösung

(1) persönliche Website: In den meisten Fällen, Ja. Diese Art von Inhalt wird typischerweise von einer Person geschrieben/bearbeitet und ist für Besucher nur zum Lesen gedacht.

(2) Forum oder Diskussion: Höchstwahrscheinlich Nein. Eine solche Website erfordert Interaktivität und Möglichkeiten, um festzustellen, wer welchen Inhalt geschrieben hat.

Für die Fragen 3 und 5 lautet die Antwort sowohl Ja als auch Nein, abhängig von den Anforderungen und der benötigten Funktionalität.

(3) blog/news: Ein einfaches Blog oder eine News-Website, die von einer kleinen Gruppe von Nutzern gepflegt wird, ist mit einem statischen Generator durchaus realisierbar. Für sehr große Gruppen von Inhaltserstellern oder wenn der Zugang zu Artikeln individuell gesteuert werden muss, führt die Verwendung eines statischen Generators zu schwierigen technischen Herausforderungen.

(4) Suchmaschine: Meistens Nein. Etwas so ausgeklügeltes wie die Google-Suche zu implementieren, wäre mit einem statischen Generator nahezu unmöglich. Es gibt zwar Möglichkeiten, eine einfache Suchmaschine zu entwickeln, die alle von einem statischen Generator erzeugten Seiten durchsucht, indem sie Indizierungen vornimmt und die Funktionen des Browsers geschickt nutzt, aber dieser Ansatz hat viele Einschränkungen.

(5) wiki: Ein einfaches Wiki ist mit einem statischen Generator (z.B. GitHub Wiki Pages) durchaus machbar, wird aber zu einer Einschränkung, sobald der Inhalt von vielen Benutzern bearbeitet oder diskutiert werden muss, wie es bei Wikipedia der Fall ist.

(6) Online-Buch: Auf jeden Fall Ja. Statische Generatoren sind perfekt für diese Art von Website. Sie bieten typischerweise Möglichkeiten, um die Wiederholung von Inhalten zu vermeiden (Variablen und Vorlagen), automatische Erstellung eines Inhaltsverzeichnisses, neben anderen Vorteilen.

GitLab-Seiten

Wenn die Website, die Sie erstellen möchten, gut zu den Stärken eines statischen Website-Generators passt - sie ist relativ klein, wird nur selten aktualisiert und der Inhalt muss nicht auf den Besucher zugeschnitten sein - dann ist die Erstellung mit GitLab Pages eine gute Option. GitLab Pages ist ein System, mit dem Benutzer Websites direkt aus ihren GitLab-Repositories erstellen und bereitstellen können. Der Service ist für öffentliche Repositories kostenlos und einfache Seiten können mit sehr wenig Konfigurationsaufwand erstellt und bereitgestellt werden.

Wir werden eine Liste von Vorlagen mit steigender Komplexität durchgehen. Während die ersten auf einfachem Markdown basieren, werden die fortgeschritteneren auf mehreren Technologien beruhen (ein Beispiel ist im folgenden Diagramm dargestellt). Es mag zunächst überwältigend klingen, aber wir werden die meisten dieser Technologien in dieser Lektion erklären - wir gehen nur nicht im Detail auf CSS/Sass (Stylingsprache, die in CSS kompiliert wird) und JavaScript/CoffeeScript (Skriptsprache, die in JavaScript kompiliert wird) ein.

Statische Websites im GitHub Pages
Technologieübersichtsdiagramm

Zunächst werden wir ein Projekt zum Speichern unserer Dateien einrichten und mehr darüber erfahren, wie wir den Inhalt unserer Seiten mit HTML und Markdown verfassen und formatieren, bevor wir GitLab so konfigurieren, dass dieser Inhalt mit GitLab Pages als Website angezeigt wird.

Einrichten eines Projekts

Bevor wir mit der Arbeit beginnen, müssen wir zunächst ein Projekt erstellen, in dem wir arbeiten können. Dieses Projekt ist vergleichbar mit einem Ordner auf Ihrem Computer, wobei der Hauptunterschied darin besteht, dass der Ordner im Web in GitLab/GitHub liegt (obwohl Sie bei Bedarf auch eine Kopie auf Ihrem Computer behalten können) und dieser Ordner eine Versionskontrollsoftware namens git verwendet, um Änderungen an den Dateien zu verfolgen. Für unsere Zwecke werden wir die Versionskontrollsoftware größtenteils ignorieren, obwohl sie nützlich sein kann, wenn Sie zu alten Versionen zurückkehren müssen (siehe Software Carpentry - Versionskontrolle mit Git für eine Einführung). In dieser Lektion werden wir mit diesem Ordner im Web arbeiten, um die Website zu kontrollieren, die wir erstellen werden.

Melden Sie sich bei Ihrem GitLab-Konto an

Bevor Sie ein Repo erstellen können, müssen Sie sich im EMBL GitLab

Es gibt zwei Möglichkeiten, ein neues Projekt zu erstellen:

Klicken Sie auf die Schaltfläche “+” in der oberen Navigationsleiste und wählen Sie “Neues Projekt”

Plus button

oder, wenn Sie sich auf der Projektseite befinden, klicken Sie auf die Schaltfläche “Neues Projekt”

Schaltfläche Neues Projekt

Sie werden zu einer Seite weitergeleitet, die drei Optionen bietet:

Ein leeres Projekt erstellen
Aus Vorlage erstellen
Projekt importieren Nehmen Sie sich Zeit, um die Beschreibungen der verschiedenen Fälle zu lesen. Bitte wählen Sie “Leeres Projekt erstellen”.

Als nächstes müssen Sie einige Angaben zu Ihrem Projekt machen.

Blank new repository page

In dieser Lektion werden wir an einer allgemeinen Gruppen-Website arbeiten. Sie können sich vorstellen, dass diese Website für Ihre Laborgruppe, eine bestimmte Projektgruppe oder eine andere Gruppe, mit der Sie zusammenarbeiten, bestimmt ist. Geben Sie in das Feld “Projektname” group-website ein.

Die Project slug bestimmt die URL für den Zugriff auf Ihr Projekt und Ihre Website. Sie wird automatisch generiert, wenn Sie das Feld Project name ausfüllen. Lassen Sie es so wie es ist.

Werfen Sie einen Blick auf das Dropdown-Menü neben dem Feld Project URL. Die Standardoption ist Ihr eigener Benutzer, dies bezieht sich auf Ihren eigenen Namensraum. Je nachdem, zu welchen Gruppen Sie gehören, können auch andere Namensräume verfügbar sein. Wenn dies zum Beispiel Ihre Gruppen-Website sein soll, ist es vielleicht eine gute Wahl, Ihren Gruppennamensraum zu wählen, um sie zu hosten. So können andere Gruppenmitglieder leicht auf das Projekt zugreifen und Ihr Gruppenname (und nicht Ihr Benutzername) wird in der URL der Website angezeigt. Wir werden dieses Testprojekt jedoch in unserem eigenen Namespace initialisieren.

Wir können auch eine Beschreibung hinzufügen (z. B. “Projekt zum Erlernen der Erstellung von Websites mit GitLab-Seiten”), damit wir wissen, worum es sich bei diesem Projekt handelt, wenn wir es nach dem Workshop wiederfinden.

Wir werden auch die Option Initialize repository with a README überprüfen. Es ist eine gute Praxis, eine README-Datei zu haben, die mehr Informationen über Ihr Repository enthält.

GitLab vs GitHub

Die meisten der hier beschriebenen Schritte sind in GitHub sehr ähnlich. Was in GitLab als “Projekt” bezeichnet wird, ist in GitHub ein “Repository”; falls Ihr Ausbilder die beiden Begriffe verwechselt, finden Sie hier den Grund. Darüber hinaus sind die “Gruppen” in GitLab “Organisationen”.

Wichtiger sind die Unterschiede in Bezug auf die Sichtbarkeitsebene und die Einrichtungsoptionen. In GitHub gibt es nur zwei Optionen für ein Repository: “Öffentlich” oder “Privat”. Das EMBL GitLab erlaubt eine spezifischere Feinabstimmung der Berechtigungen durch die Option “Intern”, d.h. nur für angemeldete Benutzer zugänglich. Während GitLab nur die Möglichkeit bietet, das Repository mit einer README zu initialisieren, bietet GitHub die Option, es auch mit einer .gitignore und Lizenzdateien zu initialisieren.

Sobald Sie diese Schritte abgeschlossen haben, können Sie auf die Schaltfläche Create Project klicken. GitLab richtet dann das Projektarchiv ein und erstellt ein Projektarchiv mit dem Namen group-website und einer README.md-Datei darin. Die grafische Oberfläche hat uns bei den folgenden Schritten geholfen:

mkdir group-website
cd group-website
git init
cat > README.md
git add README.md
git commit -m "Initial commit"

Auf einem entfernten Server. Die Standardverzweigung ist main.

Github-Repository für die Gruppenwebsite

Bevor Sie zum nächsten Kapitel übergehen, sollten Sie einen Blick auf die Schaltflächen am oberen Rand werfen, wie z.B. Add LICENSE, Add CHANGELOG usw., die Ihnen mögliche nächste Schritte vorschlagen. Zum Beispiel ist die Lizenz etwas, das Sie auf jeden Fall in Ihr Projekt aufnehmen sollten. Wir werden nicht im Detail darauf eingehen, aber bedenken Sie bitte, dass die Lizenzierung eine gute Praxis (wenn nicht sogar eine notwendige) für jedes Projekt ist, das Daten oder Software enthält. Ihre Website, selbst wenn es sich um eine sehr einfache und statische Website handelt, wird irgendeine Art von Daten enthalten, selbst wenn es sich nur um Personennamen handelt. Die Technologien und Vorlagen, die Sie zur Erstellung der Website verwenden, sind Software. Ein Wort der Weisheit.

[qwantz-easter-egg-ext]: https://chrome.google.com/webstore/detail/dinosaur-comics-easter-eg/bojkkeeefjmeogpgnlomodfkkfkfhabj [js4ds]: http://js4ds.org [html5-tags]: https://www.w3schools.com/TAGS/default.asp

Key Points

A static site generator combines page-specific content with layout elements and styling information to construct individual webpages.

GitHub/GitLab Pages is a good choice for people who are already familiar with Git and GitHub/GitLab.

This approach can be used to create a relatively small website/blog on a limited budget.

Verfassen mit Markdown

Overview

Teaching: 0 min
Exercises: 0 min

Questions

How can I write content for my webpages?

How do I link to other pages?

Objectives

create simple pages of formatted text

Markdown

Markdown ist eine leichtgewichtige Auszeichnungssprache, d.h. eine Konvention zum Hinzufügen von Stilinformationen zu Textinhalten. Wie der Name Markdown schon sagt, sind die Syntaxelemente dieser Sprache auf ein Minimum reduziert. Mit einer eher minimalistischen Syntax ist in Markdown formatierter Text vergleichsweise gut lesbar. Dies mag ein Grund dafür sein, dass Markdown die Sprache der Wahl für formatierte Benutzereingaben auf Websites wie z. B.:

Where to Start Writing Markdown?

Es gibt eine Vielzahl von Tools zum Rendern von Markdown-Quellcode. Rendering ist der Prozess der Erzeugung einer schönen Ansicht des Inhalts unter Verwendung der im Quelltext enthaltenen Stilinformationen. Die Chancen stehen gut, dass Ihr Editor dies kann. Da wir auf die Erstellung von Websites mit GitLab-Seiten hinarbeiten, werden wir GitLab gleich zum Erlernen der Grundlagen von Markdown verwenden. Das GitLab-Projekt, das Sie in der letzten Folge erstellt haben, enthält eine Datei README.md. Klicken Sie auf den Dateinamen, um sie zu öffnen.

Das Bild unten zeigt die Standardansicht. Diese Ansicht enthält eine gerenderte Ansicht des Inhalts der Datei README.md, wie die auf unserer Projekthomepage.

README preview

Mit den Schaltflächen auf der rechten Seite können Sie mit der Datei und der Visualisierung interagieren. Mit den ersten beiden Schaltflächen, den Schaltflächen mit den Symbolen, können Sie zwischen Display source und Display rendered file umschalten. Fahren Sie mit der Maus darauf, um diese beiden Meldungen in Tooltips anzuzeigen. Die Quelle ist die nicht gerenderte Ansicht unserer Datei. Wir können sie über die blaue Schaltfläche Edit bearbeiten. Klicken Sie ihn an.

Bearbeitungsoberfläche der Gruppen-Websites
README-Datei

Wir können den Inhalt ändern und einen Blick auf die gerenderte Ansicht werfen, indem wir oben auf den Reiter Preview klicken.

Vorschau auf den gerenderten Inhalt der README-Datei der
Gruppen-Websites

Fügen wir Some **bold** font hinzu und sehen wir uns an, was passiert, wenn wir die Vorschau auf der Registerkarte Vorschau verwenden. Was ist mit der fetten Welt passiert?

Um den Inhalt in der Datei README.md zu speichern, sollten wir auf die Schaltfläche Commit changes am unteren Ende der Seite klicken. Bitte beachten Sie, dass es sich hierbei nicht um eine einfache Schaltfläche “Speichern” handelt, sondern um eine tatsächliche Übertragung. Diese Version des Projekts wird in Git unter dem Namen Commit message gespeichert, den Sie hier im Commit-Menü angeben, und in dem Zweig, den Sie als Target branch festlegen. Wir haben im Moment nur den Hauptzweig - also ist diese Wahl offensichtlich - und die Commit-Nachricht wird mit dem Namen der Datei, die Sie gerade bearbeitet haben, vorkompiliert. Vielleicht möchten Sie in Ihrer Commit-Nachricht genauer sein, aber für den Moment nehmen wir die vorgegebene Option. Übertragen Sie diese Änderung.

Schreiben einer Commit-Nachricht

Eine Commit-Nachricht ist ein kurzer, beschreibender und spezifischer Kommentar, der uns später helfen wird, uns daran zu erinnern, was wir getan haben und warum. Mehr über das Schreiben von Commit-Nachrichten finden Sie in diesem Abschnitt der Git-novice Lektion.

Nach dem Übertragen von README-Änderungen

Die Schnittstelle leitet Sie auf die Hauptseite des Projekts um. Oben steht eine Meldung: “Ihre Änderungen wurden erfolgreich übertragen.” Unsere Änderungen wurden in die README-Datei aufgenommen, die nun die zweite Zeile mit der fetten Schrift zeigt.

Markdown schreiben

Nachdem wir nun die Bearbeitungsoberfläche und die Vorschauregisterkarte unseres Projekts README.md kennen, können wir es als Texteditor verwenden und ausgewählte Markdown-Funktionen untersuchen.

Unser README.md enthält bereits Text und zwei Formatierungsfunktionen:

Überschrift # group-website
Hervorhebung durch **bold**.

Lassen Sie uns etwas mehr Markdown lernen, indem wir einige Formatierungen hinzufügen und sehen, was passiert, wenn wir die Vorschau auf der Registerkarte “Vorschau” verwenden. Fügen Sie das Folgende zu Ihrer README.md Datei hinzu.

# group-website
Repo for learning how to make websites with GitLab pages

## Learning Markdown

Vanilla text may contain *italics* and **bold words**.

This paragraph is separated from the previous one by a blank line.
Line breaks
are caused by two trailing spaces at the end of a line.

[Carpentries Webpage](https://carpentries.org/)

### Carpentries Lesson Programs:
- Software Carpentry
- Data Carpentry
- Library Carpentry

Sie können dann erneut auf die Registerkarte “Vorschau” klicken, um zu sehen, wie die Formatierung wiedergegeben wird.

Vorschau auf die Formatierung in der README

Markdown Trailing Spaces Are Meaningful

In dem obigen Beispiel gibt es zwei Leerzeichen am Ende von Line breaks . Diese leiten einen sogenannten harten Zeilenumbruch ein, der bewirkt, dass der Absatz in der nächsten Zeile fortgesetzt wird, indem dem generierten HTML ein <br/> hinzugefügt wird.

Wenn Sie die Zeile in einer Markdown-Datei umbrechen, aber die beiden Leerzeichen am Ende nicht einfügen, wird der generierte HTML-Code in der gleichen Zeile fortgesetzt, ohne ein <br/> einzufügen. Dies wird weicher Zeilenumbruch genannt.

In einigen Fällen kann es vorkommen, dass weiche Zeilenumbrüche ein <br/> einführen. Dies kann passieren, wenn Sie verschiedene markdown flavors verwenden. {: .language-markdown }

Sie können diese Änderungen übertragen, um sie zu speichern. Aber zuerst machen wir eine Übung, um das Schreiben von mehr Markdown auszuprobieren.

Übung: Ausprobieren von Markdown

Verwenden Sie dieses Cheatsheet, um das Folgende zu Ihrem README.md hinzuzufügen:

Eine weitere Überschrift der zweiten Ebene

Etwas Text unter dieser Überschrift der zweiten Ebene, der einen Link und ~~durchgestrichenen~~ Text enthält.

Eine Überschrift der dritten Ebene

Eine nummerierte Liste

Bonus: Dieses Bild hinzufügen https://github.com/carpentries/carpentries.org/blob/main/images/TheCarpentries-opengraph.png
Beispiellösung

Ihr Markdown könnte zum Beispiel wie folgt aussehen:
## More info on the lesson
You can find this lesson [here](https://grp-bio-it-workshops.embl-community.io/building-websites-with-gitlab/).

### Four reasons you should learn Markdown:

1. Less formatting than HTML
2. Easy to read even with formatting
3. Commonly used for websites and software development
4. We ~~don't~~ use it in The Carpentries

![Carpentries Logo](https://github.com/carpentries/carpentries.org/raw/main/images/TheCarpentries-opengraph.png)

Referenz-Stil Links

Bisher haben wir inline-style Links verwendet, bei denen die URL inline mit dem Beschreibungstext steht, zum Beispiel:
[Carpentries Webpage](https://carpentries.org/)
Wenn Sie einen Link mehr als einmal verwenden, sollten Sie stattdessen so genannte reference-style Links verwenden. Links im Verweis-Stil verweisen auf die URL über ein Label. Das Label wird in eckige Klammern [ ] direkt nach dem Beschreibungstext des Links gesetzt und später, normalerweise am Ende der Seite, können Sie dieses Label mit der URL verbinden, auf die es verweist, um den Link zu vervollständigen. Das sieht dann so aus:
[Carpentries Webpage][carpentries]

[carpentries]: https://carpentries.org/

Im weiteren Verlauf der Lektion werden wir Markdown verwenden und mehr darüber lernen. Unabhängig davon, ob Sie sich dafür entscheiden, Ihre Website mit Markdown-basierten Technologien oder mit HTML zu strukturieren, müssen Sie dennoch einige Grundlagen von Markdown beherrschen, um Ihre README-Datei zu bearbeiten. Die README-Datei ist ein wichtiger Leitfaden - der auf der Startseite Ihres Projekts angezeigt wird - für Ihre Mitarbeiter und auch für Sie, um zu verstehen, worum es in dem Projekt geht und wie Sie dazu beitragen können.

Markdown Flavours

Die anfängliche Beschreibung von Markdown war informell und enthielt gewisse Unklarheiten, so dass im Laufe der Jahre verschiedene Markdown-Implementierungen und Syntax-Variationen (oft als “Flavours” bezeichnet) erschienen, um verschiedene Syntax-Merkmale und Erweiterungen zu unterstützen. Dies hat zur Folge, dass die Syntax einer Variante in einer anderen möglicherweise nicht wie erwartet interpretiert wird - man muss sich also bewusst sein, welche Variante von einer bestimmten Plattform verwendet wird. Hier sind ein paar bekannte Varianten:

GitLab-flavored Markdown (verwendet in dieser Lektion und von GitLab)

[GitHub-flavored Markdown][github-flavored-markdown] (von GitHub verwendet)

Kramdown (eine schnelle, Ruby, Open-Source-Implementierung, die unter der MIT-Lizenz veröffentlicht wurde)

Mardown ist auch die Sprache der Plattform für kollaborative Notizen, die am EMBL verfügbar ist. Sie können darauf [hier] zugreifen (https://pad.bio-it.embl.de/). Die Plattform basiert auf CodiMD.

Übung: Fügen Sie Ihre Repository-Details zu CodiMD hinzu

Verwenden Sie die Markdown-Syntax, um einen Link in das Dokument mit den gemeinsamen Notizen einzufügen, das Sie verwenden, um dieser Lektion zu folgen. Der Linktext sollte Ihr GitLab-Benutzername und das Ziel Ihr Repository sein.

[github-flavored-markdown]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet

Key Points

Markdown is an relatively easy way to write formatted text

Markdown and HTML tags can be used together in a single page

I recommend writing Markdown links ‘reference-style’

The landing page for a website is conventionally named index.md

Hosting von Seiten auf GitLab

Overview

Teaching: 0 min
Exercises: 0 min

Questions

How do I publish my pages via GitLab?

Objectives

publish HTML on the web with GitLab Pages

GitLab-Seiten

Nur statische Webseiten

Wie in den vorangegangenen Kapiteln bereits angedeutet, können Sie zur Veröffentlichung einer Website mit GitLab Pages verschiedene Technologien wie Jekyll, Gatsby, Hugo, Middleman, Harp, Hexo und Brunch verwenden, um nur einige zu nennen. Sie können auch jede statische Website veröffentlichen, die direkt in einfachem HTML, CSS und JavaScript geschrieben ist. Pages unterstützt keine dynamische serverseitige Verarbeitung, wie sie zum Beispiel .php und .asp erfordern.

Der Schlüssel dazu, dass Ihre Website wie erwartet funktioniert, ist die GitLab CI-Konfigurationsdatei namens .gitlab-ci.yml. Diese Datei konfiguriert, wie Ihre Website erstellt wird. Sie ist in YAML geschrieben, das eine eigene Syntax hat, die wir hier nicht näher erläutern werden, daher empfehlen wir Ihnen, diese Kurzanleitung zu befolgen, bevor Sie sie einrichten. Damit sie korrekt funktioniert, muss sie in Ihrem Stammverzeichnis, d.h. auf der gleichen Ebene wie unsere README-Datei, im Hauptprojektordner abgelegt werden.

Das Wichtigste ist, dass Sie mit GitLab CI die Kontrolle über Ihre Builds haben. Sie befinden sich nicht in einer unsichtbaren Blackbox, von der Sie nicht wissen, was vor sich geht! Sie können jeden laufenden Build live sehen, indem Sie zum Pipelines Ihres Projekts navigieren (wir werden dies später tun). Sie können auch einen beliebigen Befehl zu Ihrem .gitlab-ci.yml-Skript hinzufügen. Damit können Sie auf dem entfernten Server so ziemlich alles tun, was Sie auf Ihrem lokalen Rechner tun. Wir werden später in dieser Lektion einige Beispiele zeigen, wie man eigene Build-Befehle über die .gitlab-ci.yml.-Datei ausführt.

Lokal oder in GitLab arbeiten

Diese Lektion zielt nicht darauf ab, Git zu lehren und wie man lokal (auf dem Laptop) an einem Projekt arbeitet, das in Git versioniert und verwaltet wird. Wenn Sie jedoch ein grundlegendes Verständnis von Git haben, können Sie die nächsten Schritte lokal durchführen, um zu lernen, wie man eine Website richtig entwickelt: Testen Sie sie lokal und übertragen Sie nur wichtige Versionen davon. Im Gegenteil, die Arbeit auf der Online-Plattform wird uns dazu zwingen, Versionen zu übertragen, die nicht sehr aussagekräftig sind, nur um des Lernens willen.

Wenn Sie ein grundlegendes Verständnis von Git haben, konfigurieren Sie ein lokales Projekt für die Bereitstellung. Klonen Sie Ihr lokales Repository (lesen Sie die Lektion git novice, wenn Sie nachlesen wollen, was der Befehl git clone bewirkt und wie Sie git push Änderungen von lokalen zu entfernten Projekten übertragen). Kurz gesagt, Sie sollten nun von einem Terminal aus folgendes ausführen:
git clone https://git.embl.de/<your username>/group-website.git
cd group-website
und arbeiten in Ihrem geklonten Verzeichnis weiter. Sie können Ihre Dateien mit vim oder einem beliebigen Editor hinzufügen und bearbeiten - er muss nicht vom Terminal aus gestartet werden, aber denken Sie daran, das Terminal offen zu halten, wenn Sie die Änderungen wieder an die Gegenstelle übertragen müssen.

Wir beginnen mit dem einfachsten Beispiel, einer einfachen HTML-Seite mit GitLab-Seiten.

Lassen Sie uns die Datei .gitlab-ci.yml direkt in unserem GitLab-Projekt online erstellen. Wir werden mit mehreren Dateien arbeiten müssen. Dazu öffnen wir die Web IDE, indem wir auf die Schaltfläche oben rechts in unserem Projekt klicken: Edit > Web IDE.

Edit IDE

Wenn Sie es zum ersten Mal öffnen, erscheint ein Anpassungsfenster. Ignorieren Sie es vorerst, aber beachten Sie, dass das Aussehen der nächsten Screenshots von dem abweichen kann, was Sie auf der Standardvorlage sehen. Sie sollten jedoch die gleichen Menüs und Dateien zur Verfügung haben. Insbesondere der EXPLORER (ein Datei-Explorer) auf der rechten Seite listet Dateien und Ordner in Ihrem Repository auf (im Moment sollte es nur die Datei README geben), und das Panel auf der rechten Seite zeigt den Inhalt solcher Dateien, wenn Sie sie öffnen.

Fahre mit der Maus über den Namen deines Projekts im EXPLORER, um ein kleines Menü mit einem Symbol zum Hinzufügen von Dateien zum Ordner zu sehen. Klicken Sie darauf und erstellen Sie eine .gitlab-ci.yml-Datei. Füllen Sie diese dann mit dem folgenden Inhalt:

Erstellen Sie Ihre .gitlab-ci.yml Datei und schreiben Sie hinein:

pages:
  stage: deploy
  script:
    - echo 'Nothing to do...'
  artifacts:
    paths:
      - public
  only:
    - main

Dieser Code erstellt einen Job namens “pages”, der GitLab anweist, den Inhalt der Website in public bereitzustellen, immer wenn ein Commit gepusht wird und nur in den Hauptzweig. Es hat nicht viel zu tun, außer sich den Inhalt in der Öffentlichkeit anzuschauen, daher ist die “Skript”-Konfiguration im Grunde keine (es gibt nur ein Echo “Nichts zu tun” ins Terminal).

Validierung der Datei gitlab-ci.yml

Bevor Sie ein .gitlab-ci.yml in Ihr Projekt einfügen, können Sie dessen Syntax mit dem Tool [CI Lint] (https://docs.gitlab.com/ee/ci/lint.html) überprüfen. Sie müssen in Ihrem Konto angemeldet sein, um Zugang zu diesem Tool zu haben. Sie finden es, indem Sie zu den Pipelines Ihres Projekts navigieren: Es gibt eine Schaltfläche oben rechts auf Ihrem Bildschirm. Weitere Informationen finden Sie in der vollständigen Dokumentation für .gitlab-ci.yml.

Git-Zweige und GitLab CI-Dateien

Sie können für jedes Projekt ein eigenes .gitlab-ci.yml haben - aber Sie könnten sogar für jeden Zweig eine eigene GitLab CI-Konfiguration haben. Das bedeutet, dass Sie Ihr Skript in parallelen Zweigen testen können, bevor Sie es in Ihren Hauptzweig übertragen. Wenn der Build erfolgreich ist, wird er zusammengeführt. Wenn nicht, können Sie Anpassungen vornehmen und die Erstellung erneut versuchen, ohne Ihren Hauptzweig zu beschädigen.

Als nächstes erstellen wir den Ordner public (verwenden Sie das Symbol für einen neuen Ordner im Menü EXPLORER), der eine Datei index.html enthält.

Lokal oder in GitLab arbeiten

Wenn Sie lokal arbeiten, können Sie dies vom Terminal aus durch tun:
mkdir public
cat > public/index.html

Füllen Sie die neue Datei index.html mit diesem Inhalt:

<html>
    <head>
        <title>Home</title>
    </head>
    <body>
        <h1>Hello World!</h1>
    </body>
</html>

Bevor wir mit dem Kapitel fortfahren, versuchen Sie sich vorzustellen, wie die endgültige Anzeige auf der resultierenden Webseite aussehen wird. Sie können es auf ein Blatt Papier zeichnen.

Lokal oder in GitLab arbeiten

Wenn Sie lokal arbeiten, übertragen Sie jetzt Ihre Änderungen und geben Sie sie weiter. Sie können dies vom Hauptprojektordner aus tun:
git add .
git commit -m "simple html in public"
git push -u origin main

Wenn Sie die Datei .gitlab-ci.yml und den Ordner public, der die Datei index.html enthält, erstellt haben, sollten Sie alle Dateien im Ordner EXPLORER sehen. Speichern wir nun die erste Version unseres Projekts (commit), indem wir das Menü Source control auf der linken Seite auswählen.

IDE-Versionskontrollschaltfläche

Dies ändert das Panel auf der linken Seite, das die Dateien auflistet, die wir geändert haben (zwei Dateien wurden hinzugefügt) und erwartet, dass Sie eine Commit-Nachricht (eine kurze Beschreibung der Projektversion, die Sie committen) in das Textfeld oben eingeben. Unsere Commit-Nachricht könnte in diesem Fall lauten: “Einfaches HTML über die GitLab-Pipeline bereitstellen”. Geben Sie diese oder eine andere Nachricht ein, und dann Commit to 'main'.

IDE-Versionskontrolle

Gehen Sie zurück zu Ihrem entfernten Projekt in GitLab. Der Screenshot unten zeigt, wie es aussehen sollte:

Simple HTML project screenshot

Der Ordner public enthält die Datei index.html. Der Push-Befehl, den Sie gerade gestartet haben, sollte Ihre erste Pipeline ausgelöst haben. Wählen Sie im Menü auf der linken Seite Build > Pipelines, um sie zu visualisieren.

Erste laufende Pipeline

Da wir angehalten und überprüft haben, wie unser Remote-Ordner aussieht, ist Ihre Pipeline vielleicht schon passed . Wenn nicht, warten Sie einfach, bis es so weit ist.

Ihre erste Website wurde erfolgreich bereitgestellt! Sie fragen sich, wo Sie sie sehen können? Gehen Sie zu Deploy > Pages. Die URL Ihrer Website wird dort angezeigt. Sie sollte lauten: https://<your user name>.embl-community.io/group-website.

Die Seiten-URL in Einstellungen>Seiten

Der Screenshot unten enthält auch eine interessante Warnmeldung. Lesen Sie immer diese Art von Meldungen, die von der GitLab-Benutzeroberfläche angezeigt werden, da sie in der Regel für Sie relevant sind. Sie lautet: “Die Zugriffskontrolle ist für diese Pages-Website aktiviert; nur autorisierte Benutzer können darauf zugreifen. Um Ihre Website öffentlich zugänglich zu machen, navigieren Sie zu den Einstellungen Ihres Projekts > Allgemein > Sichtbarkeit und wählen Sie im Abschnitt Seiten die Option Jeder aus Hier finden Sie auch Links zu weiterer Dokumentation, wenn Sie mehr wissen möchten. Folgen Sie den Anweisungen, wenn Sie Ihre Website öffentlich zugänglich machen möchten.

Unabhängig davon, ob sie öffentlich ist oder nicht, sollten wir in der Lage sein, unsere eigene Website zu visualisieren. Klicken Sie auf den Link, und hier ist sie:

Einfache Website-Ansicht

Übung: Vergleichen Sie mit Ihrer Skizze

Sieht die soeben eingerichtete Website so aus, wie Sie es sich anhand des HTML-Codes in der Indexdatei vorgestellt haben? Hätten Sie gedacht, dass etwas anderes angezeigt werden würde? Diskutieren Sie mit Ihrem Kollegen neben Ihnen.

Übung: Die plain-html Vorlage

GitLab bietet eine Reihe von Vorlagen für Webseiten, die über Pages bereitgestellt werden. Eine davon heißt “plain-html”, die Sie unter diesem Link aufrufen können. Die allgemeine Struktur ist derjenigen, die wir gerade verwendet haben, sehr ähnlich. Gehen Sie in den Ordner public. Hier gibt es zwei Dateien, eine style.css-Datei und eine index.html-Datei.

Wir werden in dieser Lektion auf die Funktionsweise der Datei .css eingehen, aber es könnte jetzt interessant sein, einen Blick auf ihre Syntax und ihren Inhalt zu werfen. Dieser Dateityp wird für die Gestaltung von HTML-Inhalten verwendet. Diese spezielle Datei enthält Stilanweisungen für drei Elemente: das body, das navbar und den Linktext (a) innerhalb der Navigationsleiste, der seine Farbe ändert, wenn man mit der Maus darüber fährt (a:hover). Machen Sie sich jetzt keine Gedanken darüber, wie das genau funktioniert, aber wenn Sie sich diese Seite ansehen, denken Sie daran, mit der Maus über die Links in der Navigationsleiste zu fahren, um dies in Aktion zu sehen.

Öffnen Sie nun die Datei index.html. Ihr Inhalt wird im Folgenden wiedergegeben.
<!DOCTYPE html>
<html>
 <head>
   <meta charset="utf-8">
   <meta name="generator" content="GitLab Pages">
   <title>Plain HTML site using GitLab Pages</title>
   <link rel="stylesheet" href="style.css">
 </head>
 <body>
   <div class="navbar">
     <a href="https://pages.gitlab.io/plain-html/">Plain HTML Example</a>
     <a href="https://gitlab.com/pages/plain-html/">Repository</a>
     <a href="https://gitlab.com/pages/">Other Examples</a>
   </div>

   <h1>Hello World!</h1>

   <p>
     This is a simple plain-HTML website on GitLab Pages, without any fancy static site generator.
   </p>
 </body>
</html>
Es ist wieder Zeit zum Skizzieren! Zeichnen Sie die resultierende Webseite mit dem Inhalt dieser HTML-Datei. Hinweis: Die Navigationsleiste ist eine Leiste am oberen Rand der Seite, die es uns ermöglicht, im Inhalt der Website zu navigieren.

Optionale Frage: Wie wird die Datei .css verwendet? Woher weiß die Website, welches die richtige Datei zum Lesen ist?

Lösung

Sie können auf die deployed website gehen, um zu sehen, wie es aussieht. Hier unten ein Screenshot des Ergebnisses:

Gibt es einen Unterschied zu Ihrer Skizze?

Optionale Frage: Der Speicherort der .css Datei ist in der .html Datei angegeben, durch: <link rel="stylesheet" href="style.css">.

Nützliche Links

Sie haben jetzt die minimalen Werkzeuge, um mit HTML und CSS herumzuspielen. Sie können die beiden Dateien aus der letzten Übung template in Ihr Repository kopieren und versuchen, die Textgröße, die Farbe der Navigationsleiste, Links oder die Textformatierung zu bearbeiten. Wenn Sie sich entschließen, dieses Repository zu faken, um zu experimentieren, tun Sie bitte, was die Autoren in ihrer README-Datei verlangen (ein Grund mehr, die README-Dateien in jedem anderen Projekt zu konsultieren und sie sorgfältig zu kompilieren): “Wenn Sie dieses Projekt für Ihren eigenen Gebrauch geforkt haben, gehen Sie bitte zu den Settings Ihres Projekts und entfernen Sie die Forking-Beziehung, was nicht notwendig ist, es sei denn, Sie wollen wieder zum Upstream-Projekt beitragen.”

Ein umfangreiches Tutorial über HTML-Elemente, einschließlich Beispielen für die Einbettung von Formularen, Medien und Links, finden Sie unter w3schools. Zusätzlich zu diesem Tutorial gibt es viele andere Quellen, die HTML-Tutorials anbieten. Sie können auf jeden Fall eine auswählen, die Ihrem Geschmack entspricht, um mehr zu lernen.

Key Points

GitLab serves pages in your project according to a configuration file called .gitlab-ci.yml

GitLab-Seiten mit Jekyll

Overview

Teaching: 0 min
Exercises: 0 min

Questions

How do I publish web pages through GitLab and Jekyll?

Objectives

Publish Markdown files as HTML on the web with GitHub Pages

Jekyll ist ein leistungsstarker Generator für statische Websites, der hinter GitLab Pages stehen kann. Er erstellt statische HTML-Website-Inhalte aus verschiedenen Dateien in Ihrem Repository (Markdown-Dateien, CSS-Stylesheets, Seitenvorlagen/Layouts usw.). Dieser “kompilierte” Inhalt wird dann als Ihre Website bereitgestellt.

Jekyll macht die Verwaltung Ihrer Website einfacher, weil es auf Vorlagen basiert. Vorlagen (oder Layouts in der Jekyll-Schreibweise) sind Entwürfe, die von mehreren Seiten wiederverwendet werden können. Zum Beispiel haben wir (Ihre Ausbilder) nicht jede einzelne Übung in dieser Lektion separat gestaltet: Wir haben eine Vorlage erstellt, die angibt, wie die Übungen angezeigt werden sollen (die orangefarbene Box, die Dropdown-Lösungsbox usw.) und jedes Mal, wenn wir einen Textblock als “Übung” markieren, wird er auf diese Weise angezeigt.

Wir werden Jekyll-Layouts in Kürze behandeln; für den Moment wollen wir Jekyll und seine Skriptsprache namens Liquid lernen.

Globale Parameter

Auch in diesem Fall werden wir unser Deployment aus der Datei .gitlab-ci.yml auslösen und anpassen. Sie können Ihre vorherige Version des group-website-Repositorys bearbeiten, wir empfehlen jedoch, eine neue Version zu erstellen. Folgen Sie den Schritten in “Einrichten eines Projekts” in der [Einführung] (https://grp-bio-it-workshops.embl-community.io/building-websites-with-gitlab/01-introduction/index.html), wenn Sie dies tun möchten. Erstellen/ändern Sie den Inhalt der .gitlab-ci.yml Datei mit:

image: ruby:latest

pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  artifacts:
    paths:
      - public
  only:
    - main

Dieser Code setzt voraus, dass das Skript in der Umgebung der neuesten Ruby-Version läuft, installiert das Jekyll-Gem und baut die Site im öffentlichen Pfad auf (der Ordner wird aus der Ferne erstellt, Sie sollten sich zu diesem Zeitpunkt keine Sorgen machen). Das Ergebnis betrifft nur den Hauptzweig.

Die Ausführung dieser Pipeline erfordert auch eine Gemfile. Erstellen Sie diese im Stammordner mit dem folgenden Inhalt:

source "https://rubygems.org"

gem "jekyll"

Kurz gesagt, aber wir werden uns das noch genauer ansehen, sucht Jekyll nach Textdateien, die mit einem Header beginnen, der wie folgt formatiert ist:

---
variable: value
other_variable: other_value
---

...stuff in the page...

und fügt die Werte dieser Variablen in die Seite ein, wenn sie formatiert wird. Die drei Bindestriche, mit denen die Kopfzeile beginnt, müssen die ersten drei Zeichen in der Datei sein: Schon ein einzelnes Leerzeichen davor führt dazu, dass Jekyll die Datei ignoriert.

Der Inhalt des Headers muss als YAML formatiert sein und kann Booleans, Zahlen, Zeichenketten, Listen und Wörterbücher mit Name/Wert-Paaren enthalten. Die Werte der Kopfzeile werden in der Seite als page.variable bezeichnet. Zum Beispiel, diese Seite:

---
name: Science
---
Today we are going to study {{page.name}}.

wird übersetzt in:

<html>
  <body>
    <p>Today we are going to study Science.</p>
  </body>
</html>

Übung: Die Syntax von Jekyll

Testen Sie Ihr Verständnis von Jekylls Syntax. In was würde diese Vorlage übersetzt werden?
---
name: Tom
location: Heidelberg
---
{{page.name}} is in {{page.location}}. I believe {{page.location}} is a very nice city.
Lösung
<html>
  <body>
    <p>Tom is in Heidelberg. I believe Heidelberg us a very nice city.</p>
  </body>
</html>

Die Hauptkonfigurationsoptionen von Jekyll werden jedoch in einer anderen Datei namens _config.yml angegeben. Lassen Sie uns einige Konfigurationsparameter für unsere Website erstellen.

Erstellen Sie eine _config.yml-Datei im Stammverzeichnis Ihrer Website.
Fügen Sie die Parameter description und email hinzu als:

description: This project develops training materials for reseachers wanting to learn to build project
websites in GitLab Pages.
email: team@carpentries.org

Globale Konfigurationseinstellungen von _config.yml werden als site.PARAMETER_NAME-Variable in jeder Seite innerhalb der Website verfügbar gemacht. Auf den globalen Parameter email, den wir oben definiert haben, würde also als site.email zugegriffen werden. Bitte beachten Sie: Es handelt sich um globale Parameter, die sich von den lokalen seitenbezogenen Parametern in den obigen Beispielen unterscheiden.

Um auf den Wert des Parameters innerhalb einer Seite zuzugreifen, verwenden Sie die Liquid-Notation, um den Inhalt auszugeben, indem Sie eine Variable in geschweifte Klammern wie {{ variable }} einschließen.

Vordefinierte globale Parameter

Zusätzlich zu den globalen Parametern, die Sie definieren, stellt Ihnen Jekyll auch eine Reihe von nützlichen vordefinierten seitenweiten Variablen innerhalb Ihrer Website zur Verfügung: z.B. {{ site.time }} (die aktuelle Zeit) oder {{ site.pages }} (eine Liste aller Seiten).

Erstellen Sie eine index.md Datei im Stammverzeichnis, mit dem folgenden Inhalt:

---
title: My first Jekyll page
---

# Building Websites with Jekyll and GitLab

## Description
{{ site.description }}
Welcome to {{ page.title }}

Have any questions about what we do? [We'd love to hear from you!](mailto:{{ site.email }})

Ihr Projekt sollte die folgenden Dateien enthalten:

Basic Jekyll

Commit und push Ihre Änderungen, dann überwachen Sie die Ausführung der Pipeline und überprüfen Sie das Endergebnis unter Ihrer https://<your user name>.embl-community.io/group-website URL.

Übung: Einen globalen Twitter-Parameter erstellen

In about.md haben wir eine Twitter URL unter dem Abschnitt ‘Contact us’. Das ist eine Information, die in die globalen Parameter in _config.yml aufgenommen werden könnte, da Sie sie vielleicht in der Fußzeile jeder Seite wiederholen möchten. Nehmen Sie Änderungen an Ihrer Website vor, um die Twitter-URL als globalen Parameter zu extrahieren.
Lösung
Füge den Parameter twitter zu _config.yml hinzu:
description: "This research project develops training materials for reseachers wanting to learn to build project
websites in GitHub with GitHub Pages."
email: "team@carpentries.org"
twitter: "https://twitter.com/thecarpentries"
Benutzen Sie den Twitter-Parameter in about.md:
# About

## Project

{{ site.description }}

## Funders

We gratefully acknowledge funding from the XYZ Founding Council, under grant number 'abc'.

## Cite us

You can cite the project as:

> *The Carpentries 2019 Annual Report. Zenodo. https://doi.org/10.5281/zenodo.3840372*

## Contact us

- Email: [{{ site.email }}](mailto:{{ site.email }})
- Twitter: [{{ site.twitter }}]({{ site.twitter }})
Beachten Sie, dass Sie eigentlich keine Änderungen an Ihrer Website sehen sollten. Allerdings können Sie jetzt von jeder Seite Ihrer Website aus auf Ihre Twitter-URL zugreifen, falls Sie dies wünschen.

Lokale Parameter

Zusätzlich zu den globalen (site-weiten) Parametern, die über die globale Variable site verfügbar sind, stellt Jekyll lokale (seiten-spezifische) Informationen über die Variable page zur Verfügung. Einige davon sind vordefiniert - wie page.title, die Ihnen den Titel der Seite gibt, die gerade aktiv ist/besucht wird. Andere können Sie selbst definieren. Sehen Sie sich diese Liste der vordefinierten Seitenparameter an.

Sie können innerhalb einer Markdown-Seite lokale Parameter in YAML-Notation definieren, indem Sie diese in einen Seitenkopf einfügen und den Kopf mit dreifach gestrichelten Linien --- abgrenzen. Diese Header werden front matter genannt und dienen dazu, Variablen und Metadaten auf einzelnen Seiten Ihrer Jekyll-Site zu setzen.

Titelbild

Von Jekylls Website:

Jede Datei, die einen YAML-Frontmaterie-Block enthält, wird von Jekyll als eine spezielle Datei verarbeitet. Der Frontmatter muss das erste Element der Datei sein und muss die Form von gültigem YAML haben, das zwischen dreifach gestrichelten Linien steht.

Globale und lokale Parameter sind Case Sensitive

Es ist wichtig zu beachten, dass die in den Seiten verwendeten Parameter zwischen Groß- und Kleinschreibung unterscheiden. Normalerweise werden sie alle in Kleinbuchstaben geschrieben.

Hier ist ein Beispiel:

---
layout: post
title: "My first blog post"
author: "Danger Mouse"
---

Zwischen diesen dreifach gestrichelten Linien können Sie vordefinierte Variablen (wie page.layout oder page.title) überschreiben oder benutzerdefinierte Variablen erstellen, die Sie lokal auf der Seite benötigen (wie page.author). Auf diese Variablen können Sie dann über die Tags von Liquid (z. B. {{ page.title }} ) weiter unten in der Datei und in allen Dateien, die diese enthalten, zugreifen. Beachten Sie, dass diese Variablen nur auf dieser Seite zugänglich sind. Sie erhalten eine Fehlermeldung, wenn Sie versuchen, auf eine page.variable zu verweisen, die auf einer anderen Seite definiert wurde.

Übung: Übung mit lokalen Variablen

Lassen Sie uns die Erstellung und Verwendung lokaler Variablen üben. Denken Sie an eine lokale Variable, die Sie nur auf Ihrer Seite about.md oder index.md verwenden wollen. Wenn Ihnen keine einfällt, erstellen Sie eine lokale Variable mit dem Namen ‘lesson-example’ mit dem Wert ‘https://carpentries.github.io/lesson-example/’ und verweisen Sie auf sie in Ihrer index.md.

Was haben Sie zu Ihrem index.md hinzugefügt, um diese Variable zu erstellen? Wo haben Sie das Frontmate in Ihrer index.md eingefügt? Wie haben Sie diese Variable referenziert?
Lösung

Erstellen Sie einen YAML-Header ganz oben in index.md und fügen Sie die Variable lesson-example zwischen den dreifachen Trennstrichen ein. Sie können dann auf den Wert innerhalb Ihrer index.md Seite als {{ page.lesson-example }} verweisen. Ihre Datei sollte nun wie folgt aussehen:
---
lesson-example: "https://carpentries.github.io/lesson-example/"
---

# Building Websites in GitHub

## Description
{{ site.description }}

More details about the project are available from the [About page](about).

See some [examples of our work]({{ page.lesson-example }}).

Have any questions about what we do? [We'd love to hear from you!](mailto:{{ site.email }})
Beachten Sie, dass diese Variable nicht von der Seite about.md aus zugänglich ist und lokal auf index.md liegt.

Hinzufügen neuer Seiten

Der nächste Schritt wird sein, eine weitere Seite dieser Website zu erstellen. Idealerweise wird unsere Website mehrere Seiten haben, und um Ordnung zu halten, werden wir den Ordner pages erstellen, um sie zu speichern. Erstellen Sie in diesem Ordner eine about.md-Datei mit folgendem Inhalt:

---
title: About
permalink: /about/
---

# About

## Project

{{ site.description }}

## Funders

We gratefully acknowledge funding from the XYZ Founding Council, under grant number 'abc'.

## Cite us

You can cite the project as:

>    *The Carpentries 2019 Annual Report. Zenodo. https://doi.org/10.5281/zenodo.3840372*

## Contact us

- Email: [{{ site.email }}](mailto:{{ site.email }})
- Twitter: [@thecarpentries](https://twitter.com/thecarpentries)

Beachten Sie, dass die URL dieser Seite in der Kopfzeile durch das Attribut permalink angegeben ist.

Dies ist der aktuelle Aspekt Ihres Ordners:

Über Jekyll

Nun sollten wir die Datei index.md editieren, um einen Link zu dieser neuen About-Seite einzufügen, damit sie von der Hauptseite aus erreicht werden kann. Fügen Sie eine Zeile in index.md ein:

More details about the project are available from the [About page](about).

Der Link in dieser Zeile wird auf https://<your user name>.embl-community.io/group-website/about umleiten, das ist die URL unserer neuen About-Seite.

Commit, push und gehen Sie auf Ihre Website, um die Änderungen zu sehen. Beachten Sie, dass Site-Parameter bei der Anzeige von Dateien in GitHub nicht korrekt dargestellt werden (sie werden als Text {{ site.PARAMETER_NAME }} und nicht als gerenderter Wert des Parameters angezeigt), aber auf der Website schon.

Wiederverwenden und Reduzieren

Jekylls globale Parameter sind ein nützlicher Weg, um all Ihre site-weiten Konfigurationen an einem einzigen Ort zu halten (selbst wenn Sie sie nur einmal benutzen). In Kombination mit Jekyll-Layouts/Vorlagen (die in der nächsten Folge behandelt werden) sind sie eine großartige Möglichkeit, wiederverwendbare Markup-Snippets zu erstellen, die auf mehreren oder sogar auf jeder Seite Ihrer Website wiederholt werden können. Wiederverwendung hilft Ihnen, die Menge an Code zu reduzieren, die Sie schreiben müssen.

Nützliche Links

Dies sollte nur ein sehr grundlegendes Tutorial sein. Die Möglichkeiten der Seitenanpassung mit Jekyll gehen weit über das hinaus, was hier gezeigt wurde, man könnte zum Beispiel:

Entwurf von Seitenlayouts (wie die Übungen/Lösungen in dieser Lektion),
mit Schleifen arbeiten, um Variablen mit mehreren Werten iterativ zu verarbeiten,
Verwenden Sie Filter, um das Format der Variablen zu kontrollieren, wenn sie in eine Seite eingefügt werden,

und mehr. Diese Lektion von The Carpentries ist, auch wenn sie für GitHub konzipiert ist, eine wertvolle Ressource, um mehr darüber zu erfahren, wie man das macht.

Wenn Sie nach der offiziellen GitLab-Dokumentation über GitLab Pages mit Jekyll suchen, folgen Sie diesem Link.

Schließlich enthält dieses Projekt eine ausgefeiltere Vorlage für eine auf GitLab und Jekyll basierende Website.

Key Points

Through Jekyll, GitLab serves pages are generated from .md files

GitLab-Seiten mit Sphinx

Overview

Teaching: 0 min
Exercises: 0 min

Questions

How do I publish web pages through GitLab and Sphinx?

Objectives

Publish reStructuredText files as HTML on the web with GitHub Pages

Sphinx ist ein Werkzeug zur Generierung von Webseiten oder PDF, das hauptsächlich für die Erstellung einer Projektdokumentation entwickelt wurde. Es wurde ursprünglich für die Python-Dokumentation entwickelt, verfügt aber über ausgezeichnete Möglichkeiten für die Dokumentation von Softwareprojekten in einer Reihe von Sprachen. Polyglotte Dokumentationssysteme können sehr nützlich sein, wenn Ihr Projekt an Komplexität oder Anzahl der Mitarbeiter zunimmt, also beachten Sie dies.

In diesem Kapitel der Lektion werden wir die Programmiersprache Python verwenden. Auch wenn dies nicht unbedingt notwendig ist, empfehlen wir Ihnen, sich mit Python vertraut zu machen, da die Erklärung dieser Sprache nicht Gegenstand dieser Lektion ist. Sie können dies tun, indem Sie die Lektion [Programmieren mit Python] (https://swcarpentry.github.io/python-novice-inflammation/) durcharbeiten.

Übung: Dokumentation

Lassen Sie in einer Gruppe jedes Mitglied die Dokumentation eines der folgenden Pakete öffnen

pytest

seaborn

numpy

scipy-cookbook

scikit-learn

Diskutieren Sie, was die gemeinsamen Komponenten sind, was an diesen Dokumentations-Sites hilfreich ist, wie sie die allgemeinen Konzepte zur Dokumentation ansprechen, wie sie sich ähneln und wie sie sich unterscheiden.

Während Jekyll Markdown-Dateien (.md) in HTML konvertiert, konvertiert Sphinx reStructureText-Dateien (.rts). Obwohl diese beiden Formate auf den ersten Blick sehr ähnlich erscheinen, wurden sie für zwei unterschiedliche Zwecke entwickelt: Markdown zum Schreiben für das Web, reStructuredText zum Schreiben von Dokumentation. [In diesem Blogbeitrag (https://www.zverovich.net/2016/06/16/rst-vs-markdown.html) erfahren Sie mehr darüber, was das in der Praxis bedeutet. Der wichtigste Punkt, den wir in diesem Zusammenhang hervorheben möchten, ist, dass reStructuredText auch für die Konvertierung in PDF gut geeignet ist. Das macht es zu einem nützlichen Werkzeug auch für die Entwicklung von Dokumenten, die Sie sowohl online als auch in Papierform benötigen, z.B. Schulungsunterlagen oder eine Meeting-Agenda.

Sphinx-Schnellstart

Aus Gründen der Übersichtlichkeit werden sich die nächsten Schritte dieses Kapitels nur auf die Sphinx-Dateien konzentrieren, die für die Erzeugung von HTML-Dateien relevant sind. Durch die lokale Installation von Sphinx können Sie jedoch den Quickstart-Befehl ausführen, um ein grundlegendes Sphinx-Projekt zu starten. Wir empfehlen diese Option, wenn Sie Ihr Verständnis für das Dokumentieren mit Sphinx vertiefen möchten. Zu diesem Zweck berichten wir hier über die notwendigen Schritte.

Auf Ihrem System ist Sphinx wahrscheinlich bereits installiert. Prüfen Sie, ob dies der Fall ist, indem Sie in Ihrem Terminal eingeben:
sphinx-build --version
Wenn das nicht der Fall ist, können Sie die Installation durch Eingabe von:
pip install -U sphinx
Oder lesen Sie die detaillierten Installationsanweisungen hier. Sobald Sphinx installiert ist, können wir den Quickstart-Befehl ausführen, um einen Überblick über den minimalen Satz an Dateien zu erhalten, die zur Erstellung der Dokumentation erforderlich sind. Mit dem folgenden Befehl wird ein leeres Repository erstellt und der Befehl dort ausgeführt:
mkdir sphinx-quickstart-test
cd sphinx-quickstart-test
sphinx-quickstart
...
Separate source and build directories (y/n) [n]:
...
Project name: My project
Author name(s): <Your name>
Project release []:
...
Project language [en]:
Es werden mehrere Dokumente erzeugt. Hier ein Überblick:

Die Dateien, die für uns in diesem Zusammenhang relevant sind, sind die index.rst-Datei - das ist das Äquivalent zu unserer index.md-Datei im Beispiel mit Jekyll - und die conf.py-Datei. Deshalb werden in dieser Lektion auch nur diese beiden Dateien behandelt.

Erstellen Sie einen leeren Projektordner. Lassen Sie uns unsere index.rst-Datei im Stammordner unseres Projekts initialisieren.

.. this is a comment, it is not rendered

Sphinx Example Project's documentation
======================================

Contents:

.. toctree::
    :maxdepth: 2

Es meldet die Hauptüberschrift unseres Projekts, und dann ein Inhaltsverzeichnis durch den “TOC-Baum”. Es kann eine numerische Option maxdepth angegeben werden (wir haben sie auf 2 gesetzt), um die Tiefe des Baums anzugeben; standardmäßig werden alle Ebenen einbezogen. Mehr über den Toc-Baum unter dieser Link. Kurz gesagt, wenn wir *.rst-Dateien zu unserem Inhaltsverzeichnis hinzufügen, sollten sie hier aufgeführt werden. Fügen wir eine Datei hinzu, um zu sehen, wie das funktioniert.

Erstellen Sie eine Datei about.rst, ebenfalls im Hauptstammordner, mit dem Inhalt:

About
=====

Hello, this is the about page of my project.

Nun fügen wir diese Datei dem TOC-Baum hinzu, indem wir die Datei index.rst bearbeiten:

.. this is a comment, it is not rendered

Sphinx Example Project's documentation
======================================

Contents:

.. toctree::
    :maxdepth: 2

    about.rst

Das war’s: Unsere Homepage (die mit der Datei index.rst erzeugt wurde) verlinkt nun auf die Über-Seite (about.rst). Als nächstes schreiben wir eine minimale conf.py Datei, ebenfalls im Stammverzeichnis.

# -- Project information -----------------------------------------------------

project = 'My project'
copyright = '2021, <Your name>'
author = '<Your name>'
release = '1.0'

# -- Options for HTML output -------------------------------------------------

html_theme = 'alabaster'

Eine vollständige Liste der Optionen, die in dieser Datei angegeben werden können, finden Sie in der documentation.

Sphinx-Schnellstart

Auch hier hilft es Ihnen, wenn Sie Sphinx lokal installiert haben, um die nächsten Schritte durchzuführen. In der Tat können Sie Ihre Dokumentations-Website lokal mit dem Befehl sphinx-build . build/ erstellen, der in Ihrem Stammverzeichnis ausgeführt wird. Nach der Ausführung wird Ihre Ausgabewebsite im Ordner build/ erstellt. Sie können sie einfach visualisieren, indem Sie die Datei index.html in Ihrem Lieblingsbrowser öffnen.

Auch in diesem Fall ist die Datei .gitlab-ci.yml erforderlich, um Anweisungen für die Bereitstellung in GitLab anzugeben. Füllen Sie sie mit:

pages:
  stage: deploy
  image: python:3.6
  script:
    - pip install -U sphinx
    - sphinx-build -b html . public
  artifacts:
    paths:
      - public

Dieses Skript: gibt den Container für unsere Pipeline an (Python, Version 3.6), installiert Sphinx durch Pip, führt den Befehl sphinx-build aus - der HTML-Dateien im Stammordner (.) in einen public-Ordner baut, den es ebenfalls erstellt. Schließlich gibt er an, wo die HTML-Artefakte zu finden sind (in der Tat im Ordner public).

Das war’s schon. Jetzt sollten wir noch einmal dem Abschnitt “Einrichten eines Projekts” in der [Einführung] (https://grp-bio-it-workshops.embl-community.io/building-websites-with-gitlab/01-introduction/index.html) folgen, um ein entferntes Projekt in GitLab einzurichten, und es als entfernt für unseren lokalen Ordner mit git remote add origin <git URL>, git add . && git commit -m <message> und dann git push -u festlegen. Überwachen Sie schließlich die Ausführung Ihrer Pipeline und prüfen Sie das Endergebnis.

Key Points

Through Sphinx, GitLab serves pages are generated from .rst files

GitLab-Seiten mit Jupyter-Büchern

Overview

Teaching: 0 min
Exercises: 0 min

Questions

How do I publish web pages through GitLab and Jupyter books?

Objectives

Publish Jupyter notebooks as HTML on the web with GitHub Pages

Lassen Sie uns etwas anderes machen, das ein wenig vertrauter klingt, wenn Sie mit den Jupyter Projekten vertraut sind. Von deren Website:

Das Projekt Jupyter dient der Entwicklung von Open-Source-Software, offenen Standards und Diensten für interaktives Rechnen in Dutzenden von Programmiersprachen.

Jupyter-Notizbücher ermöglichen es Ihnen, Dokumente zu erstellen und auszutauschen, die sowohl Live-Code als auch erzählenden Text enthalten. Jupyter Lab erweitert ihre Funktionalitäten durch die Schaffung einer interaktiven Entwicklungsumgebung (die es Ihnen ermöglicht, in Ihrem Dateisystem zu navigieren und die Codierungsumgebung zu definieren). Jupyter Hub ist eine Mehrbenutzerversion von Jupyter Lab, die Institutionen lokal implementieren können (wie wir am EMBL).

Und Jupyter-Buch?

Jupyter Book ist ein Open-Source-Projekt zur Erstellung von schönen, publikationsreifen Büchern und Dokumenten aus Berechnungsmaterial.

Das ausführliche Tutorial wird Sie durch die Installationsschritte und die detaillierten Anpassungsmöglichkeiten führen, im Rahmen dieser Lektion werden wir nur die Grundlagen behandeln. Das Wichtigste zuerst: Installieren wir Jupyter Book. In Ihrem Terminal:

pip install -U jupyter-book

Bitte beachten Sie: Sie müssen auch pip installiert haben. Lassen Sie uns nun unser erstes Buchprojekt erstellen. Der Befehl jupyter-book --help würde uns dabei helfen, die Optionen zu überprüfen, aber diese Lektion wird etwas spoilern: die

jupyter-book create jupyter-book-demo

Befehl erstellt ein einfaches Jupyter-Buch in einem jupyter-book-demo-Ordner. Dieser Ordner enthält bereits die drei Dinge, die zum Erstellen eines Buches benötigt werden: eine _config.yml-Datei, ein _toc.yml-Inhaltsverzeichnis und den Inhalt des Buches in einer Sammlung von MarkDown-, reStructuredText- oder Jupyter Notebook-Dateien.

Da wir von der ganzen Entwicklung und Bereitstellung müde sind, wollen wir nicht wirklich etwas am Inhalt ändern, aber wir priorisieren stattdessen, dass er in GitLab läuft. Raten Sie mal, was wir hinzufügen müssen? In der Tat eine .gitlab-ci.yml-Datei.

pages:
  stage: deploy
  image: python:slim
  script:
    - pip install -U jupyter-book
    - jupyter-book clean .
    - jupyter-book build .
    - mv _build/html public
  artifacts:
    paths:
      - public

Dieser Teil des Codes:

Installiert jupyter-book (oder prüft, ob es korrekt installiert ist).
Säubert den Ordner von Dateien, die von (eventuellen) früheren Builds stammen.
führt den Befehl jupyter-book build . aus, der das Buch im Ordner in einem Unterordner _build erstellt. Sie können die Ausgabe überprüfen, indem Sie den gleichen Befehl in Ihrem Terminal ausführen, und Sie werden feststellen, dass sich die eigentlichen HTML-Dateien im Unterordner _build/html befinden.
Es verschiebt dann den HTML-Inhalt in unseren üblichen public-Ordner, wo die Artefakte gespeichert sind.

Deine Zeit zum Experimentieren mit einer Vorlage

Diese Vorlage ist absichtlich minimal gehalten, um Ihnen die Möglichkeit zu geben, Ihre Fähigkeiten beim Lesen der Dokumentation zu testen. Schauen Sie sich die Themenleitfäden auf jupyterbook.org an und finden Sie einen Weg, um:

Fügen Sie eine weitere Seite mit dem Namen “Über” hinzu, die mit dem Inhaltsverzeichnis verlinkt ist.

Spielen Sie mit dem Dateiformat dieser neuen Seite, fügen Sie die gleiche Art von Inhalt in den Formaten MarkDown, reStructuredTex und Notebook hinzu.

Füge eine Abbildung und eine Bildunterschrift hinzu.

Fügen Sie eine Codezelle ein. Wenn Sie mit einer Programmiersprache vertraut sind, fügen Sie einen einfachen Plot ein und visualisieren Sie die Ausgabe dieses Plots in Ihrer Seite.

Für weitere fortgeschrittene Code-Funktionen, siehe how to make the code executable

Schauen Sie in der Galerie der Jupyter-Bücher nach, um sich inspirieren zu lassen!

Key Points

Through Jupyter books, you’ll be able to integrate interactive components and code in your web pages

GitLab-Vorlagen

Overview

Teaching: 0 min
Exercises: 0 min

Questions

Where can I find pre-built projects/themes for my site?

Objectives

Find and fork pre-existing templates to determine the technologies behind a project and the styles of the deriving website

Bio-IT-Vorlagen

Die Vorlagen, die wir gemeinsam entwickelt haben, sind in unserer GitLab-Plattform verfügbar:

Sie könnten im Vergleich zu dem, was wir in dieser Lektion durchgenommen haben, leicht angereichert sein, zum Beispiel enthält die einfache HTML-Vorlage auch eine .css-Datei, aber sie sind absichtlich minimal gehalten. Wenn Sie sie als Basis für Ihr eigenes Projekt verwenden wollen, sollten Sie sie aufspalten. Wenn Sie dies tun, um Ihr eigenes Projekt zu entwickeln und nicht, um zur Vorlage selbst beizutragen, sollten Sie als nächstes die Fork-Beziehung aufheben. Lassen Sie uns den Prozess gemeinsam durchgehen.

ein Repository über die Schaltfläche Fork forken

Forken Sie ein Projekt, indem Sie auf die Schaltfläche “Fork” auf der rechten Seite des Projekttitels klicken. Daraufhin öffnet sich ein Menü (siehe unten), das dem Menü, das beim Öffnen eines neuen Projekts angezeigt wird, sehr ähnlich ist. Sie können entscheiden, ob Ihr Projekt privat bleiben soll, und den Titel und die Beschreibung bearbeiten. Sie können es auch in die entsprechende Gruppe/den entsprechenden Namensraum einordnen.

Sobald Sie fertig sind, entfernen Sie bitte die Fork-Beziehung. Sie können die Projekteinstellungen im linken Menü auf der Projektseite bearbeiten, folgen Sie Settings > General > Advanced und scrollen Sie dann nach unten zur Karte “Remove fork relationship”.

remove fork relationship

Sobald dies erledigt ist, können Sie Ihr Repository lokal klonen und mit der Bearbeitung der Vorlage beginnen. Wenn Sie eine Zusammenfassung über Klonen, Forking, Pushing und Pulling in Git benötigen, lesen Sie bitte [diese Lektion] (https://swcarpentry.github.io/git-novice/) von The Carpentries.

Weitere Vorlagen

Sie fragen sich, wo Sie weitere Beispiele für GitLab-Seitenprojekte finden können? Sehen Sie sich diesen Link an. Er enthält mehr als 40 Beispiele, die auf verschiedenen Technologien basieren. Auch in diesen Fällen ist es eine gute Praxis, die Fork-Beziehung zu entfernen, wenn Ihr Ziel darin besteht, die Vorlage für die Entwicklung Ihrer eigenen Website zu verwenden und nicht, zur Vorlage selbst beizutragen. Einige Beispiele für Vorlagen, die Sie in diesem Repository finden, sind:

courseware-template, eine Jekyll-basierte Vorlage für eine Kurs-Website. Sie können es hier in Aktion sehen. Es enthält Stile zur Formatierung von Vorlesungsinhalten, Quizfragen und Folien.
hugo blog template, die Vorlage für build blogs basierend auf Hugo.
jupyterbook, eine Vorlage zur Erstellung von Büchern und Dokumenten, die Python-Code integrieren. Sehen Sie es gerendert hier.

Jetzt haben Sie das nötige Fachwissen, um mit GitLab-Seiten zu arbeiten. Wenn Sie Fragen haben, wenden Sie sich bitte an contact us oder öffnen Sie ein Issue in den Template-Projekten, um Funktionen anzufordern oder Probleme zu lösen. Sie sind auch herzlich eingeladen, zur Entwicklung von Seitenvorlagen beizutragen, sowohl zu den bestehenden als auch zu neuen, die für Ihre Anwendungsfälle geeignet sein könnten. Schauen Sie sich schließlich das nächste (Bonus-)Kapitel an, um zu erfahren, wie man mit Fehlern in der Pipeline-Ausführung umgeht, um eventuelle CI/CD-Fehler beheben zu können!

Key Points

You can find many pre-existing templates for sites on the Internet

You can find the presented themes for sites in our local GitLab

You can avoid duplicated effort by basing new layouts on previous ones

Wenn etwas schief geht

Overview

Teaching: 0 min
Exercises: 0 min

Questions

How do I troubleshoot errors in the GitLab pipelines?

Objectives

Get feedback from GitLab about why a pipeline failed

Wenn etwas schief geht

Bis jetzt haben wir gesehen, wie man erfolgreich verschiedene Technologien zur Erstellung einer Website einsetzt. Es gibt jedoch einige Situationen, in denen dies aufgrund eines Tippfehlers oder fehlender Informationen nicht möglich ist. Wir werden einen dieser Fälle anhand eines Jekyll-Beispiels durchgehen.

Übung: Fehlersuche in Jekyll

Diese Übung soll Ihnen helfen zu erkennen, wie häufige Fehler bei der Arbeit mit diesen Elementen einer Jekyll-Website aussehen.

Bearbeiten Sie Ihre _config.yml Datei und ersetzen Sie ein : durch ein = Zeichen in einer der Variablen.
Lösung

Zum Beispiel mail=team@carpentries.org anstelle von mail:team@carpentries.org.
description: "This research project develops training materials for reseachers wanting to learn to build project
websites in GitHub with GitHub Pages."
email: "team@carpentries.org"
twitter: "https://twitter.com/thecarpentries
Wenn Sie in Ihrem GitHub-Repository navigieren, könnten Sie sehen, dass etwas in about.md kaputt geht, wo wir {{ site.twitter }} verwenden. Im Gegensatz zu dem, was wir zuvor mit ungültigem Markdown gesehen haben, weigert sich Jekyll jedoch, die Website zu erstellen und gibt eine Fehlermeldung aus.

Danach werden wir sehen, wo die Fehlermeldung zu finden ist und was sie verursacht hat.

Wenn Sie die Seite zur Ausführung der GitLab-Pipeline bis jetzt im Auge behalten haben (CI/CD > Pipelines), ist Ihnen vielleicht aufgefallen, dass die Ergebnisse der Pipeline nach dem Verschieben “ausstehend” sind, dann “laufen” und schließlich “bestanden” werden. Irgendwann. Wenn dies nicht der Fall ist, lautet der Status “fehlgeschlagen”, Sie erhalten möglicherweise eine E-Mail darüber (je nach den Einstellungen Ihres GitLab-Kontos) und sollten nicht in Panik geraten. Wie können wir stattdessen verstehen, was den Fehler verursacht hat, und ihn beheben? Der Status “fehlgeschlagen” ist zufällig eine Schaltfläche, klicken wir sie an.

Klicken Sie auf die Schaltfläche "failed", um das Pipeline-Protokoll
aufzurufen

Auch hier können Sie auf die Schaltfläche ❌ Seiten klicken, um auf weitere Details zuzugreifen, z. B. auf das vollständige Protokoll der Ausführung unserer Pipeline. Scrollen Sie im terminalähnlichen Fenster nach oben, um zu sehen, wie die Pipeline gestartet, die Umgebungen vorbereitet, die Abhängigkeiten installiert und bis zum Befehl bundle exec jekyll build - public korrekt ausgeführt wurde. Erinnern Sie sich daran? Es ist der Befehl, der Jekyll startet, wir haben ihn in die Datei .gitlab-ci.yml aufgenommen.

Wir haben Grund zu der Annahme, dass der Fehler hier damit zusammenhängt, dass Jekyll die Seite nicht erstellen kann. Wenn wir genauer lesen, um mehr Details zu erhalten, finden wir:

$ bundle exec jekyll build -d public
                    ------------------------------------------------
      Jekyll 4.2.1   Please append `--trace` to the `build` command
                     for any additional information or backtrace.
                    ------------------------------------------------
/usr/local/bundle/gems/safe_yaml-1.0.5/lib/safe_yaml/load.rb:143:in `parse': (/builds/hpg_ToyM/0/grp-bio-it/template-pages-jekyll/_config.yml): could not find expected ':' while scanning a simple key at line 3 column 1 (Psych::SyntaxError)

Dies bedeutet zwei Dinge: Erstens schlägt das Protokoll einen Weg vor, um mehr Details zu erhalten, d.h. die Datei .gitlab-ci.yml zu modifizieren, indem man --trace zum Befehl bundle exec jekyll build -d public hinzufügt, der so zu bundle exec jekyll build -d public --trace wird. Aber das brauchen wir nicht wirklich: der nächste Satz ist klar genug. Er besagt, dass es einen Fehler beim Parsen der Datei _config.yml gab, weil Jekyll das erwartete Zeichen : nicht finden konnte. Da dieser Tippfehler Jekyll daran hindert, die Seite zu erstellen, kann der Prozess nicht fortgesetzt werden.

Bei Misserfolg wird Ihre Website nicht entfernt

Angesichts des Fehlers fragen Sie sich vielleicht, was mit der Website passiert ist? Wenn Sie die Adresse besuchen, werden Sie feststellen, dass die Website immer noch verfügbar ist.

GitLab hält Ihre vorherige Version online, bis der Fehler behoben ist und ein neuer Build erfolgreich abgeschlossen wurde.

Wir sollten zu unserer Datei _config.yml zurückkehren und den Fehler = beheben, den wir (diesmal absichtlich) gemacht haben. Dann pushen Sie das Projekt erneut, und das Problem ist gelöst!

Übung: Übung mit der Fehlersuche in Jekyll

Manchmal passieren Tippfehler und können Ihre Website auf überraschende Weise verändern. Lassen Sie uns mit einigen möglichen Problemen experimentieren und sehen, was passiert.

Probieren Sie die unten aufgeführten Änderungen an Ihrer index.md-Datei aus und beobachten Sie, was passiert, wenn die Seite gerendert wird. Sie werden jedes Mal den vorherigen Fehler korrigieren wollen.

Verwenden Sie eine globale oder lokale Variable, die Sie nicht vorher definiert haben.

Lassen Sie den Bindestrich am Ende des YAML-Headers weg.

Fügen Sie kein Leerzeichen zwischen dem YAML-Header und dem Rest der Seite ein

Setzen Sie den YAML-Header an eine andere Stelle in der Seite.
Lösung
Die Stelle, an der Sie die undefinierte Variable verwendet haben, ist leer, aber ansonsten kein Fehler. Beispiel:
Hi! {{ site.greeting }}. What have you been up to?
Die Kopfzeile zeigt etwas in der Datei an und die Variable, die definiert wurde, geht zur Indexseite anstelle des Links, den wir gesetzt haben.
---
lesson-example: "https://carpentries.github.io/lesson-example/"

Examples of our work can be found at: {{ page.lesson-example }}
Dies scheint unsere Seite nicht zu beeinträchtigen, kann aber oft dazu führen, dass komplexere Seiten abbrechen.
---
lesson-example: "https://carpentries.github.io/lesson-example/"
---
Examples of our work can be found at: {{ page.lesson-example }}
Dadurch wird auch die Kopfzeile auf der Seite angezeigt und die von uns erstellte variable Verknüpfung unterbrochen.
Examples of our work can be found at: {{ page.lesson-example }}
---
lesson-example: "https://carpentries.github.io/lesson-example/"
---
Hinweis: Beheben Sie alle Fehler, die Sie absichtlich in Ihre Seite eingefügt haben, bevor Sie weitermachen.

Key Points

If a pipeline fails, GitLab will provide you useful feedback on why

Erstellen von Websites mit GitLab

Einführung

Overview

Wie Websites funktionieren

Hallo Welt in HTML

Die vielen Tags in HTML

Übung: Grundlegendes HTML schreiben

Hello, World!

Lösung

Statische vs. dynamische Sites

Beispiele aus dem Bereich der Biowissenschaften

Übung: Das perfekte Werkzeug für den Job

Lösung

GitLab-Seiten

Einrichten eines Projekts

Melden Sie sich bei Ihrem GitLab-Konto an

GitLab vs GitHub

Key Points

Verfassen mit Markdown

Overview

Markdown

Where to Start Writing Markdown?

Schreiben einer Commit-Nachricht

Markdown schreiben

Markdown Trailing Spaces Are Meaningful

Übung: Ausprobieren von Markdown

Beispiellösung

Referenz-Stil Links

Markdown Flavours

Übung: Fügen Sie Ihre Repository-Details zu CodiMD hinzu

Key Points

Hosting von Seiten auf GitLab

Overview

GitLab-Seiten

Nur statische Webseiten

Lokal oder in GitLab arbeiten

Validierung der Datei gitlab-ci.yml

Git-Zweige und GitLab CI-Dateien

Lokal oder in GitLab arbeiten

Lokal oder in GitLab arbeiten

Übung: Vergleichen Sie mit Ihrer Skizze

Übung: Die plain-html Vorlage

Lösung

Nützliche Links

Key Points

GitLab-Seiten mit Jekyll

Overview

Globale Parameter

Übung: Die Syntax von Jekyll

Lösung

Vordefinierte globale Parameter

Übung: Einen globalen Twitter-Parameter erstellen

Lösung

Lokale Parameter

Titelbild

Globale und lokale Parameter sind Case Sensitive

Übung: Übung mit lokalen Variablen

Lösung

Hinzufügen neuer Seiten

Wiederverwenden und Reduzieren

Nützliche Links

Key Points

GitLab-Seiten mit Sphinx

Overview

Übung: Dokumentation

Sphinx-Schnellstart

Sphinx-Schnellstart

Key Points

GitLab-Seiten mit Jupyter-Büchern

Overview

Deine Zeit zum Experimentieren mit einer Vorlage

Key Points

GitLab-Vorlagen

Overview

Bio-IT-Vorlagen

Weitere Vorlagen

Key Points

Wenn etwas schief geht

Overview

Wenn etwas schief geht