Przenoszenie dokumentacji¶

Instalacja narzędzia Pandoc¶

Najpierw instalujemy manager pakietów Scoop. W tym celu w wykonujemy polecenie PowerShell:

iex (new-object net.webclient).downloadstring('https://get.scoop.sh')

Następnie kończymy instalację pandoc za pomocą polecenia:

scoop install pandoc

Konwersja dokumentacji do formatu markdown¶

Dokumenty z GoogleDrive¶

Dokumenty GoogleDrive powinny być pisane wg następujących wytycznych:

w pierwszej linii powinien być tytuł, a następnie rozdziały wg styli nagłówkowych od nagłówka 1 wgłąb,
należy usunąć spis treści z dokumentu

Aby skonwertować dokument z google drive do formatu markdown należy go najpierw pobrać w formacje .docx.

Następnie wykonać polecenie:

pandoc -f docx -t commonmark "<ścieżka do pliku .docx>" -o <Plik-wynikowy.md> --shift-heading-level-by=1 --wrap preserve

Jeśli dokument zawiera obrazki to należy dodać jeszcze flagę

--extract-media=<Nazwa folderu, w którym trzymane będą obrazki>

Ważne jest żeby przy generowaniu pliku dobrze dobrać docelowy folder z obrazkami ponieważ jego ścieżka pojawi się wielokrotnie w generowanym pliku .md.

Artykuły z Wiki¶

Aby skonwertować artykuł z wiki.sente.pl należy skopiować jego treść za pomocą opcji “Edytuj dokument” i zapisać w pliku tekstowym.

Następnie wykonać polecenie:

pandoc -f dokuwiki -t markdown 
<Nazwa-pliku-z-treścią-artykułu> -o <Plik-wynikowy.md>

Alternatywnie można pobrać i od razu skonwertować artykuł za pomocą jednego polecenia

curl -H "X-DokuWiki-Do:export_raw" -u <użytkownik>:<hasło> 
"<adres-http-do-artykułu>" | pandoc -f dokuwiki -t markdown 
-o <Plik-wynikowy.md>

Dodawanie plików do dokumentacji¶

Wygenerowane wcześniej pliki .md należy jeszcze podzielić na odpowiednie rozdziały. Żeby pliki .md były widoczne w dokumentacji należy przenieść je w odpowiednie miejsce w lokalizacji .\docs\src\ a następnie do pliku foliant.yml w sekcji - chapters dodać wpisy ze ścieżkami do tych plików.