Front-End-Dokumentation, Stilführer und der Aufstieg von MDX

Selbst das beste Open-Source-Projekt kann ohne umfassende Dokumentation scheitern. Die interne Dokumentation ist gleichermaßen wichtig, verhindern sich wiederholende Q & A -Antworten und die Gewährleistung der Kontinuität der Wissen, selbst wenn die Veränderungen der Mitarbeiter sind. Gut dokumentierte Codierungsrichtlinien fördern die Codebasiskonsistenz.

Für umfangreiche Dokumentation bietet Markdown eine überlegene Alternative zu RAW -HTML. Die Einschränkungen von Markdown können jedoch durch Einbetten von HTML direkt in Markdown -Dateien überwunden werden, einschließlich benutzerdefinierter Elemente für Designsysteme mithilfe von Webkomponenten. Für React (und JSX-kompatible Frameworks wie Preact oder Vue) bietet MDX eine nahtlose Integration.

Dieser Artikel bietet einen hochrangigen Überblick über Dokumentations- und Stilhandbucherstellungstools. Obwohl nicht alle MDX verwenden, nimmt seine Einführung rasch zu.

MDX verstehen

Eine .mdx -Datei spiegelt Standard -Markdown -Syntax wider, ermöglicht jedoch den Import und Einbetten interaktiver JSX -Komponenten. Die Vue -Komponenten -Unterstützung erfolgt derzeit in Alpha. MDX integriert sich problemlos in die React -App erstellen, und Plugins existieren für Next.js und Gatsby. Docusaurus Version 2 bietet auch integrierte Unterstützung.

Docusaurus: Ein Dokumentationskraftwerk

DOCUSAURUS wurde von Facebook (ohne React) entwickelt und wird von zahlreichen wichtigen Open-Source-Projekten (Redux, Schöner, Gulp, Babel) verwendet. Die Vielseitigkeit geht über die Front-End-Dokumentation hinaus. Während der internationalen Verwendung von React in internem Dokument benötigt Docusaurus kein Reag -Wissen für die Verwendung. Es verwandelt Markdown-Dateien in gut strukturierte, visuell ansprechende Dokumentationsseiten.

Docusaurus-Websites können Markdown-basierte Blogs integrieren und Prism.js für die nahtlose Syntax-Hervorhebung enthalten. Seine Popularität ist offensichtlich, dass sie zum Top -neuen Tool von 2018 für Stackshare gewählt wurde.

Alternative Dokumentationslösungen

Während sich Docusaurus auf Dokumentation spezialisiert hat, gibt es zahlreiche Alternativen. Benutzerdefinierte Lösungen sind mit verschiedenen Back-End-Sprachen, CMSS oder statischen Site-Generatoren möglich. React, IBMs Designsystem, Apollo und Ghost CMS nutzen beispielsweise Gatsby, einen vielseitigen statischen Site -Generator, der häufig für Blogs verwendet wird. VuePress gewinnt an der Antrieb innerhalb des Vue -Ökosystems. Mkdocs, ein in Python geschriebenes Open-Source-Generator für statische Site, bietet eine einfache YAML-Konfiguration. Gitbook, eine beliebte bezahlte Option, bietet kostenlosen Zugang zu Open-Source- und gemeinnützigen Teams. Für einfachere interne Dokumentation sind die Markdown -Rendering -Funktionen von Github eine praktikable Option.

Komponentendokumentation: Docz, Storybook und StyleGuidist

Stilführer und Designsysteme haben eine immense Popularität erlangt. Komponentengesteuerte Frameworks (wie React) und zugehörige Tools haben sie von Eitelkeitsprojekten in wichtige Ressourcen umgewandelt.

Storybook, Docz und StyleGuidist dienen einem ähnlichen Zweck: Anzeigen interaktiver UI -Komponenten und Dokumentation ihrer APIs. Das Management zahlreicher Komponenten mit unterschiedlichen Zuständen und Stilen erfordert einen zentralisierten Katalog zur Entdeckbarkeit und Wiederverwendung. Style Guides bieten leicht durchsuchbare Übersichten, fördern visuelle Konsistenz und verhindern redundante Arbeiten.

Diese Tools vereinfachen die Überprüfung verschiedener Komponentenzustände und überwinden die Herausforderungen der Reproduktion aller Staaten innerhalb einer Live -Anwendung. Die isolierte Entwicklung der Komponenten ermöglicht es, schwer zu erreichen (z. B. Ladungszustände) zu verspotten.

Die Kommentare von Dan Green zu den Vorteilen von Storybook gelten gleichermaßen für Docz und StyleGuidist:

„Storybook hat die Zusammenarbeit zwischen Design und Engineering vereinfacht. Es wird die Notwendigkeit komplexer Setups (Docker-Container usw.) beseitigt. Für Wellen verwalten wir Komponenten, die nur in kurzlebigen, komplexen Prozessen sichtbar sind (z. B. Bildschirme). Vor dem Storybook, der Verwaltung dieser Komponenten war schwierig. Jetzt. Jetzt bietet Storybook eine isolierte Umgebung, die Designer und PMS, Streamlining-Demos.“

- Dan Green, Wave Financial

Über die Visualisierung von Zuständen und das Auflisten von Requisiten hinaus verbessert schriftliche Inhalte (Entwurfsrationale, Anwendungsfälle, Benutzer-Testergebnisse) die Komponentendokumentation. Die Zugänglichkeit von Markdown macht es ideal für die gemeinsame Dokumentation zwischen Designern und Entwicklern. DOCZ, StyleGuidist und Storybook integrieren nahtlos den Markdown mit Komponenten.

Docz

Derzeit nur React (mit geplanter Unterstützung für Preact, Vue und Webkomponenten) bietet docz (14.000 Github Stars) benutzerfreundliche Funktionen. Es bietet<playground></playground> Und<props></props> Komponenten, direkt in .mdx -Dateien verwendet.

 Import {Playground, Requisiten} aus "docz";
Schaltfläche importieren "../Src/Button";

## Sie können _write_ ** markdown **
### Sie können Komponenten importieren und verwenden

<playground>
  <button>klicken</button>
</playground>

Wickeln von Reagemokomponenten mit<playground></playground> Erstellt eingebettete interaktive Vorschau.<props></props> Zeigt Komponenten -Requisiten, Standardwerte und den erforderlichen Status an.

<props of="{Button}"></props>

Der MDX-basierte Ansatz von Docz ist intuitiv und effizient und bietet eine hervorragende Gatsby-Integration.

StyleGeist

StyleGuidist verwendet Markdown -Code -Blöcke (Triple Back Tunpfer) in Standard .md -Dateien anstelle von MDX.

 `` `JS
 console.log ('geklickt')

<code></code>

 <code>>Push Me</code>

Codeblöcke markiert js , jsx oder javascript rendern als interaktive React -Komponenten. Der Code ist bearbeitbar und bietet sofortiges visuelles Feedback. StyleGuidist generiert automatisch Proptabellen aus den Deklarationen von ProTTypen, Fluss oder Typenkript. Es unterstützt React und Vue.

Storybook

Storybook (36.000 Github Stars) ist eine UI -Komponentenentwicklungsumgebung. Anstelle von Markdown/MDX verwendet es JavaScript -Dateien für Geschichten (darstellen Komponentenzustände).

 Storiesof ('Button', Modul)
  .Add ('deaktiviert', () => (
    <button disabled>Lorem Ipsum</button>
  ))

Der Ansatz von Storybook ist weniger intuitiv als Docz und StyleGuidist. Die Beliebtheit und die umfangreiche Rahmenunterstützung (React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte, HTML) sind jedoch bemerkenswert. Die Dokumentation erfordert derzeit Addons, aber zukünftige Veröffentlichungen werden MDX enthalten, die von Docz inspiriert sind.

 # Taste

Einige _notes_ über Ihre Schaltfläche mit ** Markdown -Syntax **.


<button>Lorem Ipsum</button>

Die kommenden DOCS -Funktionen von Storybook versprechen erhebliche Verbesserungen.

Abschluss

Der Wert von Musterbibliotheken wird weithin anerkannt. Gut ausgeführte Bibliotheken fördern visuelle Konsistenz und Produktkohäsion. Während diese Tools Design und CSS -Expertise nicht ersetzen, bieten DOCZ, Storybook und StyleGuidist hervorragende Lösungen für die Kommunikation von Designsystemen in Organisationen.

Das obige ist der detaillierte Inhalt vonFront-End-Dokumentation, Stilführer und der Aufstieg von MDX. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!