Für wen

Doku nach Markdown holen, ohne Nacharbeit

Dokumentation zu migrieren heißt meist: HTML umwandeln und danach länger damit verbringen, das wieder zu entfernen, was der Konverter behalten hat. Genau dieses Entfernen ist der Teil, für den Clean Clipper gebaut wurde – und der Teil, der gemessen wurde: null übrige HTML-Tags über 512 erfasste Seiten.

Die Nacharbeit nach dem Import

Ein Konverter, der alles behält, verschiebt die Arbeit nur nach hinten. Die umgewandelte Seite trägt Navigationsleiste, Versionsauswahl, Sprachumschalter und Feedback-Block im selben Fluss wie den Text, dazu leere Überschriften, die aus aufgeklappten Menüs stammen. Bei zweihundert Seiten ist dieses Aufräumen kein Nebenschritt mehr, sondern der eigentliche Aufwand des Projekts.

Dazu kommen die Reste, die man erst spät bemerkt. Ein div mitten in einem Code-Zaun, eine Tabelle, die in eine Zeile gefallen ist, ein Callout, aus dem ein loser Absatz ohne Kennzeichnung wurde. Der Fehler fällt auf, wenn die Seiten schon im neuen System stehen, und dann ist die Korrektur teurer als der ganze Import.

Am spätesten fällt auf, was die Verweise machen. Querverweise zwischen zwei Seiten der alten Dokumentation kommen als absolute Links auf die alte Website an, und sie funktionieren – genau deshalb merkt es niemand. Erst wenn die alte Website abgeschaltet wird, zeigt sich, dass die halbe neue Doku nach draußen zeigte. Das ist Arbeit, die beim Umzug ohnehin anfällt; sie ist nur billiger, wenn man sie einplant, statt sie zu entdecken.

Was der Import hergibt

• Überschriften, Listen, Tabellen, Code-Zäune und Fußnoten werden zu gewöhnlichem Markdown
• Sprach-Tags an den Code-Zäunen bleiben erhalten – 73 von 156 Zäunen auf dem technischen Korpus
• Null übrige HTML-Tags über 512 gemessene Seiten
• Navigationsleisten, Versionsauswahl und Feedback-Blöcke werden entfernt, nicht umgewandelt
• Leere Überschriften aus aufgeklappten Menüs fallen weg, statt die Gliederung zu verwässern
• Namensvorlage und Unterordner halten einen importierten Bestand von Anfang an geordnet
• Hinweisboxen und Callouts werden zu Zitatblöcken – der Inhalt bleibt, die Gestaltung nicht, weil Markdown dafür keine Standardsyntax hat
• Querverweise auf andere Seiten bleiben absolute Links auf die ursprüngliche Website und sind damit als Umschreibarbeit sichtbar

---
title: "systemd/Timer"
source: "https://wiki.ubuntuusers.de/systemd/Timer/"
extraction: "dom"
---

## Aufbau einer Timer-Unit

| Schlüssel | Bedeutung |
| --- | --- |
| `OnCalendar` | Zeitpunkt in Kalenderschreibweise |
| `Persistent` | holt einen verpassten Start nach |

> Hinweis: Zu jeder Timer-Unit gehört eine gleichnamige Service-Unit.

Einen Umzug ordentlich anfangen

Ein Import, der ohne Namensregel beginnt, wird zweimal gemacht. Diese sechs Schritte legen die Ordnung fest, bevor die erste Seite erfasst wird.

1. Legen Sie den Zielordner und die Unterordner nach der künftigen Gliederung an, nicht nach der alten. Der Import ist der einzige günstige Zeitpunkt, eine Struktur zu ändern; danach kostet jede Verschiebung Verweise.
2. Setzen Sie die Namensvorlage auf {title} und ergänzen Sie sie nur dort um {domain}, wo aus mehreren Quellen importiert wird. Der Dateiname wird in vielen Generatoren zum Pfad, und ein Datum darin ist später eine Umbenennungsaktion.
3. Stellen Sie Bilder auf „weglassen“, wenn die Abbildungen ohnehin neu erstellt werden – sonst auf „behalten“, damit die Links als Aufgabenliste in den Dateien stehen. Binärdateien lädt die Erweiterung in keinem Fall herunter.
4. Erfassen Sie die Seiten in der Reihenfolge der Gliederung und nicht in der Reihenfolge, in der Sie sie finden. Es gibt keinen Crawler und keinen Stapelbetrieb, und das ist die Stelle, an der Sie entscheiden, welche Seiten überhaupt mitkommen.
5. Prüfen Sie stichprobenweise im Lesemodus: Sind die Code-Zäune mit Sprache versehen, stehen die Tabellen ganz da, wurde aus jeder Hinweisbox ein Zitatblock? Auf dem technischen Korpus trugen 73 von 156 Zäunen eine Sprachmarke – die übrigen zeichnet die Quelle selbst nicht aus.
6. Planen Sie das Umschreiben der Querverweise als eigenen Arbeitsschritt ein. Links auf andere Seiten bleiben absolute Links auf die alte Website; sie funktionieren, bis diese abgeschaltet wird, und sind deshalb leicht zu übersehen.

Einstellungen für den Import

Die Werte sind auf einen Bestand ausgelegt, der in ein Repository wandert und dort weiterlebt – nicht auf einzelne Notizen. Deshalb kein Datum im Dateinamen.

---
title: "Systemd (Deutsch) – Units verwalten"
source: "https://wiki.archlinux.org/title/Systemd_(Deutsch)"
extraction: "dom"
---

## Units aktivieren

```bash
systemctl enable --now sshd.service
```

> **Hinweis:** `enable` legt nur die Verknüpfung an. Erst `--now` startet
> die Unit auch in der laufenden Sitzung.

Siehe auch [Systemd/Timers](https://wiki.archlinux.org/title/Systemd/Timers).

Drei Wege durch einen Umzug

Zweihundert Seiten in ein neues System holen

Die alte Doku soll in einen statischen Generator umziehen. Sie legen den Zielordner im Repository der neuen Doku an, richten die Unterordner nach der künftigen Gliederung und erfassen Seite für Seite in dieser Reihenfolge.

Weil kein Crawler mitläuft, wird der Import zur Auswahl: Von zweihundert Seiten kommen selten zweihundert mit. Was ankommt, ist gewöhnliches Markdown mit Überschriften, Listen, Tabellen, Code-Zäunen und Fußnoten – und ohne rohe Auszeichnung: null übrige HTML-Tags über 512 gemessene Seiten.

Eine fremde Anleitung in die eigene Doku übernehmen

Ein Verfahren ist auf einer fremden Wiki-Seite besser beschrieben als in Ihrer eigenen Doku, und es soll übernommen und angepasst werden. Sie erfassen die Seite in den Unterordner import, getrennt vom redigierten Bestand.

Die Code-Zäune tragen ihre Sprache, sofern die Quelle sie ausgezeichnet hat, und aus der Hinweisbox wird ein Zitatblock, den Sie im eigenen System zum passenden Callout machen. Was Sie übernehmen dürfen, richtet sich nach der Lizenz der Quelle – geprüft wird das nicht.

Eine Referenzseite als Vorlage nachbauen

Sie brauchen die Struktur einer gut gemachten API-Referenz als Muster: welche Abschnitte in welcher Reihenfolge, welche Tabellen, wo die Beispiele stehen. Der Clip zeigt die Gliederung ohne Navigationsleiste, Versionsauswahl und Feedback-Block.

Leere Überschriften, die aus aufgeklappten Menüs stammen, fallen dabei weg, statt die Gliederung zu verwässern. Was übrig bleibt, ist die Struktur des Artikeltextes – und die lässt sich in Ihrem Editor als Gerüst weiterverwenden.

Gegen die üblichen Wege

Doku umzuziehen geht auf mehreren Wegen, und jeder verschiebt die Arbeit an eine andere Stelle. Die letzte Zeile nennt auch, was hier zu tun bleibt.

Wenn der Import hakt

Warum zeigen meine Querverweise noch auf die alte Website?

Weil Links auf andere Seiten als absolute Links übernommen werden. Sie funktionieren, solange die alte Website läuft, und genau deshalb fällt es nicht auf. Planen Sie das Umschreiben als eigenen Schritt ein – bei Textdateien ist eine Suche-und-Ersetze-Aktion über den Ordner der schnellste Weg.

Aus meinen Warnhinweisen sind Zitatblöcke geworden

Weil Markdown keine Standardsyntax für Hinweisboxen kennt. Der Inhalt bleibt vollständig, die Auszeichnung als „Warnung“ oder „Hinweis“ nicht. In den meisten Zielsystemen wird daraus mit einer Zeile wieder ein Callout; welche Zeile das ist, hängt vom System ab, und deshalb entscheidet die Erweiterung es nicht.

Ein Abschnitt der Seite fehlt im Clip

Prüfen Sie, ob er hinter einer Registerkarte oder einem Aufklapper stand. Erfasst wird das DOM in dem Zustand, in dem es beim Klick steht, und geschlossene Bereiche sind dort auf vielen Doku-Systemen gar nicht vorhanden. Öffnen Sie den Abschnitt vorher; bei Registerkarten für mehrere Sprachen erfassen Sie gegebenenfalls zweimal.

Die Dateien liegen richtig, aber die Navigation fehlt

Weil die Erweiterung keine erzeugt. Es entstehen Dateien, keine mkdocs.yml und keine sidebars.js; die Gliederung des Zielsystems legen Sie an. Das ist der Grund, warum sich lohnt, die Unterordner schon beim Import nach der künftigen Struktur zu benennen.

Was es nicht tut

Es gibt keinen Crawler und keinen Stapelbetrieb: Sie erfassen eine Seite nach der anderen, und zwar die, auf der Sie stehen. Es erzeugt keine Navigationsstruktur und keine mkdocs- oder docusaurus-Konfiguration, sondern Dateien, die Sie danach einordnen. Callouts und Hinweisboxen werden zu Zitatblöcken, weil Markdown keine Standardsyntax dafür kennt. Und Abbildungen bleiben Links auf die ursprüngliche Website; Binärdateien werden nicht heruntergeladen.

Fragen