Schnelle und einfache Dokumentation mit Markdown

Sie haben also ein tolles Thema, eine Vorlage oder eine Webanwendung erstellt. Nun zum mühsamen Teil; die Dokumentation. Das Schreiben des Inhalts ist nicht unbedingt problematisch, es ist wahrscheinlicher, dass die Erstellung der Hilfedateien wertvolle Zeit in Anspruch nimmt. Markdown, eine leichte und *wirklich* einfache Formatierungssyntax, kann all das für Sie lösen.

Über Markdown

Markdown wurde von John Gruber entwickelt und ist eine reine Textformatierungssyntax, die das Erstellen grundlegender HTML-Elemente erheblich erleichtert.

Anstatt HTML-Tags zu verwenden (deren Schreiben relativ viel Zeit in Anspruch nimmt), besteht die Aufgabe von Markdown darin, Ihrem Denkprozess aus dem Weg zu gehen, damit Sie sich auf den Inhalt konzentrieren können. Da die Syntax so einfach ist, ist es einfach, Markdown sowohl zu schreiben als auch zu lesen. Später in diesem Tutorial werden wir die Schritte zum Erstellen einer Designdokumentation mit Markdown durchgehen, damit Sie sehen, wie leicht und schnell es ist!

Markdown umwandeln

Sobald Sie sich mit dem Schreiben von Markdown vertraut gemacht haben, benötigen Sie eine Art Parsing-Anwendung, um Ihren Markdown in HTML-Markup umzuwandeln.

Der ursprüngliche Markdown-Konverter wurde in Perl erstellt, aber seitdem sind viele Anwendungen (auf mehreren Plattformen) aufgetaucht. Sehen wir uns einige der Optionen an, sowohl online als auch auf Ihrem eigenen System.

Dingus (Online)

Dingus ist eine Webanwendung, die von denselben Leuten erstellt wurde, die Ihnen Markdown gebracht haben. Kopieren Sie einfach Ihren Markdown-Code aus einem Texteditor und fügen Sie ihn ein (oder geben Sie ihn in den Textbereich ein) und mit einem Klick auf eine Schaltfläche wird Ihr HTML-Code (sowie eine Vorschau) angezeigt. Nichts Besonderes, aber eine einfache Möglichkeit, Markdown in HTML zu konvertieren.

MarkdownPad (Windows)

MarkdownPad ist eine großartige Windows-Anwendung, mit der Sie auf einfache Weise Markdown-Dateien erstellen können (und es ist kostenlos!). Es enthält großartige Funktionen wie sofortige HTML-Vorschau, einfache Formatierung mit Tastenkombinationen, CSS-Anpassung, HTML-Export und sogar einen "ablenkungsfreien" Modus.

Mou (OS X)

Mou ist eine großartige, kostenlose Mac-Anwendung, mit der Sie Markdown auf einfache und schöne Weise schreiben können. Es verfügt über großartige Funktionen wie benutzerdefiniertes Styling, Tastaturkürzel, Live-HTML, HTML-Export (mit optionalem CSS-Stil), PDF-Export, Diktatunterstützung und mehr. Für dieses Tutorial werden wir Mou verwenden, um die Dokumentation unseres Themas zu erstellen.

MarkdownNote (OS X und iOS)

MarkdownNote ist eine weitere großartige Anwendung zum Schreiben von Markdown, und die iOS-Anwendung ist perfekt, wenn Sie Markdown unterwegs schreiben möchten. Genau wie die anderen Anwendungen, die wir behandelt haben, bietet es einige großartige Funktionen, darunter Live-HTML-Vorschau, Tastenkombinationen und Dropbox-Synchronisierung.

Themendokumentation erstellen

Bisher haben wir uns mit Markdown befasst und einige Tools nachgeschlagen, mit denen Sie Markdown schreiben können. Lassen Sie uns nun eine Themendokumentation für ein nicht vorhandenes Thema erstellen, die das behandelt, was Sie normalerweise in die Dokumentation aufnehmen sollten, die Markdown-Syntax und bewährte Methoden.

Markdown-Syntax

In den folgenden Schritten werden wir Markdown so untersuchen, wie es unseren Anforderungen entspricht. Für einen tieferen Einblick in die Markdown-Syntax, lesen Sie Markdown: The Ins and Outs auf Nettuts+.

Was sollte eine Dokumentationsdatei enthalten?

Da Sie die Vor- und Nachteile Ihres Themes/Templates/Webanwendung bereits kennen, kann es etwas mühsam erscheinen, die Grundlagen zu behandeln. Der Zweck einer Dokumentationsdatei besteht darin, anderen Benutzern und Käufern als Leitfaden zu dienen. Häufig sind Installation, Anpassung und einige Optimierungen erforderlich, über die Benutzer Bescheid wissen müssen - und es ist Ihre Aufgabe, sie zu schulen. Das möchten wir vielleicht aufnehmen:

• Information
  • Autor
  • Erstellungsdatum
  • Ausführung
  • Kontaktinformation.
• Dateistruktur
  • HTML
  • CSS
  • Javascript
• Individuelle Dateistruktur
  • HTML-Struktur
  • CSS-Struktur
• Benutzerdefinierte Stile
• Dateien optimieren
  • CSS optimieren
  • Javascript optimieren
• Browser-Kompatibilität
• Änderungsprotokoll

Denken Sie daran, dass die Dokumentation für jeden mit Grundkenntnissen einfach genug sein sollte, aber auch das Ändern wichtiger Dateien behandelt. Sie müssen beispielsweise nicht unbedingt zeigen, wie bestimmte CSS-Werte geändert werden, aber Sie sollten zeigen, wie Sie auf diese Dateien zugreifen.

Schritt 1: Einrichten der Markdown-Datei

Jetzt ist es Zeit für die lustigen Sachen! Fahren Sie fort und öffnen Sie Ihren Markdown-Editor (ich werde Mou für Mac verwenden). Erstellen Sie einen Header für Ihre Dokumentationsdatei:

1

#Theme Documentation

Überschriftenelemente können einfach geschrieben werden, indem ein bis sechs # vor dem Inhalt hinzugefügt werden. Im obigen Beispiel haben wir ein # -Zeichen verwendet, um ein h1-Element mit dem Text 'Themendokumentation' zu erstellen. Wenn Sie ein h3-Element erstellen möchten, schreiben Sie ###Heading 3.

Erstellen wir nun eine horizontale Regel (<hr />), um den Titel vom anderen Inhalt zu trennen. Auch in Markdown ist dies extrem einfach:

1

***

Schritt 2: Themeninformationen

Ein wichtiger Abschnitt, den Sie Ihrer Dokumentation hinzufügen müssen, ist ein Informationsabschnitt.

1

*Theme Name:* Theme

2

*Author:* Suhail Dawood

3

*Created:* 08/08/2012

4

*Version:* 1.0.1

5

***

6

Thank you for your purchase! If you have any questions about this theme, feel free to e-mail me at **email@tutsplus.com** or tweet me **@tutsplus**

7

***

Schauen wir uns das HTML-Äquivalent des obigen Markdown-Codes an:

1

<em>Theme Name: </em>Theme<br />

2

<em>Author: </em>Suhail Dawood<br />

3

<em>Created: </em>08/08/2012<br />

4

<em>Version: </em>1.0.1<br />

5

<hr />

6

Thank you for your purchase! If you have any questions about this theme, feel free to e-mail me at <strong>email@tutsplus.com</strong> or tweet me <strong>@tutsplus</strong>

7

<hr />

Wenn Sie sich die beiden verschiedenen Quellen ansehen, können Sie sofort erkennen, dass Markdown viel intuitiver zu verstehen und zu erstellen ist. Anstatt ständig < und  > hinzufügen zu müssen, können Sie sich mit Markdown auf den Inhalt konzentrieren. Fügen Sie zum Hervorheben ein Sternchen vor und nach dem Text hinzu (z. B. *Emphasized Text*). Fügen Sie zwei Sternchen vor und nach dem Text hinzu (z. B. **Emboldened Text**). Um einen Zeilenumbruch hinzuzufügen, fügen Sie einfach zwei Leerzeichen an der Stelle hinzu, an der Sie einen Zeilenumbruch einfügen möchten.

Schritt 3: Hinzufügen eines Inhaltsverzeichnisses

Nun fügen wir unserer Markdown-Datei eine Inhaltsliste hinzu:

1

##Table of Contents

2

1. HTML Structure

3

2. CSS Files

4

3. Javascript Files

5

4. PSD Files

6

5. Theme Styles

7

6. Tweaking Javascript

8

7. Tweaking CSS

9

8. Browser Compatibility

10

***

Wenn wir dies in HTML erstellen würden, würde es so aussehen:

1

<h2>Table of Contents</h2>

2

<ol>

3

   <li>HTML Structure</li>

4

   <li>CSS Files</li>

5

   <li>Javascript Files</li>

6

   <li>PSD Files</li>

7

   <li>Theme Styles</li>

8

   <li>Tweaking Javascript</li>

9

   <li>Tweaking CSS</li>

10

   <li>Browser Compatibility</li>

11

</ol>

12

<hr />

Anstatt eine geordnete Liste und separate Listenelemente erstellen zu müssen, schreiben Sie einfach 1. First Element und fügen Sie weiter inkrementierte Elemente hinzu.

Schritt 4: HTML-Struktur

Es ist wichtig, Ihren Benutzern mitzuteilen, wie die Dateien der Site angeordnet sind. Da wir eine Dokumentation für ein Thema erstellen, sollten wir skizzieren, wie der HTML-Code des Themas strukturiert ist. Wir können dies mit dem folgenden Code skizzieren:

1

##1. HTML Structure

2

The HTML Structure for each page is as follows:

3

4

* Meta

5

* Link to CSS Files

6

* Header

7

	* Logo

8

	* Social Links

9

* Navigation

10

* Main Content

11

	* Content Slider

12

	* Articles

13

* Sidebar

14

	* Search

15

	* Post Archives

16

	* Mailing List

17

* Link to Javascript Files

18

* Javascript

19

***

Einfach. Um unser Inhaltsverzeichnis zu erstellen, haben wir eine geordnete Liste verwendet. In diesem Abschnitt haben wir verschachtelte ungeordnete Listen verwendet. Um eine ungeordnete Liste in Markdown zu erstellen, fügen Sie einfach ein Sternchen und ein Leerzeichen vor dem Text hinzu (z.B. * Item 1). Um Listenelemente zu verschachteln, rücken Sie einfach nach innen und erstellen Sie ein weiteres Listenelement.

Schritt 5: CSS-Dateien

Gerade bei Themes ist die CSS-Dokumentation sehr wichtig. Es ist eine gute Idee, die verschiedenen CSS-Dateien, die im Design enthalten sind, sowie eine kurze Beschreibung jeder Datei zu skizzieren:

1

##2. CSS Files

2

There are 3 CSS files in this theme:

3

4

* main.css

5

* colors.css

6

* skeleton.css

7

8

#####main.css

9

This CSS file is the main stylesheet for the theme. It holds all the values for the different elements of theme and the default color scheme.

10

#####colors.css

11

This CSS file holds the styling of all the other colors schemes that are included in the theme.

12

#####skeleton.css

13

This CSS file allows the theme to be responsive, adapting to different screen sizes. 

14

***

Stellen Sie sicher, dass Sie Überschriften verwenden, um verschiedene Abschnitte der Dokumentationsdatei zu trennen. Eine schön angelegte Dokumentationsdatei führt zu weniger verwirrten Benutzern!

Schritt 6: Javascript-Dateien

Wenn Ihr Theme Javascript-Dateien enthält, ist es eine gute Idee, diese zumindest in der Dokumentation zu skizzieren:

1

##3. Javascript Files

2

There are 2 Javascript files in this theme:

3

4

* jquery.js

5

* slider.js

6

7

#####jquery.js

8

This theme uses the jQuery Javascript library.

9

#####slider.js

10

The content slider in the theme runs on this Javascript file. There are some settings that can be tweaked, this will be covered in the 'Tweaking Javascript' section.

11

***

Stellen Sie sicher, dass Sie die Dateien in Ihrem Design nicht nur auflisten, sondern auch beschreiben. Dies wird es dem Benutzer viel einfacher machen, den Inhalt jeder Datei zu verstehen und zu entscheiden, ob er damit herumspielen möchte oder nicht.

Schritt 7: PSD-Dateien

Obwohl es in ThemeForest einen separaten Abschnitt für PSD-Vorlagen gibt, haben sich viele Autoren dafür entschieden, PSD-Dateien in ihre codierten Vorlagen aufzunehmen, um dem Benutzer die Freiheit zu geben, Designänderungen vorzunehmen. Wenn Ihr Design PSD-Dateien enthält, ist es möglicherweise eine gute Idee, sie genau wie bei allen anderen Dateien zu skizzieren:

1

##4. PSD Files

2

Included in this theme is 5 different PSD files:

3

4

1. homepage.psd

5

2. about.psd

6

3. portfolio.psd

7

4. blog.psd

8

5. contact.psd

9

10

These PSD files will be handy if you would like to make any changes to the theme's design. You can also create a new page layout using the existing PSD files as a base to work with.

11

***

Es empfiehlt sich, Ihre PSD-Dateien klar zu benennen (z. B. full-width-page.psd) und nicht vage Namen (z. B. template-003.psd). Auf diese Weise können Benutzer finden, was sie brauchen, ohne jede Datei öffnen zu müssen.

Schritt 8: Themenstile

Höchstwahrscheinlich enthält Ihr Thema eine Auswahl von Farbschemata, aus denen Ihre Benutzer auswählen können. Wenn dies der Fall ist, stellen Sie sicher, dass Sie skizzieren, wie dies geschieht:

1

##5. Theme Styles

2

Included with this theme are 10 different theme styles:

3

4

1. Light

5

2. Dark

6

3. Grey

7

4. Green

8

5. Red

9

6. Orange

10

7. Blue

11

8. Purple

12

9. Brown

13

10. Dark Blue

14

15

To change these styles, go to the WordPress backend, select **Options > Styles** and select the style you would like.

16

***

Im obigen Beispiel habe ich die verschiedenen Farbschemata aufgelistet, die im Design enthalten sind, und gezeigt, wie Sie sie ändern können.

Schritt 9: Javascript optimieren

Wenn Ihr Code Javascript-Dateien mit Anpassungsparametern enthält (z. B. ein Slider-Skript), ist es eine gute Idee, Ihren Benutzern zu zeigen, wie diese Werte bearbeitet werden:

1

##6. Tweaking Javascript

2

The content slider in the theme runs off of slider.js, and there are a couple of values that can be changed to alter the look and feel of the slider.

3

#####Changing Values

4

In slider.js, you can alter these values:

5

6

<code>auto: true</code>  

7

*Boolean: Animate automatically, true or false*  

8

9

<code>speed: 1000</code>  

10

*Integer: Speed of the transition, in milliseconds*

11

12

13

<code>pager: true</code>  

14

*Boolean: Show pager, true or false*  

15

16

<code>nav: false</code>  

17

*Boolean: Show navigation, true or false*  

18

***

Der obige Code beschreibt, wie ein Benutzer Werte ändern kann. Um Code zu stylen, umschließen Sie den relevanten Text in <code>-Tags. Anwendungen wie Mou fügen diesen Elementen in der Live-Vorschau ein Styling hinzu, und Sie können den Code auch exportieren, um das Styling beizubehalten. Wir werden später noch ein wenig über den Export Ihrer Dokumentation sprechen.

Schritt 10: CSS optimieren

CSS-Dateien werden sehr oft von einem Benutzer angepasst. Sie werden es sicherlich für hilfreich halten, wenn Sie der Dokumentation einen Abschnitt hinzufügen, der zeigt, wie Sie auf die CSS-Dateien zugreifen, damit sie sie bearbeiten können.

1

##7. Tweaking CSS

2

The theme is build on a responsive framework, which allows content to be seen optimally on all screen sizes.

3

#####Changing the CSS

4

Start off by going into the WordPress backend, **Themes > Theme > View Source**. Select the *style.css* file to view and have the ability to edit the code.

5

6

Here, you can change things like the fonts, sizes, colors, etc.

7

***

Nachdem der Benutzer Zugriff auf die CSS-Datei hat, kann er die gewünschten Änderungen vornehmen.

Schritt 11: Browserkompatibilität

Es ist eine gute Idee, den Benutzer über alle Browserkompatibilitätsprobleme zu informieren:

1

##8. Browser Compatibility

2

This theme works well (-) or great (X) in the following browsers:

3

4

**IE 6-8** -  

5

**IE 9+** X  

6

**Chrome** X  

7

**Firefox** X  

8

**Safari** X  

9

**Opera** X

10

***

Wenn Sie diesen Abschnitt erweitern möchten, können Sie erklären, welche Funktionen des Themes in bestimmten Browsern leiden.

Schritt 12: Fertigstellen der Dokumentation

Um unsere Dokumentation zu vervollständigen, fügen wir einen Abschnitt hinzu, in dem unsere Benutzer wissen, wie sie uns bei weiteren Fragen kontaktieren können. Fügen wir diesen Code hinzu:

1

####Theme by Suhail Dawood

2

If you have any other questions that aren't covered in the documentation, feel free to e-mail <email@tutsplus.com> or add a new post on the [forum](http://forum.tutsplus.com/ "visit the forum").

Um E-Mails mit Markdown zu verknüpfen, packen Sie einfach Ihre E-Mail-Adresse zwischen Chevrons (z. B. <email@tutsplus.com>).

Das Hinzufügen von Links in Mardown ist ziemlich einfach. <a href="http://tutsplus.com" alt="The World's Leading Tutorial Network">Tuts+ ist der Hyperlink, der im HTML-Code erscheinen soll. Der Text sollte in eckige Klammern gesetzt werden [Tuts+]. Unmittelbar darauf folgt die Website-Adresse in Klammern (z.B. (http://www.tutsplus.com/)) und der alt-Text in doppelte Anführungszeichen in Klammern (zB (http://www.tutsplus.com / "The World's Leading Tutorial Network")).

Endgültiger Markdown-Code

Hier ist ein Blick auf unseren endgültigen Markdown-Code für diese Dokumentation:

1

#Theme Documentation

2

***

3

*Theme Name:* Theme  

4

*Author:* Suhail Dawood  

5

*Created:* 08/06/2012  

6

*Version:* 1.0.1  

7

***

8

Thank you for your purchase! If you have any questions about this theme, feel free to e-mail me at **email@tutsplus.com** or tweet me **@tutsplus**

9

***

10

##Table of Contents

11

1. HTML Structure

12

2. CSS Files

13

3. Javascript Files

14

4. PSD Files

15

5. Theme Styles

16

6. Tweaking Javascript

17

7. Tweaking CSS

18

8. Browser Compatibility

19

***

20

##1. HTML Structure

21

The HTML Structure for each page is as follows:

22

23

* Meta

24

* Link to CSS Files

25

* Header

26

	* Logo

27

	* Social Links

28

* Navigation

29

* Main Content

30

	* Content Slider

31

	* Articles

32

* Sidebar

33

	* Search

34

	* Post Archives

35

	* Mailing List

36

* Link to Javascript Files

37

* Javascript

38

***

39

##2. CSS Files

40

There are 3 CSS files in this theme:

41

42

* main.css

43

* colors.css

44

* skeleton.css

45

46

#####main.css

47

This CSS file is the main stylesheet for the theme. It holds all the values for the different elements of theme and the default color scheme.

48

#####colors.css

49

This CSS file holds the styling of all the other colors schemes that are included in the theme.

50

#####skeleton.css

51

This CSS file allows the theme to be responsive, adapting to different screen sizes. 

52

***

53

##3. Javascript Files

54

There are 2 Javascript files in this theme:

55

56

* jquery.js

57

* slider.js

58

59

#####jquery.js

60

This theme uses the jQuery Javascript library.

61

#####slider.js

62

The content slider in the theme runs on this Javascript file. There are some settings that can be tweaked, this will be covered in the 'Tweaking Javascript' section.

63

***

64

##4. PSD Files

65

Included in this theme is 5 different PSD files:

66

67

1. homepage.psd

68

2. about.psd

69

3. portfolio.psd

70

4. blog.psd

71

5. contact.psd

72

73

These PSD files will be handy if you would like to make any changes to the theme's design. You can also create a new page layout using the existing PSD files as a base to work with.

74

***

75

##5. Theme Styles

76

Included with this theme are 10 different theme styles:

77

78

1. Light

79

2. Dark

80

3. Grey

81

4. Green

82

5. Red

83

6. Orange

84

7. Blue

85

8. Purple

86

9. Brown

87

10. Dark Blue

88

89

To change these styles, go to the WordPress backend, select **Options > Styles** and select the style you would like.

90

***

91

##6. Tweaking Javascript

92

The content slider in the theme runs off of slider.js, and there are a couple of values that can be changed to alter the look and feel of the slider.

93

#####Changing Values

94

In slider.js, you can alter these values:

95

96

<code>auto: true</code>  

97

*Boolean: Animate automatically, true or false*  

98

99

<code>speed: 1000</code>  

100

*Integer: Speed of the transition, in milliseconds*

101

102

103

<code>pager: true</code>  

104

*Boolean: Show pager, true or false*  

105

106

<code>nav: false</code>  

107

*Boolean: Show navigation, true or false*  

108

***

109

##7. Tweaking CSS

110

The theme is build on a responsive framework, which allows content to be seen optimally on all screen sizes.

111

#####Changing the CSS

112

Start off by going into the WordPress backend, **Themes > Theme > View Source**. Select the *style.css* file to view and have the ability to edit the code.

113

114

Here, you can change things like the fonts, sizes, colors, etc.

115

***

116

##8. Browser Compatibility

117

This theme works well (-) or great (X) in the following browsers:

118

119

**IE 6-8** -  

120

**IE 9+** X  

121

**Chrome** X  

122

**Firefox** X  

123

**Safari** X  

124

**Opera** X

125

***

126

####Theme by Suhail Dawood

127

If you have any other questions that aren't covered in the documentation, feel free to e-mail <email@tutsplus.com> or add a new post on the [forum](http://forum.tutsplus.com/ "visit the forum").

Exportieren der Dokumentation

Nachdem wir die Dokumentationsdatei erstellt haben, ist es an der Zeit, diesen Markdown in eine HTML- oder PDF-Datei zu konvertieren. Ich werde Mou verwenden, um meine Dokumentation zu exportieren, aber die Schritte sind allgemein und gelten für die meisten Anwendungen.

In HTML exportieren

Um Ihre Dokumentation in HTML zu exportieren, wählen Sie einfach Datei > Exportieren > HTML. Benennen Sie Ihre Dokumentationsdatei und aktivieren/deaktivieren Sie 'CSS einbeziehen', je nachdem, ob Sie möchten, dass das gleiche Styling, das in der Anwendung angezeigt wird, auf Ihre HTML-Datei angewendet wird. Mou erstellt keine separate CSS-Datei, sondern fügt stattdessen das Styling der HTML-Datei hinzu. Mou erstellt auch die notwendigen Tags wie html,doctypehead usw.

Als PDF exportieren

Wenn Sie Ihre Dokumentation in PDF exportieren möchten, wählen Sie Datei > Exportieren > PDF. Im Fall von Mou werden alle in der HTML-Live-Vorschau angezeigten Stile in die PDF-Datei aufgenommen.

Und wir sind fertig! Kristallklare, lesbare Dokumentation für Auftraggeber, Kunden und Kollegen. Laden Sie die Quelldateien für dieses Tutorial herunter und sehen Sie sich die resultierenden .md .html- und .pdf-Dateien an.

Übersicht über die Markdown-Syntax

Hier ist ein kurzer Vergleich der HTML- und Markdown-Syntax, die wir in diesem Tutorial behandelt haben

Zusätzliche Ressourcen

• Markdown bietet noch viel mehr, einschließlich alternativer Möglichkeiten zum Erstellen anderer Elemente. Sie können einen detaillierten Blick auf die gesamte Markdown-Syntax auf Nettuts+ werfen.
• Das offizielle Markdown-Projekt bei Daring Fireball
• Markdown auf Wikipedia
• Vim Essential Plugin: Markdown zu HTML auf Nettuts+
• Weitere Informationen zur Themeforest-Dokumentation hier, hier und hier (Danke an Ivor dafür!)