Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: update docs #227

Merged
merged 3 commits into from
Mar 21, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/validate.yml
Original file line number Diff line number Diff line change
Expand Up @@ -42,8 +42,8 @@ jobs:
- name: Install dependencies
run: pnpm install --frozen-lockfile

- name: Lint commit messages
uses: acdh-oeaw/commitlint-action@v1
# - name: Lint commit messages
# uses: acdh-oeaw/commitlint-action@v1

- name: Format
run: pnpm run format:check
Expand Down
3 changes: 2 additions & 1 deletion app/api/keystatic/[...params]/route.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,14 @@ const { GET: _GET, POST: _POST } = makeRouteHandler({ config });
function rewriteUrl(request: Request) {
const forwardedHost = request.headers.get("x-forwarded-host");
const forwardedProto = request.headers.get("x-forwarded-proto");
const forwardedPort = request.headers.get("x-forwarded-port");

if (isNonEmptyString(forwardedHost) && isNonEmptyString(forwardedProto)) {
const url = new URL(request.url);

url.hostname = forwardedHost;
url.protocol = forwardedProto;
url.port = "";
url.port = forwardedPort ?? "";

return new Request(url, request);
}
Expand Down
22 changes: 11 additions & 11 deletions content/documentation/de/howto.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -41,9 +41,9 @@ Forschende und Mitarbeiter\*innen am ACDH-CH können mithilfe der Plattform ihr

Dann sind Sie hier genau richtig! Mithilfe der Learning Resources Plattform und der folgenden Schritt-für-Schritt Anleitung können Sie Ihr Wissen ganz einfach mit anderen teilen.

<SideNote type="info" title="Hinweis:">
<Callout kind="note" title="Hinweis">
Die folgenden Abschnitte zeigen die Erstellung von Inhalten ausgehend von einer Idee. Falls bereits ein Textentwurf, ein ausgearbeiteter Text oder Übungsmaterialien vorliegen, kann man direkt zum Abschnitt "Wie kann ich einen Beitrag veröffentlichen?" springen.
</SideNote>
</Callout>

## Wie kann ich einen Beitrag gestalten

Expand Down Expand Up @@ -80,43 +80,43 @@ Um einen Text einzupflegen, benötigen Sie lediglich einen [GitHub-Account](http

Der erste wichtige Schritt ist, dass Sie sich als Autor\*in anlegen. Gehen Sie dafür links unter "Contents" auf "People“. Durch Klicken auf den Button "New Person" können Sie sich nun selbst als Autor\*in anlegen. Speichern Sie die Eingaben und veröffentlichen Sie dann den Eintrag.

<Figure src="images/screenshot-add-new-person.png">
<Figure src="/assets/content/documentation/screenshot-add-new-person.png">
Screenshot: Neuen Autor oder Autorin anlegen
</Figure>

### Schritt 2: Einen neuen Beitrag anlegen

Nun können Sie entweder unter "Collections" und "Posts" mit dem Button "New Post" einen neuen Beitrag starten oder dies über den zweiten Tab "Workflow" tun. Im Bereich "Workflow" finden Sie jederzeit alle Beiträge, die derzeit in Bearbeitung sind oder auf ihre Prüfung und Veröffentlichung warten. Wenn Sie also ihre Arbeit unterbrechen, gehen Sie beim nächsten Mal einfach zum Tab Workflow, wo Sie in der linken Spalte unter "Drafts" die Beiträge im Entwurfsstatus finden, öffnen, und daran weiterarbeiten können. Sobald eine Änderung in einem Beitrag vorgenommen wurde, erinnert Sie die Plattform vor dem Verlassen automatisch daran, die Änderungen zu speichern oder ggf. zu verwerfen (nicht speichern).

<Figure src="images/screenshot-workflow-new-post.png">
<Figure src="/assets/content/documentation/screenshot-workflow-new-post.png">
Screenshot: Einen neuen Beitrag anlegen
</Figure>

<SideNote type="info" title="Hinweis:">
<Callout kind="note" title="Hinweis">
Beiträge werden immer zuerst als Draft-Version gespeichert. Wenn Sie fertig sind, können Sie den Entwurf auf "In Review" umstellen, damit ihn das Redaktionsteam überprüfen kann. Wenn dies erfolgt ist, wird der Beitrag auf "Ready" gestellt und danach publiziert. Erst dann ist er auf der öffentlichen Instanz der Lernplattform einsehbar.
</SideNote>
</Callout>

Wenn Sie einen neuen Beitrag starten (oder einen vorhandenen Beitrag durch Anklicken wieder öffnen), so teilt sich der Bildschirm in zwei Hälften. Links ist der Bearbeitungsbereich, rechts können Sie im Vorschau-Modus direkt überprüfen, wie Ihr Beitrag auf der HowTo Plattform aussehen wird. Der Vorschau-Modus kann mit dem Auge-Symbol rechts oben aus- und wieder eingeschaltet werden.

Jeder Beitrag startet mit einigen formalen Angaben. Dazu gehören der Titel, der möglichst aussagekräftig und nicht zu lange sein sollte, die Sprache, das Datum, die Autor\*innen, Editor\*innen, Tags und ein kurzer Abstract. Bei einigen Feldern können nur Angaben aus dem Dropdown-Menü ausgewählt werden. Sollte der gewünschte Eintrag nicht vorhanden sein, so muss dieser vorab angelegt werden. Autor*innen können Sie selbst hinzufügen (siehe Anleitung unter Schritt 1), für Tags wenden Sie sich bitte an das Redaktionsteam unter acdh-ch-training@oeaw.ac.at.

<SideNote type="tip" title="Tipp:">
<Callout kind="tip" title="Tipp:">
Die erste (gespeicherte) Eingabe im Feld "Titel" wird für die URL des Beitrags verwendet. Wollen Sie eine möglichst einfache und gut lesbare URL haben, so raten wir Ihnen, beim ersten Speichern im Titelfeld nur die gewünschten Wörter ohne Umlaute oder Sonderzeichen zu benutzen.

In unserem Beispiel (siehe Abbildung) haben wir im Titelfeld die Wörter "Test Example Entry" eingegeben und gespeichert. Danach kann der Titel beliebig abgeändert werden, die URL bleibt aber bei "test-example-entry".

<Figure src="images/screenshot-url-erstellen_3.png">
<Figure src="/assets/content/documentation/screenshot-url-erstellen_3.png">
Screenshot: Zusammenhang Titel nach der ersten Speicherung und URL des Beitrags
</Figure>
</SideNote>
</Callout>

Auf die formalen Angaben wie Titel, Sprache und Abstract folgt dann das Feld für den Inhalt des Beitrags ("Content"). Dieser kann entweder im Rich-Text Format oder im Markdown eingegeben werden und Sie können durch den Schieberegler (im Screenshot unten gelb markiert) jederzeit zwischen den Formaten wechseln. Um einen Beitrag abspeichern zu können, muss in jedem Pflichtfeld, und dazu zählt auch "Content", eine Angabe vorhanden sein.

### Schritt 3: Die wichtigsten Editierfunktionen für den Inhalt

Im Rich-Text stehen Ihnen verschiedene Formatierungsoptionen, wie Fett, Kursiv, Überschriften, Aufzählungen, etc. zur Verfügung (siehe grüne Markierung im Screenshot). Außerdem können Sie mithilfe des "Plus"-Symbols (blaue Markierung) verschiedene vorprogrammierte Funktionen nutzen, wie das Einfügen von Bildern, Videos, Codeblocks, Tipp-Boxen, oder ein Quiz.

<Figure src="images/screenshot-editierfunktionen-cms_2.png">
<Figure src="/assets/content/documentation/screenshot-editierfunktionen-cms_2.png">
Screenshot: Editierfunktionen im CMS
</Figure>

Expand All @@ -136,7 +136,7 @@ Wenn Sie mit der Maus kurz über das Formatierungssymbol fahren, wird eine kurze
- Code Block: Einen längeren Codeblock einfügen
- Download: Material zum Download einfügen
- Figure: Bilder einfügen. Im Vergleich zur Funktion "Image" ist es bei "Figure" zusätzlich möglich, bei der Bildunterschrift (Caption) Markdown-Inhalte einzugeben und damit Verlinkungen oder doppelte Anführungszeichen zu verwenden.
- SideNote: Hiermit kann ein Hinweis oder ein Tipp eingefügt werden. Es gibt unterschiedliche Optionen, die farblich unterschiedlich markiert und im Text hervorgehoben werden. Das Dropdown-Menü unter "Type" zeigt die zur Verfügung stehenden Optionen an.
- Callout: Hiermit kann ein Hinweis oder ein Tipp eingefügt werden. Es gibt unterschiedliche Optionen, die farblich unterschiedlich markiert und im Text hervorgehoben werden. Das Dropdown-Menü unter "Type" zeigt die zur Verfügung stehenden Optionen an.
- Video: Ein Video einbinden, dass auf Youtube, Vimeo oder Nakala gehostet ist. Optional können Sie eingeben, ab welcher Stelle das Video abgespielt werden soll und ob die Abspielfunktion automatisch starten soll.
- Quiz: Dies gibt Ihnen die Möglichkeit, eine oder mehrere Fragen zu gestalten. Die Anzahl der angezeigten Antwortoptionen legen Sie mit "Options" fest. Für jede Antwortmöglichkeit muss auch festgelegt werden, ob die Antwort richtig oder falsch ist. Unter "Messages" können Sie zusätzlich Rückmeldungen an den Lernenden einfüllen, damit er*sie auch weiß, warum die Antwort richtig oder falsch ist. Mit Hilfe des Feldes "Control" können Sie den Button, der vom Lernenden zur Überprüfung gedrückt werden muss, benennen. Systemseitig ist hier "Überprüfen" bzw. "Validate" eingestellt. Wenn der Vorschau-Modus aktiviert ist (Auge-Symbol), sehen Sie auf der rechten Browser-Seite immer gleich, wie Ihre Multiple-Choice-Frage aussieht und können die Antwortmöglichkeiten auch testen. Richtige Antworten werden grün angezeigt, falsche Antworten in rot. Beachten Sie, dass Antworten immer eindeutig richtig oder falsch sein müssen.
- Tab: Mit dieser Funktion können Sie einen Abschnitt mit Registerkarten in Ihrem Artikel erstellen. Die Lernenden können dann zwischen den Tab bzw. Optionen wechseln, ohne die Hauptseite verlassen zu müssen. Die Funktion kann zum Beispiel nützlich sein, um die Installation eines Tools oder Programms zu erklären, welches unterschiedliche Eingaben auf verschiedenen Betriebssystemen (wie Windows, Mac) erfordert.
Expand Down
Loading