Veränderungen sind unvermeidbar, und ab und zu kommt es dazu. In den letzten Jahren gab es Veränderungen, die uns aufgezwungen wurden, Veränderungen, über die wir keine direkte Kontrolle hatten. Aber bei Layer0/Edgio ist die jüngste Änderung eine von uns selbst, eine, die dringend benötigt wurde: Eine vollständige Neufassung und Neugestaltung der Edgio-Dokumentation.
Diese Überholung sollte grundlegend und kontrollierbar sein. Die Wahrheit ist, wir wollten die Dinge selbst in die Hand nehmen, wie wir es noch nie zuvor getan haben. Und so haben wir, stark inspiriert von den React Beta Docs, auf die Schultern von Riesen gelegt, indem wir eine Instanz des Basis-Repo erstellen und es für unseren spezifischen Anwendungsfall feinabstimmen.
Das Wichtigste zuerst
Der erste Schritt war der Reactiflux Discord-Kanal. Um es einfach auszudrücken, half die Community bei der Identifizierung der Beta-Dokumentation von React.
Das React Beta-Repo als Vorsprung
Wir haben einige Tage damit verbracht, zu untersuchen, wie die Beta-Website von React Docs erstellt wurde, welche Technologien sie verwendet und wie wir diesen Stack nutzen und aufbauend darauf aufbauen können, um unseren spezifischen Anforderungen gerecht zu werden. Unsere Vorliebe für MDX und Next.js war richtig und wir hatten einen Vorsprung.
Technologien
Hier sind einige der wichtigsten Technologien, die verwendet werden:
- MDX: Funktionaler Markdown mit eingebetteten REACT-Komponenten
- Next.js: React Framework
- Webpack: Modul-Bundler
- Gestaltete Komponenten: Gestaltung
- Algolei: Suche
- PRISM: Hervorhebung der Code-Syntax
MDX: MDX ist eine erweiterte Form des Markdowns für das Komponentenzeitalter. Damit wird das Markdown-Dokument funktionsfähig, indem Sie JSX in jedes Markdown-Dokument einbetten können, wodurch die Inhaltserstellung mit Markdown auf eine neue Ebene gebracht wird.
Wir wussten bereits, was MDX war und wie leistungsstark es sein kann, aus Artikeln wie MDX, The Secret Ingredient and Front-End Documentation, Style Guides und The Rise of MDX. Dies ebnete den Weg für einige der benutzerdefinierten Komponenten, die wir erstellt haben.
Next.js: Die Kopplung von MDX mit Next.js ist nichts Neues. Daher war es zunächst einmal wichtig, die offizielle Dokumentation oder diesen Blogbeitrag zu lesen. Es gibt mehrere Ansätze, um Markdown in Next.js-Seiten zu erhalten, wie z. B. ein lokales Markdown-Dokument und dessen Umwandlung in HTML mit Packages wie Remark und Remark-html in einem von getStaticProps, getStaticPaths oder getServerSideProps
Ein anderer Ansatz besteht darin, eine `.md`- oder `.mdx`-Datei direkt als Next.js-Seiten mit dem @next/mdx-Paket zu definieren, oder wenn Sie sich mit den untergeordneten Dingen beschäftigen möchten, folgen Sie dem Teamansatz und dem DIY-Konzept des React.
Webpack: Next.config.js (oder next.config.mjs) wird vom Next.js-Server und den Build-Phasen verwendet. Hier können Sie Next.js für erweiterte Anwendungsfälle konfigurieren, wie z.B. das Lesen von `.mdx`-Dateierweiterungen im Pages-Verzeichnis und das Laden als Next.js-Seiten.
Webpack verwendet Loader, um Dateien vorzuverarbeiten. Einer der häufigsten Anwendungsfälle ist die Transponierung und ein solches gängiges Paket ist babel-Loader (lädt ES2015+-Code und transpilt mit Babel nach ES5). Um `.mdx`-Dateien mit Webpack in Next.js zu laden, wird @mdx-js/Loader verwendet.
Das umfangreiche Ökosystem von Remark/rehype-Plugins kann von @mdx-js/Loader für eine feinkörnige Transformation von Markdown in HTML aufgerufen werden.
Gestylte Komponenten: Obwohl es eine Vielzahl von Möglichkeiten gibt, CSS in Next.js zu schreiben, haben wir uns für gestylte Komponenten entschieden. Mit Styled Components sind wir in der Lage, Komponentenstile auf eine kolokativere, modulare, gekoppelte und weniger aufdringliche Weise zu erstellen. Erfahren Sie, wie Sie gestylte Komponenten in React verwenden, oder erkunden Sie den Happy Path für gestylte Komponenten, um weitere Informationen zu gestylten Komponenten zu erhalten.
Algolia: Wir haben ein Upgrade auf die neueste Version von DocSearch v3 durchgeführt, die auf der Algolia Autocomplete aufbaut und Verbesserungen bei der Zugänglichkeit und Reaktionsfähigkeit bietet, um ein reibungsloseres Erlebnis auf Desktop- und Mobilgeräten zu ermöglichen. Dazu gehört der Algolia Crawler, der die wichtigsten Informationen bei der Suche extrahiert.
PRISM: PRISM ist ein gut getesteter und vertrauenswürdiger Textmarker für die Code-Syntax. Es ist nicht nur einfacher zu beginnen, es verfügt auch über ein umfangreiches Plugins-Ökosystem und ist erweiterbar mit vernünftigen Standardeinstellungen für Vorgänge wie Theming.
Funktionen
Während die Neukonstruktion eine weitgehend kosmetische Änderung am Nennwert aufweist, gibt es andere Features wie:
Eine neue Homepage mit wichtigen Details
Beginnen Sie mit den vier Säulen der Layer0/Edgio-Plattform, und bauen Sie sich auf und nutzen Sie weitere Funktionen, die Layer0/Edgio zu bieten hat.
Design
Das Umschalten zwischen Themen ist nur einen Mausklick entfernt. Wechseln Sie vom hellen Modus in den dunklen Modus oder umgekehrt, oder lassen Sie Ihr Betriebssystem entscheiden.
Verbesserte Navigation
Die beiden wichtigsten Navigationsmodi – Menü (links) und Inhaltsverzeichnis (rechts) – wurden überarbeitet, um Navigation und Scannen zu verbessern. Ein neues Steuerelement für die Seitennummerierung (unten) hilft Ihnen, zu wissen, welcher Leitfaden als Nächstes gilt und welcher vorher kommt.
Verbesserte Codeblöcke
Mit PrismJS ist die Syntax-Hervorhebung und Anpassung einfach.
Verbesserte Suche
Die Algolia-Suche wurde auf v3 aktualisiert, wodurch wir viel mehr Kontrolle darüber haben, welche Inhalte für Ergebnisse indiziert werden. Dies funktioniert auch auf mobilen Geräten.
Aber warte, es gibt noch mehr
Das React Beta Docs Repo hat viel zu tun, und wir konnten hier die Vorteile von Open Source nutzen. Es gibt einige Dinge, die wir fast aus der Box bekommen, wie Inhaltsverzeichnis, Doku-Paginierung, Brotkrumen, SEO usw. Einige davon haben wir optimiert, um unseren Kontext besser zu erfüllen, und einige sind noch im Begriff.
Beitrag Leisten
Für uns ist dies die neue Dokumentation ein Schritt in die richtige Richtung und der Beginn eines Neuanfangs. Wir möchten, dass Sie uns auf diesem Weg begleiten, da wir Ihnen weiterhin helfen, Ihre Websites schneller und sicherer zu gestalten, ohne Kompromisse bei der Entwicklererfahrung einzugehen. Der Quellcode für die Layer0-Entwickler-Dokumente befindet sich in einem offenen Repository auf GitHub, und wir freuen uns über Feedback- und Pull-Anfragen. Wenn Sie einen Tippfehler oder eine bessere Möglichkeit gefunden haben, etwas zu erklären, reichen Sie bitte eine Anfrage ein oder reichen Sie ein Problem ein! Weitere Informationen finden Sie in unseren Beitragsrichtlinien.
