Von ReadMe
Synchronisieren Sie Ihr ReadMe-Projekt mit GitHub oder exportieren Sie es, und importieren Sie das Repository. Kategorieordner werden zu Ihrer Navigation, die Seitenreihenfolge stammt aus _order.yaml, und Ihr MDX behält seine Syntax.
Aktualisiert am 19. Nov. 20263 Min. Lesezeit
ReadMe kann ein Projekt mit seiner bidirektionalen Synchronisierung als Markdown-Dateien in Ordnern in ein GitHub-Repository schreiben. Typemark importiert dieses Repository: Jeder Kategorieordner wird zu einer Navigationsgruppe, _order.yaml legt die Seitenreihenfolge fest, und Ihre API-Referenzseiten zeigen ihre Endpunkte aus Ihren OpenAPI-Dateien an.
Die Seiten von ReadMe sind MDX, daher liest Typemark sie unverändert: excerpt funktioniert als Seitenbeschreibung, und <Callout>, <Image>, <Cards> und <Embed> werden ohne Änderungen gerendert. Der Import verschiebt Dateien so, dass Ihre URLs gleich bleiben, und wandelt das um, was nur in ReadMe gerendert wird, etwa Emoji-Callouts und doc:-Links, in einen Commit, den Sie prüfen können.
Bevor Sie beginnen
- Ihr ReadMe-Tarif umfasst die GitHub-Synchronisierung, oder Sie können das Projekt exportieren. Prüfen Sie Ihren Tarif in ReadMe.
- Die ReadMe-Synchronisierung benötigt ein neues, leeres Repository: keine Commits und kein README.
- Das Repository ist 100 MB groß oder kleiner.
Projekt importieren
Projekt mit GitHub synchronisieren
Verbinden Sie das Projekt in ReadMe mit einem neuen, leeren GitHub-Repository. ReadMe schreibt
docs/,reference/und die anderen Ordner hinein. Jede ReadMe-Version ist ein Branch; Typemark importiert den Branch, den Sie beim Verbinden auswählen, standardmäßig den Standard-Branch, sofern Sie keinen anderen wählen.Typemark-Projekt erstellen
Klicken Sie auf Neues Projekt, geben Sie einen Namen ein und wählen Sie unter Starten mit die Option Von GitHub importieren. Klicken Sie auf Erstellen und mit GitHub verbinden und gewähren Sie der Typemark-GitHub-App Zugriff auf das Repository.
Repository auswählen
Typemark zeigt ReadMe-Projekt erkannt an. Klicken Sie auf Importieren und bestätigen Sie.
Import prüfen
Typemark schreibt
typemark.json, wandelt die alte Syntax in einem Commit um, pusht ihn und erstellt Ihre Seite. Die Projektübersicht zeigt die Import-Zusammenfassung.Bilder übernehmen
Bilder, die Sie in ReadMe hochgeladen haben, werden auf
files.readme.iogehostet. Sie funktionieren vorerst weiter, liegen aber bei ReadMe. Die Zusammenfassung listet jede Seite auf, die sie verwendet: Laden Sie sie inimages/herunter und aktualisieren Sie die Links, bevor Sie ReadMe kündigen. Ihr Coding-Agent kann das für Sie übernehmen.GitHub-Synchronisierung beenden und live gehen
Trennen Sie die GitHub-Synchronisierung in ReadMe, arbeiten Sie die Go-Live-Checkliste ab und klicken Sie dann unter Einstellungen > Veröffentlichung auf Live gehen.
Was umgewandelt wird
| ReadMe | Typemark |
|---|---|
Kategorieordner in docs/ | Navigationsgruppen mit dem Namen des Ordners, im Tab Guides |
| Seitendateien | Verschoben, um den URLs von ReadMe zu entsprechen, sodass /docs/my-page /docs/my-page bleibt. Weiterleitungen decken die älteren flachen URLs verschachtelter Seiten ab |
_order.yaml | Seitenreihenfolge innerhalb der Gruppe. Die Dateien selbst werden entfernt |
Ordner mit index.md und Unterseiten | Die Indexseite, danach ihre Unterseiten, in derselben Gruppe |
API-Referenzseiten (api: mit einer operationId) | Endpunkt-Seiten unter derselben URL und an derselben Stelle, im Tab API Reference. Jede zeigt den Endpunkt aus Ihrer Spezifikation zusammen mit dem eigenen Text der Seite. Typemark ergänzt das Frontmatter um openapi: "<spec> METHOD /path" |
OpenAPI-Dateien in reference/ ohne Referenzseiten | Generierte API-Seiten im Tab API Reference |
title | title |
excerpt | Die Seitenbeschreibung, unverändert übernommen |
hidden: true | Aus der Seitenleiste ausgeblendet, per URL weiterhin erreichbar |
<Callout icon="📘" theme="info"> | Wird als Callout gerendert und im visuellen Editor geöffnet. Unverändert gespeichert |
<Image>, <Cards>, <Columns>, <Embed>, <Table>, <Anchor> | Werden unverändert gerendert. Ein <Embed> eines YouTube-, Vimeo-, Loom- oder Wistia-Videos spielt es ab |
Emoji-Callouts > 📘 Title | <Callout> mit dem passenden Theme |
doc:-, ref:- und recipe:-Links | Links zur Typemark-Seite |
| Glossarbegriffe | Einfacher Text |
| HTML-Kommentare | Entfernt, da sie in MDX nicht gebaut werden |
| Rezepte und benutzerdefinierte Seiten | Normale Seiten, in den Gruppen Recipes und Pages |
Nicht übernommen
- Bilder auf
files.readme.iobleiben extern, bis Sie sie verschieben. Siehe Schritt 5. - Mehr als eine Version. Ein Projekt importiert einen Branch, den Sie beim Verbinden auswählen.
- Einstellungen für „Try it“ in der API und gespeicherte Schlüssel. Die API-Seiten von Typemark zeigen die Referenz aus Ihrer Spezifikation.
- Variablen wie
<<company>>bleiben als Text erhalten und werden in der Zusammenfassung aufgelistet. - Changelog-Beiträge in
changelogs/werden nicht importiert. Erstellen Sie die benötigten mit Changelog-Einträgen neu. <HTMLBlock>und<TutorialTile>werden nicht unterstützt und in der Zusammenfassung aufgelistet.- Benutzerdefiniertes CSS und andere Einstellungen, die in ReadMe statt im Repository liegen.
Aus dem Terminal
Um einen Export oder ein synchronisiertes Repository auf Ihrem Computer umzuwandeln:
cd my-readme-project
typemark migrate # detects the ReadMe project and converts it, then offers to create the project and push it
Beantworten Sie zweimal mit „ja“, und Ihre Seite ist auf Typemark, offline, bis Sie sie veröffentlichen. In CI oder mit einem Coding-Agenten verwenden Sie stattdessen typemark migrate --create "My Docs" --push.
typemark migrate schreibt dieselben Änderungen wie der GitHub-Import. Committen oder stashen Sie zuerst Ihre Arbeit, damit Sie das Ergebnis mit git diff prüfen können.
Mit Ihrem Coding-Agenten
Ihr Coding-Agent kann die files.readme.io-Bilder herunterladen, Rezepte in Guides zusammenführen und alles beheben, was die Zusammenfassung auflistet:
typemark migrate --from readme --agent claude
Siehe Mit Ihrem Coding-Agenten.