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:
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) 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.
, natomiast działają linki w <...>
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
.
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 wpipetable_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 dlaid
są generowane zmienne globalne javascript, ale jakoś to u mnie nie działa. -
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>