1. System wielo-plikowej dokumentacji MarkDown * 2. Markdown it! -> HTML * 3. pandoc MD -> HTML * 4. pandoc -> MD

1. System wielo-plikowej dokumentacji MarkDown

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

Założenia:

  1. 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”.
  2. Przeglądarka www z wtyczką interpretującą pliki MarkDown.
    Tu Markdown Viewer.
  3. 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.
  4. 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 “Otó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 - 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 "..." jeśli zawiera spacje.

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

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

.

4. pandoc -> MD

  • Konfiguracja TotalCommander pandoc -> MD - TotalCommnder \ pandoc -> MD