{"id":34791,"date":"2019-10-31T22:00:25","date_gmt":"2019-10-31T19:00:25","guid":{"rendered":"https:\/\/prohoster.info\/blog\/zhivye-gajdlajny-mdx-i-drugie-frejmvorki\/"},"modified":"2019-10-31T22:00:25","modified_gmt":"2019-10-31T19:00:25","slug":"zhivye-gajdlajny-mdx-i-drugie-frejmvorki","status":"publish","type":"post","link":"https:\/\/prohoster.info\/de\/blog\/administrirovanie\/zhivye-gajdlajny-mdx-i-drugie-frejmvorki","title":{"rendered":"Lebendige Guidelines \u2014 MDX und andere Frameworks","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Sie k\u00f6nnen das beste Open-Source-Projekt haben, aber wenn es keine gute Dokumentation gibt, besteht die Wahrscheinlichkeit, dass es nie erfolgreich wird. Eine gute Dokumentation im B\u00fcro erm\u00f6glicht es Ihnen, nicht st\u00e4ndig dieselben Fragen zu beantworten. Dokumentation stellt auch sicher, dass die Leute sich im Projekt zurechtfinden, wenn Schl\u00fcsselmitarbeiter das Unternehmen verlassen oder die Rollen sich \u00e4ndern. Lebendige Richtlinien helfen, die Datenintegrit\u00e4t zu gew\u00e4hrleisten. <\/p>\n

<\/a><\/noindex><\/p>\n

Wenn Sie einen langen Text schreiben m\u00fcssen, ist Markdown eine ausgezeichnete Alternative zu HTML. Manchmal reicht die Markdown-Syntax jedoch nicht aus. In diesem Fall k\u00f6nnen wir HTML innerhalb von Markdown verwenden, zum Beispiel benutzerdefinierte Elemente. Wenn Sie also ein Designsystem mit nativen Webkomponenten erstellen, lassen sie sich leicht in die Textdokumentation integrieren. Wenn Sie React (oder ein anderes JSX-Framework wie Preact oder Vue) verwenden, k\u00f6nnen Sie dasselbe mit MDX tun. <\/p>\n

<\/p>\n

Dieser Artikel bietet einen umfassenden \u00dcberblick \u00fcber die Tools zum Schreiben von Dokumentationen und zum Erstellen von Richtlinien. Nicht alle hier aufgef\u00fchrten Werkzeuge nutzen MDX, aber es wird zunehmend in Dokumentationstools integriert.<\/p>\n

<\/p>\n

Was ist MDX?<\/h2>\n

<\/p>\n

Die Datei .mdx<\/code> hat die gleiche Syntax wie Markdown, erm\u00f6glicht jedoch das Importieren von interaktiven JSX-Komponenten und deren Einbettung in Ihren Inhalt. Die Unterst\u00fctzung von Vue-Komponenten befindet sich in der Alpha-Phase. Um mit MDX zu beginnen, m\u00fcssen Sie lediglich 'Create React App' installieren. Es gibt Plugins f\u00fcr Next.js und Gatsby. Die n\u00e4chste Version von Docusaurus (Version 2) wird ebenfalls eine integrierte Unterst\u00fctzung haben.<\/p>\n

<\/p>\n

Dokumentation mit Docusaurus schreiben<\/h2>\n

<\/p>\n

Docusaurus wurde bei Facebook entwickelt. Sie verwenden es in jedem Open-Source-Projekt au\u00dfer React. Au\u00dferhalb des Unternehmens verwenden es Redux, Prettier, Gulp und Babel.<\/p>\n

<\/p>\n

\"LebendigeProjekte, die Docusaurus verwenden.<\/em><\/p>\n

<\/p>\n

Docusaurus kann verwendet werden, um kann diese<\/em> Dokumentation zu schreiben, nicht nur zur Beschreibung des Frontends. Es basiert auf React, aber um es zu verwenden, m\u00fcssen Sie mit React nicht vertraut sein. Es nimmt Ihre Markdown-Dateien, eine Prise Magie, und gut strukturierte, formatierte und lesbare Dokumentation mit ansprechendem Design ist bereit. <\/p>\n

<\/p>\n

\"Lebendige
\nAuf der Website von Redux k\u00f6nnen Sie die Standardvorlage von Docusaurus einsehen.<\/em><\/p>\n

<\/p>\n

Websites, die mit Docusaurus erstellt wurden, k\u00f6nnen auch einen Blog auf Markdown-Basis beinhalten. Prism.js ist sofort integriert, um die Syntax hervorzuheben. Obwohl Docusaurus relativ neu ist, wurde es auf StackShare als das beste Werkzeug des Jahres 2018 anerkannt. <\/p>\n

<\/p>\n

Andere M\u00f6glichkeiten zur Erstellung von Inhalten<\/h2>\n

<\/p>\n

Docusaurus wurde speziell f\u00fcr die Erstellung von Dokumentationen entwickelt. Nat\u00fcrlich gibt es unz\u00e4hlige M\u00f6glichkeiten, eine Website zu erstellen \u2013 Sie k\u00f6nnen Ihre eigene L\u00f6sung in jeder Sprache, CMS oder mithilfe eines Static Site Generators implementieren.<\/p>\n

<\/p>\n

Beispielsweise verwenden die Dokumentation f\u00fcr React, die IBM Design System, Apollo und Ghost CMS Gatsby \u2013 ein Static Site Generator, der h\u00e4ufig f\u00fcr Blogs verwendet wird. Wenn Sie mit Vue arbeiten, wird VuePress eine gute Wahl f\u00fcr Sie sein. Eine andere M\u00f6glichkeit ist die Verwendung eines in Python geschriebenen Generators \u2013 MkDocs. Es ist Open Source und wird \u00fcber eine YAML-Datei konfiguriert. GitBook ist auch eine anst\u00e4ndige Option, aber es ist nur f\u00fcr Open-Source- und Nicht-Profit-Teams kostenlos. Eine weitere M\u00f6glichkeit besteht darin, Markdown-Dateien einfach \u00fcber Git hochzuladen und sie in GitHub zu bearbeiten. <\/p>\n

<\/p>\n

Dokumentation von Komponenten: Docz, Storybook und Styleguidist<\/h2>\n

<\/p>\n

Richtlinien, Designsysteme, Komponentebibliotheken \u2013 egal wie Sie sie nennen, aber sie sind in letzter Zeit sehr beliebt geworden. Das Aufkommen komponentenbasierter Frameworks wie React und der hier erw\u00e4hnten Werkzeuge hat es erm\u00f6glicht, sie von eitlen Projekten in n\u00fctzliche Werkzeuge zu verwandeln. <\/p>\n

<\/p>\n

Storybook, Docz und Styleguidist tun dasselbe: Sie zeigen interaktive Elemente an und dokumentieren deren API. Ein Projekt kann Dutzende oder sogar Hunderte von Komponenten haben \u2013 alle mit verschiedenen Zust\u00e4nden und Stilen. Wenn Komponenten wiederverwendet werden sollen, m\u00fcssen die Leute wissen, dass sie existieren. Es gen\u00fcgt, die Komponenten zu katalogisieren. Richtlinien bieten eine \u00fcbersichtliche \u00dcbersicht \u00fcber alle Ihre Komponenten. Das hilft, visuelle Konsistenz zu bewahren und Wiederholungsarbeit zu vermeiden.<\/p>\n

<\/p>\n

Diese Werkzeuge bieten eine bequeme M\u00f6glichkeit, verschiedene Zust\u00e4nde einzusehen. Es kann schwierig sein, jeden Zustand einer Komponente im Kontext einer realen Anwendung zu reproduzieren. Anstatt in einer echten Anwendung zu klicken, sollte man eine separate Komponente entwickeln. Es ist m\u00f6glich, schwer erreichbare Zust\u00e4nde zu simulieren (z. B. den Ladezustand). <\/p>\n

<\/p>\n

Neben der visuellen Demonstration verschiedener Zust\u00e4nde und einer Liste von Eigenschaften ist es oft notwendig, eine allgemeine Beschreibung des Inhalts zu schreiben \u2013 Designbegr\u00fcndungen, Anwendungsf\u00e4lle oder Beschreibungen der Ergebnisse von Benutzertests. Markdown ist sehr einfach zu erlernen \u2013 idealerweise sollten die Richtlinien eine gemeinsame Ressource f\u00fcr Designer und Entwickler sein. Docz, Styleguidist und Storybook bieten eine M\u00f6glichkeit, Markdown leicht mit Komponenten zu mischen.<\/p>\n

<\/p>\n

Docz<\/h2>\n

<\/p>\n

Zurzeit funktioniert Docz nur mit React, aber es wird aktiv an der Unterst\u00fctzung von Preact, Vue und Webkomponenten gearbeitet. Docz ist das neuesten der drei Werkzeuge, hat aber auf Github \u00fcber 14.000 Sterne gesammelt. Docz bietet zwei Komponenten an \u2013 <Playground><\/code> und < Props ><\/code>. Diese werden in Dateien importiert und verwendet .mdx<\/code>. <\/p>\n

<\/p>\n

import { Playground, Props } from \"docz\";\nimport Button from \"..\\\/src\\\/Button\";\n\n## Sie k\u00f6nnen _schreiben_ **Markdown**\n### Sie k\u00f6nnen Komponenten importieren und verwenden\n\n