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!