MarkDown - zastosowania

+ 07.03.2025 + 05.08.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:

Uwaga! Aby zezwolić na auto-konwersję plików lokalnych Markdown trzeba włączyć ustawienia w nieco magicznej sekwencji (tu przykładowa sekwencja dla FF/Win):

ADVANCED OPTIONS (po kliknięciu na ikonę m)
File Access ALLOW ACCESS
Site Access ALLOW ALL
Po tym przy File Access pojawia się REFRESH i po kliknięciu mamy okazję w wyskakującym okienku zezwolić na dostęp.

Włączyłem sobie dodatkowo -> opcje COMPILER (po kliknięciu w ikonę wtyczki) MARKDOWN-IT
oprócz domyślnie zaznaczonych html, linkify:

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

A linkify zwykle odznaczam, bo linkuje również m.in., a przecież zawsze poprawnie działają linki w <...>
Warto też przeglądnąć opcje CONTENT i ich przykłady.

Opis na stronie https://github.com/arve0/markdown-it-attrs dotyczący atrybutów wpisanych w {...} jest prawie zgodny z działaniem w tej wtyczce, choć w przypadku tabeli nie zawsze to się zgadza. Problemem są m.in. atrybuty zadawane w ostatniej komórce wiersza i nie udaje się scalanie komórek (wersja Markdown Viewer z 23.05.2024). Częściowo udaje się to obejść - zob. źródłowy plik

md_it_attr.md .

MarkDownload

Po kliknięciu w ikonę wtyczki mamy ⚙️ w prawym górnym rogu. Można zapisać swoje ustawienia 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_CLI.zip
Skrypt działa podobnie do wtyczki “Markdown Viewer” - z możliwością wyboru opcji i dodatków.

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

Więcej informacji i dokładna instrukcja jest w md-it_CLI.zip\doc\md-it_Readme.md.

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.

Jeśli potrzebujemy własnego znakowania punktów zagnieżdżonych list można użyć stylu, np.:
```
<style> 
  :root ol ol {list-style-type: lower-alpha;}
  :root ol ol ol {list-style-type: lower-roman;}
</style>
```
, z tym, że w źródłowym MD należy nadal w zagnieżdżonych listach używać 1. 2. 3. …

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

We wtyczce “Markdown Viewer” nie działa kod zdefiniowany w bloku <script>

… to znaczy prawie nie działa, bo blok <script> jest dołączany do HTML, tylko nie jest wykonywany. Ale gdy się wynikowy HTML zapisze jako plik, to <script> działa.

Natomiast jest wykonywany kod javascript inicjowany ręcznie po załadowaniu strony, np.:

<label style="border:1px solid aqua; padding:2px 6px;" title="Pokaż spis treści">
<input type="checkbox" 
  onchange="document.querySelector('#toc').style.display=this.checked ? 'block' : 'none';
  if (this.checked) {
    //może być wiele wierszy, tylko nie może być wiersza pustego, ani `"`.
  };"
>
 📑 Pokazuj spis treści </label>
    
<div id="toc" style="display:none;"> ... </div>

Basic writing and formatting syntax - GitHub »