strobelstefan.org
/
Markdown
1
3
Fork 0
Code Issues Releases Activity
Markdown Spickzettel https://strobelstefan.org
28 Commits
1 Branch
0 Tags
374 KiB
Go to file
Stefan 9d61da9201 Redirect To New Repository Adress 2023-11-11 08:40:00 +01:00
pics Markdwon-to-PDF 2023-10-15 18:17:20 +02:00
README.md Redirect To New Repository Adress 2023-11-11 08:40:00 +01:00

README.md

Markdown Spickzettel

❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️
❗️
❗️ ACHTUNG! Das Template ist umgezogen!
❗️
❗️ Die aktuelle Version wird ebenfalls bei Codeberg verwaltet.
❗️ 👉 https://codeberg.org/sst/markdown
❗️
❗️ Der Umzug erfolgte im Rahmen der Website Neustrukturierung und Umbenennung
❗️
❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️❗️

Was ist Markdown?

Markdown ist für Menschen eine leicht verständliche und einfach zu erlernende Auszeichnungssprache.

Dateiendung für Markdown

Die Dateiendung .md, in manchen Fällen auch .markdown, steht für "Markdown Documentation". Diese Bezeichnung weist darauf hin, dass jedes .md-File in einer der verfügbaren Dialekte der Markdown-Entwicklungssprachen geschrieben ist. Diese zählen zu den Markup- bzw. Auszeichnungssprachen.

Editoren

Zettlr

Zettlr ist ein schlanker Markdowneditor für das 21. Jahrhundert.

Ein lesenswerter Beitrag zum Arbeiten mit Markdown-Dokumenten und dem Editor Zettlr findet sich auf 🔗 https://www.hendrik-erz.de/post/how-i-work-part-v-zettlr-and-academic-markdown

Visual Studio Code

Der Editor aus dem Hause Microsoft eignet sich auch sehr gut zum Schreiben von Markdown Dokumenten.

Visual Code Studio gibt es für alle gängigen Betriebssysteme. Mit Erweiterungen kann der Funktionsumfang erweitert werden.

(K)Ubuntu:

sudo snap install code --classic

Mac OS

brew install --cask visual-studio

Joplin

Ein guter Markdown-Editor ist 🔗 Joplin.

Ich habe den Editor bereits in meinem Blog vorgestellt.

Der Editor eignet sich hervorragend für die Speicherung von Notizen auf Cloud-Diensten, wie z.B. Nextcloud.

Obsidian

Obsidian kann auch als Markdown-Editor verwendet werden.

Notepad++

Es wird für den beliebten Editor Notepad++ eine Erweiterung angeboten, die sich über die "Plugin-Verwaltung" sehr einfach installieren lässt.

Erweiterungen --> Plugin-Verwaltung

Dort sucht man nach dem Plugin "MarkdownViewer++" und installiert es.

Anschließend lassen sich die Markdown-Dateien in der Vorschau ausgeben.
Die Vorschau wird mit der Tastenkombination Strg+⇧+M (Strg + Shift + M) aktiviert.

Bei dem Editor "Notepad++" kann es evtl. zu Problemen in der Preview kommen, wenn man Links setzt. Hier bietet sich ein relativ unkomplizierter Workaround an. Anstatt die Preview im Editor anzeigen zu lassen, kann die Anzeige auch in einem Webbrowser erfolgen. Für die Anzeige ist eine Erweiterung zu installieren.

Webbrowser - Markdown Viewer

Chrome Browser

Mozilla Firefox

Metadaten

Metadaten können direkt am Anfang hinzugefügt werden.

---
[//]: # (Title: Title)
[//]: # (Author: Author's Name)
[//]: # (Date: yyyy-mm-dd)
[//]: # (Comment: Kommentare) 
[//]: # (Tags: #tag1, #tag)  
[//]: # (CSS: https://path-to-css)
---

Allgemeine Befehle

Kursiv = *Kursiv*

Fett = **Fett**

Kursiver und fetter Text = ***Kursiver und fetter Text***

Durchgestrichener Text = ~~Dieser Text ist durchgestrichen.~~

Horizontale Linie = ***

Horizontale Linie = ---

Inhaltsverzeichnis einfügen

Die Funktion wird nicht von jedem Markdown-Editor unterstützt.

[TOC]

Ein vollständiges Inhaltsverzeichnis kann mit Visual Studio Code erstellt werden, wie bei diesem Dokument. Für beide Editoren sind dafür Erweiterungen notwendig.

Code

Code einfügen = Am Anfang und am Ende einer Zeile

Code Block - Möglichkeit 1:

```text
Code Block
```

Code Block - Möglichkeit 2:

Einrücken um 4 Leerzeichen

Test
Test2

    Test
    Test2

Überschriften

Überschrift 1 = # Überschrift 1
Überschrift 2 = ## Überschrift 2
Überschrift 3 = ### Überschrift 3
Überschrift 4 = #### Überschrift 4
Überschrift 5 = ##### Überschrift 5
Überschrift 6 = ###### Überschrift 6

Zeilenumbruch

Ein Zeilenumbruch wird durch 2 Leerzeichen am Zeilenende erzwungen.

Ohne Zeilenumbruch
Erste Zeile Zweite Zeile

Erste Zeile
Zweite Zeile

Mit Zeilenumbruch
Erste Zeile
Zweite Zeile

Erste Zeile  
Zweite Zeile

Seitenumbruch

Ein Seitenumbruch kann in einem Markdown-Dokument an beliebiger Stelle eingefügt werden. Auf die Markdown Darstellung hat das keinen Einfluss. Der Seitenumbruch wird erst bei einem Export in eine PDF-Datei eingefügt.

<div style="page-break-after: always;"></div>

Checkliste/Aufgabenliste

  • Text
  • Text
- [ ] Text muss angegeben werden
- [ ] Text muss angegeben werden
  • Text
  • Text
* [ ] Text muss angegeben werden
* [ ] Text muss angegeben werden

Ungeordnete Listen

Um mit Markdown eine unsortierte Liste zu erstellen, könnt ihr die Zeichen Plus, Bindestrich oder ein Sternchen verwenden. 1

Liste mit *

  • Listeneintrag
  • Listeneintrag
* Listeneintrag
* Listeneintrag

Liste mit * und Einrückungen

Die einzurückende Zeile ist mit 2 Leerzeichen einzurücken. Je nach verwendetem Markdowneditor auch mit Tabulator

  • Listeneintrag
  • Listeneintrag
    • Listeneintrag
    • Listeneintrag
* Listeneintrag
* Listeneintrag
  * Listeneintrag
  * Listeneintrag

Liste mit +

  • Listeneintrag
  • Listeneintrag
+ Listeneintrag
+ Listeneintrag

Liste mit -

  • Listeneintrag
  • Listeneintrag
- Listeneintrag
- Listeneintrag

Geordnete Liste

1. Line
2. Line
    1. Sub-Line
    2. Sub-Line
3. Line
  1. Sub-Line
  2. Sub-Line

Zitate

Zitatebene 1 - Zitat

Zitatebene 2 - Zitat im Zitat

Zitatebene 3 - Zitat im Zitat im Zitat

> Zitatebene 1 - Zitat

>> Zitatebene 2 - Zitat im Zitat

>>> Zitatebene 3 - Zitat im Zitat im Zitat

Verweise innerhalb des Dokuments

Verweis 1

Verweis 2

Verweis 3

  1. Verweis 1
  2. Verweis 2
  3. Verweis 3

Als Code sieht das Ganze dann so aus

1. [Verweis 1](#verweis-1)
2. [Verweis 2](#verweis-2)
3. [Verweis 3](#verweis-3)

Verweise auf andere Dokumente

Es lässt sich ein Link auf ein anderes Dokument einsetzen

README

[README](readme.md)

Verweise auf Abschnitte anderer Dokumente

Verweise auf Abschnitte innerhalb anderer Dokumente sind ebenfalls möglich:

README

[README](readme.md#kaffeespende)

Bilder einfügen

Die grundsätzliche Syntax für das Einfügen von Bildern sieht wie folgt aus.

![image photo.jpg]
![image photo.jpg Beispiel]
![image photo.jpg "Dies ist ein Beispielbild"]

Wird das Markdown-Dokument nur für GitHub, codeberg.org oder nur im Webbrowser dargestellt und nicht in ein anderes Format konvertiert, dann eignet sich die HTML-Option (Möglichkeit 4 - Verwendung von HTML) am besten zum Einfügen von Bilddateien.

Möglichkeit 1

Die Möglichkeit eignet sich besonders, wenn das Markdown-Dokument mit Pandoc in ein PDF konvertiert werden soll.

Es wird das Bild als Referenz im Dokument definiert. Dazu wird irgendwo der Befehl eintragen:

[Bild 1]: /pfad/zum/bild.png "Beschreibung"

An der Stelle, an der das Bild angezeigt werden soll, wird das Bild dann "aufgerufen".

![Irgendeine Beschreibung][Bild 1]

![][Bild 1]

Die Höhe und Breite für das Bild können auch vorgegeben werden.

[Bild 1]: /pfad/zum/bild.png "Beschreibung" {width="50px"}

Der Aufruf in Dokument erfolgt mit dem bereits bekannten Befehl

![Irgendeine Beschreibung][Bild 1]

![][Bild 1]

Möglichkeit 2 - Höhe und Breite anpassen

Die Möglichkeit eignet sich besonders, wenn das Markdown-Dokument mit Pandoc in ein PDF konvertiert werden soll.

![Irgendeine Beschreibung](./pfad/zum/bild.png){width="500px"}

Die Größe von Bilder kann angepasst werden. (❗nur gültig für Obsidian❗)

# width = 100; height = 100
 
![Irgendeine Beschreibung|100x100](/pfad/zum/bild.png)

![Irgendeine Beschreibung|1000](/pfad/zum/bild.png)

Möglichkeit 3 - LaTeX

Diese Möglichkeit eignet sich besonders, wenn das Markdown-Dokument mit Pandoc in ein PDF konvertiert werden soll.

\includegraphics[width=0.2\textwidth]{./pfad/zum/bild.png}

Möglichkeit 4 - Verwendung von HTML

Eine flexiblere Möglichkeit Bilder in den Text einzufügen, ist die Verwendung von HTML. Die Option funktioniert nicht zusammen mit Pandoc.

<img src="pfad/zum/bild.png" width="250" height="350" alt="Irgendeine Beschreibung">

Beim referenzieren auf das Bild ist davor kein / zu verwenden!

Möglichkeit 5 - Badges von Shields.io

Badges lassen sich mithilfe des kostenloses Webdienstes shields.io sehr einfach in eine Markdown-Datei einfügen. Es lassen sich statische und dynamische Badges direkt über die offizielle Webpräsenz erstellen.

[![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/donate?hosted_button_id=xxxxxxxxx)

Tastaturtasten und andere Symbole

Mithilfe von HTML und Unicode lassen sich in Markdown sehr einfach Symbole einfügen.

<kbd>Strg</kbd>+<kbd>&#8679;</kbd>
<kbd>Strg</kbd>+<kbd>&#11013;</kbd>
<kbd>Strg</kbd>+<kbd>&#127183;</kbd>
<kbd>Strg</kbd>+<kbd>&#11013;</kbd>
<kbd>Strg</kbd>+<kbd>&#8984;</kbd>

Strg+⇧

Strg+⬅

Strg+🃏

Strg+⌘

Alle verfügbaren Symbole und deren Kodierung ist auf w3schools.com verfügbar

Emojis

Es gibt eine große Zahl an Emojis, die in Markdown-Dokumente eingefügt werden können.

⚠️ ACHTUNG:

:warning: __ACHTUNG:__

😀 😄 🤣 😉

:grinning: :smile: :rofl: :wink:

Auf GitHub finden sich einige gute Emoji-Cheat-Sheets

Für Visual Studio Code gibt es die Erweiterung :emojisense. Beim Einfügen eines : in das Dokument wird ein Dropdown eingeblendet und das entsprechende Emoji kann ausgewählt werden.

Machs farbig

Bring mehr rote Farbe in deinen Text.
Bring mehr blaue Farbe in deinen Text.
Bring mehr grüne Farbe in deinen Text.
Bring mehr gelb Farbe in deinen Text.

Bring mehr <span style="color:red">rote</span> Farbe in deinen Text.  
Bring mehr <span style="color:blue">blaue</span> Farbe in deinen Text.  
Bring mehr <span style="color:green">grüne</span> Farbe in deinen Text.
Bring mehr <span style="color:yellow">gelb</span> Farbe in deinen Text.

Es gibt auch fetten, farbigen Text Rot ist fett in einem normalen Text.

<span style="color:red">**Rot ist fett**</span> in einem normalen Text.

Schriftgröße und -art ändern

Die Maßeinheit em wird im Schriftsatz zur Bestimmung der Zeichenbreite in Abhängigkeit von der Schriftgröße verwendet.
(Quelle: https://de.wikipedia.org/wiki/Em_(Schriftsatz))

Schrift vergrößern

  • 2em Verdoppelt die Schriftgröße
  • 4em vervierfacht die Schriftgröße

Das ist normaler Text, der auf einmal ganz groß wird.

Das ist normaler Text der auf einmal ganz <span style="font-family:Tahoma; font-size:4em;">groß</span> wird.

oder

Das ist normaler Text der auf einmal ganz groß

Das ist normaler Text der auf einmal ganz <font size="6">groß</font>

Text durchstreichen

Dieser Text ist durchgestrichen.

Dieser Text ist durchgestrichen

Dieser Text ist ~~durchgestrichen~~.

# oder 

Dieser Text ist <del>durchgestrichen</del>.

Schrift verkleinern

Das Gleiche geht natürlich auch in die andere Richtung, die Schriftgröße lässt sich verkleinern.

Das ist normaler Text, der auf einmal ganz ganz klein wird.

Das ist normaler Text, der auf einmal ganz <span style="font-family:Tahoma; font-size:0.5em;">ganz klein</span> wird.

oder

Das ist normaler Text, der auf einmal ganz klein wird.

Das ist normaler Text, der auf einmal ganz <font size="0.5">klein</font> wird.

Tabellen

Tabellen lassen sich sehr einfach schreiben. Mit | lassen sich die Spalten und Felder kennzeichnen, mit : definiert man die Textausrichtung.
Wie auch schon bei anderen Sprachen, z.B. LaTeX und HTML, ist das manuelle Erstellen von Tabellen sehr umständlich, Editoren bieten jedoch eine gute Unterstützung.

Spaltenüberschrift 1 Spaltenüberschrift 2 Spaltenüberschrift 3
Inhalt align=left Inhalt align=center Inhalt align=right
Inhalt Inhalt Inhalt
Inhalt Inhalt Inhalt
Inhalt Inhalt Inhalt 
| Spaltenüberschrift 1 | Spaltenüberschrift 2 |  Spaltenüberschrift 3 |  
|:-----------|:-----------:| -----------:| 
| Inhalt align=left  | Inhalt align=center | Inhalt align=right |
| Inhalt | Inhalt | Inhalt |
| Inhalt | Inhalt | Inhalt |
| Inhalt | Inhalt | Inhalt |

Fußnoten

Ein Text mit einer Fußnote.1

Ein Text mit einer Fußnote.[^1]

[^1]: Der Text wird automatisch am Seitenende platziert.

Markdown-to-PDF

Pandoc ist ein freier Parser für Multidokumentenformate. Mit dem Tool lassen sich Dokumente von einem Format in ein andres Dateiformat umwandeln.

Pandoc ist das ultimative Werkzeug 🧰 um Dokumente von einem Format in ein anderes Format zu konvertieren. Auf der Homepage wird es beschrieben als das "swiss-army knife", was es auch wirklich ist.

Es ist vielseitig einsetzbar und lässt sich mithilfe von Skripten, Hooks, etc. sehr flexibel einsetzen.

Pandoc muss für seine Aufgaben nicht zwingend auf dem eigenen Client 💻 installiert werden, sondern kann auch auf einem Server oder gar in einer Docker-Umgebung 🐳 aufgesetzt werden.

Für große, umfangreiche Dokumente 📚, wie wissenschaftliche Arbeiten, Bücher, Dokumentationen, etc. ist Markdown-to-PDF nicht geeignet. Dafür sollte von Anfang an LaTeX genutzt werden, das es einen erheblich größeren Funktionsumfang bietet.

MacOS und Linux

Für das Umwandeln von Markdown-to-PDF werden LaTeX-Pakete benötigt. Die Installation kann bei Linux und MacOS direkt in der CLI mit dem Paketmanager tlmgr erfolgen.

Für MacOS bietet sich aber auch das grafische Tool Tex Live Utility an, das mit Homebrew auf dem eigenen Client installiert werden kann.

brew install --cask tex-live-utility
Tex Live Utility

Windows

In meinem Beitrag 🔗 Typora wird kostenpflichtig! Welche Alternativen gibt es und wie lassen sich Markdown-Dokumente konvertieren? habe ich beschrieben was für Windows benötigt wird.

Einfache PDF-Dokumente erstellen

Das Dokument README.md wird in das PDF-Dokument test.pdf umgewandelt.

pandoc README.md -o test.pdf
  • -o = Ausgabedatei

Einfache Formatierungen

Es lassen sich auf Vorlagen zusammen mit Pandoc verwenden. Damit können Formatierungen für genau definiert werden.

Die Vorlagen greifen dabei auf LaTeX zurück. Eine einfache Vorlage kann so aussehen

% Contents of listings-setup.tex
% Quelle: https://tex.stackexchange.com/questions/97474/how-to-add-lstlistoflistings-to-the-table-of-contents
\usepackage{xcolor}

\lstset{
    basicstyle=\ttfamily,
    numbers=left,
    numberstyle=\footnotesize,
    stepnumber=2,
    numbersep=5pt,
    backgroundcolor=\color{black!10},
    showspaces=false,
    showstringspaces=false,
    showtabs=false,
    tabsize=2,
    captionpos=b,
    breaklines=true,
    breakatwhitespace=true,
    breakautoindent=true,
    linewidth=\textwidth
}

Der Pandoc-Befehl zum Umwandeln lt.

pandoc --listings -H listings-setup.tex --toc -V geometry:"left=1cm, top=1cm, right=1cm, bottom=2cm" -V fontsize=12pt test.md -o test2.pdf

Eisvogel - Ein tolles Template für Markdown-to-PDF

Das Template "Eisvogel" eignet sich sehr gut, um aus Markdown-Dokumenten aufwendigere PDF-Dokumente zu erstellen

Das Template ist in einem beliebigen Pfad abzuspeichern und kann dann über den Pandoc-Befehl aufgerufen werden. Damit lässt sich Eisvogel zentral verwalten und für alle Markdown-Dokumente verwendet werden.

Die Funktionen von Eisvogel sind in der Dokumentation auf GitHub beschreiben und werden zu Beginn in das Dokument zwischen --- eingefügt.

---
title: "Titel"
subtitle: "Sub-titel"

author: ['Stefan Strobel']

date: "Release Date: 2022-10-15"

subject: "Stefan Strobel"

keywords: [strobelstefan.de, Markdown, Pandoc, Eisvogel]

lang: "de"

header-left: "\\hspace{1cm}"
header-center: "\\leftmark"
header-right: ""Seite \\thepage""
footer-left: "Release date: 15.10.2023"
footer-center: "Version: 1.0.0"
footer-right: ""

titlepage: true,
titlepage-text-color: "FFFFFF"
titlepage-rule-color: "360049"
titlepage-rule-height: 0
titlepage-background: "`~/Documents/pictures/bild`{=latex}"
logo: "`~/Documents/eisvogel/pictures/logo`{=latex}"

logo-width: 100mm

toc-own-page: true

code-block-font-size: \normalsize

table-use-row-colors: true
---

# Kapitelüberschrift

...

In diesem Beispiel wird die Datei README.md in ein PDF-Dokument umgewandelt.

pandoc README.md --template ~/Documents/mein-tolles-markdown-dokument/eisvogel --listings --number-sections --pdf-engine=lualatex -V mainfont='JetBrainsMono Nerd Font' -V book --top-level-division=chapter --highlight-style kate -o mein-unfassbar-tolles-pdf-dokument.pdf
  • --template = Das Eisvogel-Template ist im Verzeichnis ~/Documents/mein-tolles-markdown-dokument/eisvogel abgespeichert
  • --top-level-division=chapter = Die Kapitel im PDF-Dokument sind die Überschriften, die im Markdown-Dokument mit einem # gekennzeichnet wurden
  • -V book = Kapitel beginnen auf einer neuen Seite
  • -V mainfont='JetBrainsMono Nerd Font' = Es wird die Schrift JetBrainsMono Nerd Font genutzt

Oft ist es sinnvoll anstatt einem großen Dokument mehrere kleine Markdown-Dokumente zum Schreiben zu verwenden.

Das Konvertieren mehrerer Markdown-Dokumente in ein finales PDF-Dokument stellt keine Herausforderung für Pandoc dar. Es werden einfach alle md-Dokumente der Reihe nach aufgerufen und in einem PDF-Dokument zusammengefasst.

Die Optionen für Eisvogel sind nur in der ersten md-Datei zu definieren, in diesem Beisiel der README.md.

pandoc README.md dokument-01.md dokument-02.md dokument-03.md dokument-04.md dokument-05.md dokument-06.md dokument-07.md --template ~/Documents/mein-tolles-markdown-dokument/eisvogel --listings --number-sections --pdf-engine=lualatex -V mainfont='JetBrainsMono Nerd Font' -V book --top-level-division=chapter --highlight-style kate -o mein-unfassbar-tolles-pdf-dokument.pdf

Pandoc und Unicode

Es gibt aktuelle keine gute Unterstützung von Unicode, was das Ganze ein wenig kniffeliger, aber nicht ganz unlösbar macht. Es lassen sich mit Pandoc alle auf dem Gerät, also auf dem eigenen Client, dem Server oder der Docker-Umgebung, installierten Fonts verwenden. Dazu muss ist im Befehl die Option -V mainfont='' mitzugeben.

Bei MacOS lassen sich die verfügbaren Fonts einfach über die App "Schriftsammlung" abfragen.

Schriftsammlung -App in MacOS

Ein Font, das zumindest eine kleine Anzahl an Emojis unterstütz sind Nerd Fonts.

Wie geht man vor?

  1. Schriftzeichen in der "Schriftsammlung" auswählen
  2. Das Schriftzeichen kopieren und in das Markdown-Dokument einfügen
  3. Konvertierung mit Pandoc starten

Das Vorgehen führt leider nicht immer zum Erfolg. Viele Zeichen werden im fertigen PDF-Dokument kryptisch dargestellt. Dann ist ein anderes Schriftzeichen auszuwählen und auszuprobieren.

Das ist nicht besonders toll, aber immerhin eine Möglichkeit ein paar Zeichen zu verwenden. Wenn jemand eine bessere Lösung gefunden hat, dann bitte unbedingt mitteilen❗

Emojis und Icons lassen sich aber auch jederzeit als Bilddatei in das Dokument einbinden. Das geht zwar nicht so schnell und einfach, ist aber immerhin eine Lösung mit vertretbarem Aufwand.

LaTeX-Vorlagen und mathematische Formeln

Auch Markdown beherrscht mathematische Formeln, die aus TeX entliehen sind.

Vorlagen für LaTeX gibt in meinem Git-Repository auf Codeberg

Hilfreiche Tools

Ein Snippet Manager wie MassCode eignet sich sehr gut, um auf eigene Codeblöcke zuzugreifen.

Für Visual Studio Code gibt es ein Plugin, damit man direkt auf den Snippet Manager zugreifen kann.

Kaffeespende

Du findest meine Vorlage hilfreich, dann kannst du mir gerne einen Kaffee ausgeben. ☕

PayPal 😊 Liberapay 😎 Bitcoin bc1qfuz93hw2fhdvfuxf6mlxlk8zdadvnktppkzqzj 😄

Follow Me

🐘 Mastodon • RSS

  1. Der Text wird automatisch am Seitenende platziert. ↩︎