Eine README-Datei ist ein wichtiger Leitfaden, der anderen Entwicklern eine detaillierte Beschreibung Ihres GitHub-Projekts gibt.

Sie fragen sich vielleicht, warum jemand Zeit damit verbringen sollte, eine README-Datei zu schreiben. Nun, hier sind einige Gründe, um Sie davon zu überzeugen, dass es eine gute Idee ist:

  1. Eine gute README hilft Ihrem Projekt, sich von anderen Projekten abzuheben und sollte so gut sein wie Ihr Projekt selbst.
  2. Es ist das erste, was auffällt, wenn Sie auf Ihr Projekt stoßen, daher sollte es ziemlich kurz, aber detailliert sein.
  3. Die Qualität einer README-Beschreibung unterscheidet ein gutes Projekt von einem schlechten.
  4. Oftmals wird README.md als Website gehostet; Stellen Sie sicher, dass Ihre Webseite genauso cool aussieht wie Ihr Projekt!

Inhalt der Readme-Datei:

Im Folgenden sind die allgemeinen Schlüsselkomponenten einer Readme-Datei aufgeführt:

  • Fügen Sie den Titel Ihres Projekts hinzu: Dies ist der Name des Projekts. Es beschreibt das gesamte Projekt in wenigen Worten und hilft den Menschen, das primäre Ziel und Ziel zu verstehen.
  • Schreiben Sie eine Beschreibung: Ihre Beschreibung ist ein wesentlicher Bestandteil Ihres Projekts. Eine gut gepflegte Beschreibung ermöglicht es Ihnen, Ihre Arbeit anderen Entwicklern sowie potenziellen Arbeitgebern vorzustellen.
  • So verwenden Sie Ihr Projekt: Stellen Sie Anweisungen und Beispiele bereit, damit Benutzer oder Mitwirkende das Projekt verwenden können. Dies macht es ihnen leicht, so dass sie im Falle eines Problems immer eine Anlaufstelle haben.
  • Credits einbeziehen: Wenn Sie als Team an dem Projekt gearbeitet haben, listen Sie Ihre Teammitglieder auf. Sie sollten auch ihre GitHub-Profile einbeziehen.

Sie können auch die folgenden Details in der Readme-Datei hinzufügen:

  1. Was war Ihre Motivation? Warum haben Sie dieses Projekt gebaut?
  2. Welches Problem löst das Projekt? Oder was macht es?
  3. Warum haben Sie bestimmte Technologien verwendet? Wenn Ihr Projekt viele Funktionen hat, listen Sie sie hier auf.
  4. Erwähnen Sie einige der Herausforderungen, mit denen Sie konfrontiert waren, und Funktionen, die Sie in Zukunft implementieren möchten.
  5. Erwähnen Sie alles, was Sie glauben, dass Sie stolz darauf sind, es in diesem Projekt zu bauen oder zu haben
  6. Was haben Sie dabei gelernt?
  7. Was kommt als nächstes für das Projekt?
  8. Erwähnen Sie Sprachen, Frameworks, Datenbanken usw.
  9. Stellen Sie Bereitstellungslinks oder andere erforderliche Links bereit

Bevor wir tief in die Readme unseres Projekts eintauchen, lassen Sie uns die Markdown-Sprache besprechen.

Abschlag

  • Markdown ist eine leichte Auszeichnungssprache , die es uns ermöglicht, ein digitales Textdokument mit typischen Formatierungstechniken wie Überschriften, Hervorhebungen, Listen, Bildern und Links zu gestalten.
  • Markdown-Dateien haben die Erweiterungen .md oder .markdown . Wir können Markdown in XHTML oder HTML konvertieren, um es in einem Browser gut anzuzeigen.
  • Einige der vielen Verwendungsmöglichkeiten von Markdown sind:
  1. Readme-Dateien
  2. Schreiben von Nachrichten in Online-Diskussionsforen
  3. Erstellen von Rich-Text mit einem Nur-Text-Editor, E-Mails und technischer Dokumentation.
  • Beliebte Websites, die Markdown verwenden, sind GitHub, Trello, Reddit, SourceForge und StackExchange.
  • Markdown-Parser unterstützen auch das Einfügen von HTML-Codeblöcken, die die eingeschränkte Syntax von Markdown ergänzen, wenn Sie ein komplexeres Design erzielen möchten.

Warum sollten wir Markdown verwenden?

  1. Einfachere Erstellung von Dokumentationen für Nicht-Tech-Autoren , die sowohl kollaborativ als auch flexibel sein können.
  2. Einfach zu verstehen – Es hat eine Basis von E-Mail-Formatierungskonventionen, denen die meisten von uns bereits ausgesetzt sind.
  3. Leicht lesbar (im Rohzustand), im Gegensatz zu HTML, das voller Tags ist.
  4. Plattformunabhängig – das heißt, Sie können Markdown-Dateien in jedem Texteditor erstellen.
  5. Wiederverwendbare Fähigkeit : Sie ist vielseitig und wir können sie verwenden, um Notizen zu machen, Inhalte für eine Website zu erstellen oder druckfertige Dokumente zu erstellen.

Lassen Sie uns nun Elemente der Markdown-Sprache besprechen.

1. Überschriften:

  • Überschriften machen Ihren Text lesbarer und helfen, die Themen aufzugliedern.
  • In Markdown werden Überschriften mit Hashes (#) vor der Zeile formatiert, die Ihre Überschrift enthält.
  • Sie können bis zu sechs Hashes verwenden, wobei die Anzahl der Hashes einer Überschriftenebene entspricht.

Syntax:

# Heading level 1
## Heading level 2
### Heading level 3
#### Heading level 4
##### Heading level 5
###### Heading level 6

Formatierter Text:

2. Absätze:

  • Um Ihre Informationen in Absätze aufzuteilen (mit einer merklichen Lücke zwischen den einzelnen Absätzen).
  • Absätze werden durch eine Leerzeile (eine Zeile ohne Zeichen) zwischen aufeinanderfolgenden Absätzen getrennt.

Syntax:

Paragraph 1
Paragraph 2

3. Zeilenumbrüche:

  • Um Ihre Informationen aufzuteilen, indem Sie eine neue Zeile mit weniger Platz einfügen, als Sie bei der Formatierung als Absatz erhalten würden. Nennt sich Zeilenumbruch.
  • Um einen Zeilenumbruch in Ihre Markdown-Datei einzufügen, beenden Sie Ihre Zeile mit mindestens zwei Leerzeichen und drücken Sie die Eingabetaste. Es wird eine neue Zeile für Ihren Text gerendert.

Syntax:

Line 1  
Line 2

4. Kursiv:

  • Wickeln Sie den Artikel mit einem Stern/Unterstrich auf jeder Seite ein.

Beispiel:

*one star on each side*
_This text is also italic_

Formatierter Text:

one star on each side
This text is also italic

5. Fett:

  • Wickeln Sie den Artikel mit zwei Sternen/Unterstrichen auf jeder Seite ein.

Beispiel:

**two stars on each side**
__This text is also bold__

Formatierter Text:

two stars on each side
This text is also bold

6. Gleichzeitig fett und kursiv:

  • Machen Sie Ihren Text gleichzeitig fett und kursiv, um ihm noch mehr Gewicht zu verleihen!
  • Verwenden Sie drei Sternchen (oder drei Unterstriche), um Ihr Wort oder Ihren Satz einzuschließen.

Beispiel:

***This text is italic and bold.***
___This text is also italic and bold.___

Formatierter Text:

This text is italic and bold.
This text is also italic and bold.

7. Durchschlagen:

  • Wickeln Sie den Gegenstand auf jeder Seite in zwei Tilden.

Beispiel:

~~strikethrough~~

Formatierter Text:

8. Verbindungen:

  • Um in Markdown-Inhalten auf externe Websites zu verlinken, verwenden Sie zwei Sätze von Klammern.
  • Schließen Sie den Linktext in eckige Klammern [ ] ein und schließen Sie dann die URL in Klammern ( ) ein: [ ]( ).

Beispiel:

[This text links to gfg](https://write.geeksforgeeks.org/).

Formatierter Text:

This text links to gfg

9. Bilder:

  • Das Einfügen eines Bildes in Ihre Markdown-Datei ähnelt der Formatierung für Links.
  • Beginnen Sie Ihre Bildformatierung mit einem Ausrufezeichen. Verwenden Sie als Nächstes eckige Klammern, um den Alt-Text Ihres Bildes einzuschließen, neben Klammern, die die URL für Ihr Bild enthalten.
  • Stellen Sie sicher, dass zwischen dem Ausrufezeichen, den eckigen Klammern oder runden Klammern keine Leerzeichen stehen.
  • Wenn Ihre Markdown-Datei in HTML gerendert wird, wird das Bild direkt in den Textkörper eingebettet.

Beispiel:

![image](https://media.geeksforgeeks.org/wp-content/cdn-uploads/20210914130327/100-Days-of-Code-with-GFG-Get-Committed-to-a-Challenge.png)

Formatiertes Bild:

10. Ungeordnete Listen:

  • Mit Markdown können Sie Ihre Listen mit mehreren verschiedenen Symbolen formatieren: Sternchen (*), Bindestriche (-) oder Pluszeichen (+).
  • Es liegt an Ihnen, welches Symbol Sie bevorzugen. Das Ergebnis ist das gleiche.

Syntax:

-Just add a dash first and then write a text.

-If you add another dash in the following line, you will have another item in the list.
    - If you add four spaces or use a tab key, you will create an indented list.
        - If you need sert an indenta list within an intended one, just press a tab key again.

Sometimes you want bullet points:

*Start a line with a star 
*Profit!

Ausgabe:

11. Geordnete Listen:

  • Formatieren Sie Ihre geordneten Listen, indem Sie jedem Listenelement eine Zahl voranstellen, gefolgt von einem Punkt und einem Leerzeichen.
  • In Markdown spielt es keine Rolle, welche Zahlen Sie zum Formatieren Ihrer Liste verwenden, da die Liste immer als 1, 2, 3 usw. dargestellt wird.

Beispiel:

1. Just type a number follo by a dot.
2. If you want to add a second item, just type in another number followed by a dot.
1. If you make a mistake when typing numbers, fear not, Markdown will correct for you. 
    1. If you press a tab key or type four spaces, you will get an indented list and the numbering will start from scratch.
        1. If you want to insert an indented numbered list within an existing indented numbered one, just press the tab key again. 
            -If need be, you can also add an indented unordered list within an indented numbered one, by pressing a tab key and typing adash.

Formatierter Text:

12. Blockzitate:

  • Manchmal möchten wir in Markdown mit Anführungszeichen auf eine externe Quelle verweisen. Es wird als Blockzitat bezeichnet.
  • Sie stellen ein Blockzitat dar, indem Sie der ersten Zeile des Blockzitats ein Größer-als-Zeichen oder eine spitze Klammer (>) voranstellen.

Beispiel:

> This is a blockquote
> This is a blockquote
> This is a blockquote

Formatierter Text:

13. Horizontale Regeln:

  • Eine horizontale Linie ist ein winziges Funktionselement, mit dem Sie Textblöcke in Ihrer Markdown-Datei visuell aufteilen können.
  • Wir stellen eine horizontale Linie durch drei oder mehr Bindestriche (-), Sternchen (*) oder Unterstriche (_) dar.

Beispiel:

---
* * *
___

Formatierter Text:

14. Codeschnipsel:

  • Um Code-Snippets als Beispiele zu referenzieren, formatieren Sie Code-Snippets mit Backticks `, die Ihr Code-Snippet umschließen.
  • Der erste Backtick „öffnet“ das Snippet und der zweite Backtick „schließt“ es.

Beispiel:

`This is a code snippet.`

Formatierter Text:

15. Codeblöcke:

  • Das Formatieren von Codeblöcken ist nützlich, wenn Sie einen größeren Codeblock in Ihre Markdown-Datei aufnehmen müssen.
  • Formatieren Sie Ihre Codeblöcke, indem Sie jede Zeile Ihres Codeblocks mit einem Tabulator oder vier Leerzeichen einrücken.
  • Und wenn Sie Syntaxhervorhebung verwenden möchten, einschließlich der Sprache.

Beispiel:

```javascript

if (isAwesome){

 return true

}

```

Formatierter Text:

16. Flucht:

  • In Markdown müssen Sie häufig Zeichen in Ihren Text einfügen (z. B. ein Sternchen), die möglicherweise Teil der Markdown-Syntax sind.
  • Sie müssen diese Zeichen „escapen“, damit Ihre Markdown-Anwendung diese Zeichen nicht als Formatierung liest.
  • Sie maskieren Zeichen in Markdown mit einem umgekehrten Schrägstrich vor dem Zeichen ohne Leerzeichen dazwischen.

Syntax:

\ backslash
` backtick
* asterisk
_ underscore
{} curly braces
[] square brackets
() parentheses
# hash symbol
+ plus sign
– minus sign (hyphen)
. dot
! exclamation mark

Formatierter Text:

17. Listen innerhalb eines Blockquotes:

  • Verschachteln Sie Ihre Listenformatierung in Ihrer Blockquote-Formatierung.
  • Formatiere dein Blockzitat mit einem Größer-als-Zeichen (>) gefolgt von einem Leerzeichen, einschließlich eines Zeichens vor jeder Zeile deines Blockzitats.
  • Fügen Sie Ihre Listenformatierung (*) direkt nach Ihren Größer-als-Zeichen hinzu.

Beispiel:

> This is a blockquote
> * This is a list item within a blockquote
> * This is a list item within a blockquote
> * This is a list item within a blockquote

Formatierter Text:

18. Zitate:

  • Fügen Sie am Anfang jeder Zeile ein Zitat mit dem Zeichen > hinzu.

Beispiel:

> "I make Jessica Simpson look like a rock scientist."

> —Tara Reid, actress

Formatierter Text:

Da wir über readme.md sprechen , das in GitHub-Repositories vorhanden ist, lassen Sie uns über GitHub Flavored Markdown sprechen!

GitHub Flavored Markdown

  • GitHub.com verwendet seine Version der Markdown-Syntax, die einen zusätzlichen Satz nützlicher Funktionen bietet, von denen viele die Arbeit mit Inhalten auf GitHub.com erleichtern.
  • Beachten Sie, dass einige Funktionen von GitHub Flavored Markdown nur in den Beschreibungen und Kommentaren von Issues und Pull Requests verfügbar sind.
  • Dazu gehören @Erwähnungen sowie Verweise auf Issues und Pull Requests.

1. Syntaxhervorhebung:

  • Hebt die Syntax hervor.

Beispiel:

Formatierter Code:

2. Aufgabenlisten:

  • So erstellen Sie eine Aufgabenliste
  • Wenn Sie eine Aufgabenliste in den ersten Kommentar eines Problems aufnehmen, erhalten Sie eine praktische Fortschrittsanzeige in Ihrer Problemliste.
  • Es funktioniert auch in Pull-Requests.

Beispiel:

- [x] @mentions, #refs, [links](), **formatting**, and <del>tags</del> supported
- [x] list syntax required (any unordered or ordered list supported) 
- [x] this is a complete item 
- [ ] this is an incomplete item

Formatierter Text:

3. Tabellen:

  • Sie können Tabellen erstellen, indem Sie eine Liste von Wörtern zusammenstellen und sie mit Bindestrichen teilen – (für die erste Zeile) und dann jede Spalte mit einem senkrechten Strich (|) trennen.

Beispiel:

First Header | Second Header 
 ------------ | ------------- 
Content from cell 1 | Content from cell 2 
Content in the first column | content in the second column

Formatierter Text:

4. Benutzername @Erwähnungen:

  • Wenn Sie ein @-Symbol gefolgt von einem Benutzernamen eingeben, wird diese Person benachrichtigt, dass sie kommen und sich den Kommentar ansehen soll.
  • Dies wird als „@Erwähnung“ bezeichnet, weil Sie die Person erwähnen.
  • Sie können auch Teams innerhalb einer Organisation @erwähnen.

5. Automatische Verlinkung für URLs:

  • Jede URL (wie http://www.github.com/) wird automatisch in einen anklickbaren Link umgewandelt.

Da Sie jetzt alles über readme.md wissen, vergessen Sie beim nächsten Erstellen eines Repositorys nicht, Ihrem Projekt eine perfekte Readme hinzuzufügen!