MarkDown - zastosowania

+ 07.03.2025
1. System wielo-plikowej dokumentacji MarkDown * 2. Markdown it! -> HTML *
3. pandoc MD -> HTML * 4. pandoc -> MD * 5. PowerToys -> MD *
6. MD-ściągawka

1. System wielo-plikowej dokumentacji MarkDown

Przykład systemu dokumentacji tworzonej w polikach lokalnych MarkDown z ilustracjami i wzajemnie linkowanymi plikami.

Założenia:

Edytor tekstowy, który ułatwia otwieranie plików wspomnianych w tekście.
Tu Notepad++ (N++), który po zaznaczeniu w tekście ścieżki/nazwy ma opcję p.kl.myszy: “Otwórz plik”. N++ z opcjonalnie zainstalowaną wtyczką “MarkdownPanel”.
Przeglądarka www z wtyczką interpretującą pliki MarkDown.
Tu Markdown Viewer .
Składnia w bloku kodu jest kolorowana z pomocą https://prismjs.com/. Dostępnych jest wiele języków programowania. Łatwo też można korygować kolory, dodając w pliku *.md np.
```
<style> .token.variable { color: #905; } pre {line-height: 1.2 !important;} </style>
```
Dodatkowo warto mieć w przeglądarce wtyczkę, która generuje MarkDown na podstawie zaznaczonego fragmentu strony www (w tym zaznaczenia fragmentu przetłumaczonego).
Tu MarkDownload.
Po zakończonym okresie częstego edytowania dokumentacji można wyeksportować wszystkie “.md” do “.html” (skrypt?) i linkujące się dokumenty będą działały w przeglądarkach www bez zainstalowanych wtyczek MarkDown.

Tak jak obrazy ![]() tak i pliki linkowane ➔📎 [** **]( ) wstawiam ze ścieżkami względnymi w takiej składni:

➔📎 [**./inny_plik.md**](./inny_plik.md ) 

co dla HTML daje link:

➔📎 ./inny_plik.md

Po jego kliknięciu w przeglądarce www, gdy był oglądany (i interpretowany) w niej aktualny plik “*.md” otwierany jest “./inny_plik.md” i od razu interpretowany przez wtyczkę “Markdown Viewer”.

Działając natomiast w pliku “*.md” w N++ zaznaczam ścieżkę do pliku, p.kl.myszy “Otwórz plik”.

Najwygodniej jest, gdy nazwy są bez spacji. Inaczej trzeba je zamienić w linku na %20:

➔📎 [**./kolejny plik.md**](./kolejny%20plik.md )

a w N++ zaznaczać ścieżkę z lewej strony - tu: ./kolejny plik.md. Spacja przy końcowym nawiasie ␣) nie przeszkadza w interpretacji linku, a jest pomocna podczas zamieniania wcześniejszych na %20.

W ten sposób można dołączać też inne pliki, np. tekstowe, czy takie jak PDF, które w edytorze tekstowym się nie otworzą, ale nieźle zadziałają w przeglądarce.

Moja konfiguracja wtyczek MarkDown

Obie wtyczki wymagają zezwolenia na pracę z plikami lokalnymi (Advanced opt./Szczegóły - File Access) - co jest opisane w ich instrukcjach.

Markdown Viewer:

Włączyłem sobie dodatkowo -> opcje COMPILER (po kliknięciu w ikonę wtyczki):

attr (Custom attributes using {}),
sub (~a~),
sup (^a^),
tasklists (- [x])

MarkDownload

Po kliknięciu w ikonę wtyczki mamy ⚙️ w prawym górnym rogu. Można zapisać swoje ustwienia i porównać z moimi:

MarkDownload-export-AK.json
. . .

{
  "headingStyle": "atx",
  "hr": "---",
  "bulletListMarker": "*",
  "codeBlockStyle": "fenced",
  "fence": "```",
  "emDelimiter": "_",
  "strongDelimiter": "**",
  "linkStyle": "inlined",
  "linkReferenceStyle": "full",
  "imageStyle": "markdown",
  "imageRefStyle": "inlined",
  "frontmatter": "---\ncreated: {date:YYYY-MM-DD HH:mm:ss} (UTC {date:Z})\ntags: [{keywords}]\nsource: {baseURI}\nauthor: {byline}\n---\n\n# {pageTitle}\n\n> ## Excerpt\n> {excerpt}\n\n---",
  "backmatter": "",
  "title": "{pageTitle}",
  "includeTemplate": false,
  "saveAs": true,
  "downloadImages": true,
  "imagePrefix": "img/",
  "mdClipsFolder": "MarkDownload/{pageTitle}",
  "disallowedChars": "[]#^",
  "downloadMode": "downloadsApi",
  "turndownEscape": true,
  "contextMenus": true,
  "obsidianIntegration": false,
  "obsidianVault": "",
  "obsidianFolder": ""
}

2. Markdown it! -> HTML

Po zainstalowaniu Markdown it! dla node.js można konwertować MD -> HTML za pomocą skryptu, wypakowanego z md-it.cmd.zip

W początkowej części skryptu jest nagłówek HTML, gdzie znaki < > + są (w skrypcie) poprzedzone znakiem ^. Tekst nagłówka można sobie zmieniać dla swoich potrzeb.

Parametrem skryptu jest nazwa pliku MD, w otoczona cudzysłowem "..." jeśli zawiera spacje.

Plik markdown-viewer2.css, który jest używany w skrypcie to styl skopiowany z wtyczki “Markdown Viewer” dla Edge

Uwaga: w paczkach md-it.cmd.zip i markdown-v.head.html.zip przed 2025-02-20 był błąd wielkości czcionki dla h3 - było 1.4px, a powinno być 1.4em.

3. pandoc MD -> HTML

Wypakuj plik markdown-v.head.html.zip do foldera %appdata%\pandoc\
Jest to styl skopiowany z wtyczki “Markdown Viewer” dla Edge, który będzie wklejany do nagłówka HTML.

Wszytko z MD w pojedynczym pliku HTML (łacznie z obrazami):

pandoc -i FROM.md -o 1_(__TO__).html --embed-resources -H %appdata%\pandoc\markdown-v.head.html -M lang=pl

HTML z obrazami na zewnątrz (ale markdown-v.head.html jest wklejone do wynikowego pliku):

pandoc -i FROM.md -o (__TO__).html --standalone -H %appdata%\pandoc\markdown-v.head.html -M lang=pl

Wskazówka: jeśli chcemy uzyskać w tabelach automatyczne ustawianie szerokości kolumn to w pliku *.md można wstawić:
<style> body > table > colgroup > col {width: unset!important;}</style>

4. pandoc -> MD

Konfiguracja TotalCommander pandoc -> MD - TotalCommnder \ pandoc -> MD
Skrypt pipetable_align.py spakowany w pipetable_align.zip wyrównuje spacjami pionowe | po konwersji do Markdown w pandoc.
Skrypt można zapisać w folderze %appdata%\pandoc\ i dodać menu w TotalCommander:
cmd=cmd param=/k %%AppData%%/pandoc/pipetable_align.py %N

5. PowerToys -> MD

W PowerToys - narzędzie “Wklejanie zaawansowane” (“Advanced Paste”) [ ⊞ Win + ⇧ Shift + V ] pozwala m.in. na przekonwertowanie zawartości schowka na tekst markdown.

6. MD-ściągawka

To nie jest przegląd reguł - tylko wybrane przypominajki.

Przy korzystaniu z list warto kolejne wiersze punktu wcinać na tyle spacji ile jest do pierwszego znaku nie-spacji w punkcie, bo to jest pozycja od której liczą się dalsze wcięcia np. dla pod-listy czy bloku kodu. Można to wykorzystać także do oddzielania punktów wierszami z pustymi spacjami - tu spacje są oznaczone jako “∙”:
```
∙1.∙abc
∙∙∙∙
∙2.∙def
∙∙∙∙
∙∙∙∙∙∙∙∙blok kodu w p.2. (4 spacje wiodące)
∙∙∙∙∙∙*∙podpunkt w p.2. (ma 2 spacje wiodące)
∙∙∙∙
∙3.∙ghi∙∙
∙∙∙∙złamany wiersz w p.3.
```
W listach obowiązuje też zasada ręcznego łamania wiersza,
np. 2 spacje na końcu.

Zwinięty tekst:

<details markdown=1><summary markdown="span">Rozwiń . . . </summary>
Zwinięty tekst
</details>

Rozwiń . . .

Zwinięty tekst

Kotwica:
```
Kotwica:
<span id="anchorName"></span>
Odnośnik:
[Idź do...](#anchorName)
```
Podobno lepiej name= niż id=, bo dla id są generowane zmienne globalne javascript, ale jakoś to u mnie nie działa.

Idź do…-test

Basic writing and formatting syntax - GitHub »