Hotové řešení markdown2pdf se zdrojovým kódem pro Linux

Úvod

Markdown je skvělý způsob, jak napsat krátký článek, a někdy i poměrně obsáhlý text, s jednoduchým formátováním ve formě italiky a tučného písma. Také je Markdown vhodný pro psaní článků s začleněním zdrojového kódu. Ale někdy je třeba převést ho do obyčejného, dobře formátovaného PDF souboru, a aby nedošlo k problémům při konverzi, které jsem například zažil — nelze psát česky v komentářích zdrojového kódu, příliš dlouhé řádky se nepřesouvají, ale jsou ořezány, a další drobné problémy. Tento návod umožní rychle nastavit konvertor. md2pdf aniž bychom se příliš zabývali tím, jak to funguje. Skript pro víceméně automatickou instalaci je níže ve správné sekci.

Můj příklad TeX šablony pro konverzi používá balíček písem PSCyr, který zahrnuje podporu Microsoft písem, a to konkrétně Times New Roman. Takové požadavky na diplom podle normy byly. Pokud umíte, můžete šablonu upravit podle svých potřeb. V mém návodu bude nejprve zapotřebí se zabývat nastavením PSCyr v TexLive. Nastavení se provádí v distribuci Linux Mint Mate, pro jiné distribuce možná bude potřeba vyhledat standardní složky balíku TexLive pro váš systém.

Instalace TexLive

Samozřejmě, že lze nainstalovat jen potřebné části tohoto balíku. Ale osobně se mi otevřeně nechtělo hledat minimálně nutnou pracovní instalaci. Aby vše správně fungovalo, nainstalujeme celý balík TexLive. Jmenuje se texlive-full a váží něco málo přes 2 gigabyty, mějte tento fakt na paměti. Spustíme příkaz:

user@hostname:~$ sudo apt install texlive-full -y

Po poměrně dlouhé instalaci můžeme přejít k dalšímu bodu.

Instalace konvertoru Pandoc

Pandoc je balíček pro Linux, který umožňuje převádět některé textové formáty na jiné. Má mnoho zajímavých možností, se kterými se můžete seznámit sami na internetu. Nás ale zajímá pouze možnost převodu markdown souboru do PDF. Zkontrolujeme, zda je Pandoc nainstalován, a pokud ne, tak ho nainstalujeme. Například takto:

user@hostname:~$ dpkg -s pandoc

Pokud je v výstupu napsáno, že není nainstalován — instalujeme:

user@hostname:~$ sudo apt install pandoc -y

Instalace balíčku PSCyr pro TexLive

Nejprve je potřeba stáhnout PSCyr. Prozatím je stále dostupný na této odkazu, pokud není článek k mání z nějakého důvodu, nevěšte hlavu, není těžké ho najít spolu s instrukcí k instalaci, když do Googlu zadáte něco jako „Instalace PsCyr texlive“. Pokud je dostupný, je to pro vás jednodušší, stáhněte si ho a budeme předpokládat, že jste rozbalili archiv do domácí složky, a tak cesta k složce obsažené v archivu vypadá jako ~/PSCyr. Pak otevřeme Terminál a postupně provedeme tyto příkazy:

user@hostname:~$ cd
user@hostname:~$ mkdir ./PSCyr/fonts/map ./PSCyr/fonts/enc
user@hostname:~$ cp ./PSCyr/dvips/pscyr/*.map ./PSCyr/fonts/map/
user@hostname:~$ cp ./PSCyr/dvips/pscyr/*.enc ./PSCyr/fonts/enc/
user@hostname:~$ echo "fadr6t AdvertisementPSCyr "T2AEncoding ReEncodeFont"" > ./PSCyr/fonts/map/pscyr.map

Dále zjistíme, kde se nachází lokální adresář texmf. Provedeme příkaz:

user@hostname:~$ kpsewhich -expand-var='$TEXMFLOCAL'

Pravděpodobně je tento adresář u vás — /usr/local/share/texmf/, a pak provedeme:

user@hostname:~$ sudo cp -R ./PSCyr/* /usr/local/share/texmf/

Nebo se nemusíte trápit a můžete provést příkaz, který zkopíruje do složky texmf kdekoliv to bylo:

user@hostname:~$ sudo cp -R ./PSCyr/* $(kpsewhich -expand-var='$TEXMFLOCAL')

Písma PSCyr jsou nainstalována, připojujeme v TexLive:

user@hostname:~$ sudo texhash
user@hostname:~$ updmap --enable Map=pscyr.map
user@hostname:~$ sudo mktexlsr

LaTeX šablona pro konverzi md2pdf

Nebudu popisovat, jak přesně je tato šablona nastavena, jednoduše ji uvedu pod spoilerem bez zvláštních vysvětlení. Stačí říct, že je nastavena docela dobře, alespoň zpracovává texty s množstvím zdrojového kódu. Pokud vám nevyhovují velikosti odsazení, meziřádkové intervaly, absence číslování sekcí a podsekcí, tak si myslím, že je dost snadné to vygooglit dotazem na internetu „jak v Latex udělat…“ a pokračujte podle vaší potřeby. Pokud je to zcela nejasné, napište do komentářů, pokusím se zabývat vlastními nastaveními před čtyřmi lety a napsat, která část šablony za co odpovídá. Mezitím zapíšu, jak jsem to udělal já na svém PC, a vy máte právo to zopakovat nebo modifikovat podle sebe.

Vytvořte soubor template.tex ve složce /usr/share/texlive/:

user@hostname:~$ sudo touch /usr/share/texlive/template.tex

Nastavíme mu práva pro čtení:

user@hostname:~$ sudo chmod 444 /usr/share/texlive/template.tex

otevřeme jako root a vložíme do něj obsah skrytý pod spoilerem níže:

user@hostname:~$ sudo nano /usr/share/texlive/template.tex

Obsah šablony /usr/share/texlive/template.tex

documentclass[oneside,final,14pt]{extreport}
usepackage{extsizes}
usepackage{pscyr}
renewcommand{rmdefault}{ftm}
usepackage[T2A]{fontenc}
usepackage[utf8]{inputenc}
usepackage{amsmath}
usepackage{mathtext}
usepackage{multirow}
usepackage{listings}
usepackage{ucs}
usepackage{hhline}
usepackage{tabularx}
usepackage{booktabs}
usepackage{longtable}
usepackage{titlesec}
usepackage{hyperref}
usepackage{graphicx}
usepackage{setspace}
usepackage[center,it,labelsep=period]{caption}
usepackage[czech,russian,ukrainian]{babel}
usepackage{vmargin}
newcommand{specialcell}[2][c]{%
    begin{tabular}[#1]{@{}c@{}}#2end{tabular}}
setpapersize{A4}
setmarginsrb {1cm}{1cm}{1cm}{1cm}{0pt}{0mm}{0pt}{13mm}
usepackage{indentfirst}
setlengthparindent{1cm}
renewcommand{baselinestretch}{1}
renewcommandthechapter{}
renewcommandthesection{}
renewcommandthesubsection{}
renewcommandthesubsubsection{}
titleformat
{chapter} % command
{bfseriesnormalsizecentering} % format
{thechapter} % label
{0.5ex} % sep
{
    centering
}
[
vspace{-1.5ex}
] % after-code
titleformat
{section}
[block]
{normalfontbfseries}
{thesection}{0.5em}{}
sloppy
letoldenumerateenumerate
renewcommand{enumerate}{
  oldenumerate
  setlength{itemsep}{1pt}
  setlength{parskip}{0pt}
  setlength{parsep}{0pt}
}
letolditemizeitemize
renewcommand{itemize}{
  olditemize
  setlength{itemsep}{1pt}
  setlength{parskip}{0pt}
  setlength{parsep}{0pt}
}
providecommand{tightlist}{%
  setlength{itemsep}{0pt}setlength{parskip}{0pt}}

titlespacing{subsubsection}{parindent}{3mm}{3mm}
titlespacing{subsection}{parindent}{3mm}{3mm}
usepackage{color}

lstset{
    basicstyle=footnotesizettfamily,
    inputencoding=utf8,
    extendedchars=true,
    showspaces=false,
    keepspaces=true
    showstringspaces=false,
    showtabs=false,
    tabsize=4,
    captionpos=b,
    breaklines=true,
    breakatwhitespace=true,
    breakautoindent=true,
    linewidth=textwidth
}

begin{document}
$if(title)$
maketitle
$endif$
$if(abstract)$
begin{abstract}
$abstract$
end{abstract}
$endif$

$for(include-before)$
$include-before$

$endfor$
$if(toc)$
{
$if(colorlinks)$
hypersetup{linkcolor=$if(toccolor)$$toccolor$$else$black$endif$}
$endif$
setcounter{tocdepth}{$toc-depth$}
tableofcontents
}
$endif$
$if(lot)$
listoftables
$endif$
$if(lof)$
listoffigures
$endif$
$body$

$if(natbib)$
$if(bibliography)$
$if(biblio-title)$
$if(book-class)$
renewcommandbibname{$biblio-title$}
$else$
renewcommandrefname{$biblio-title$}
$endif$
$endif$
bibliography{$for(bibliography)$$bibliography$$sep$,$endfor$}

$endif$
$endif$
$if(biblatex)$
printbibliography$if(biblio-title)$[title=$biblio-title$]$endif$

$endif$
$for(include-after)$
$include-after$

$endfor
end{document}

Uložíme soubor /usr/share/texlive/template.tex a napíšeme skript, který převede soubor Markdown do PDF, vytvářející ve stejné složce soubor s názvem Markdown souboru s příponou .pdf, tedy po převodu filename.md ve složce se objeví filename.md.pdf. Skript nazveme md2pdf a umístíme na cestu /usr/bin. Provedeme po sobě jdoucí příkazy:

user@hostname:~$ cd
user@hostname:~$ touch md2pdf
user@hostname:~$ echo "#!\/bin\/bash" > md2pdf
user@hostname:~$ echo "pandoc --output=$1.pdf --from=markdown_github --latex-engine=pdflatex --listings --template=\/usr\/share\/texlive\/template.tex $1" >> md2pdf
user@hostname:~$ sudo cp md2pdf \/usr\/bin\/
user@hostname:~$ sudo chmod 111 \/usr\/bin\/md2pdf

Ve 4. řádku je uveden příkaz pro převod. Všimněte si —from=markdown_githubGitHub verze Markdown je zpětně kompatibilní s původním Markdown, takže pokud je váš text napsán v něm, nemusíte mít obavy. Pokud je váš MD soubor napsán ve specifickém dialektu Markdown, přečtěte si manuál na Pandoc (man pandoc), ujistěte se, že vaše implementace je podporována, a upravte /usr/bin/md2pdf pokud je to nutné.

Skript pro více méně automatickou instalaci

Pokud nechcete nic moc nastavovat a máte distribuci podobnou Ubuntu, můžete zkusit vytvořit skript s obsahem skrytým pod spoilerem, a pravděpodobně se vše nainstaluje samo, jedině musíte sami zkopírovat TeX šablonu, vyloženou výše pod spoilerem. Otevřete Terminál a proveďte:

user@hostname:~$ cd
user@hostname:~$ touch installmd2pdf.sh

Dále jej vyplňte tímto obsahem:

Obsah skriptu $HOME/installmd2pdf.sh

#!/bin/bash
cd /tmp
sudo apt install texlive-full pandoc -y
wget http://blog.harrix.org/wp-content/uploads/2013/02/PSCyr.zip
unzip -qq PSCyr.zip
cd
mkdir ./PSCyr/fonts/map ./PSCyr/fonts/enc
cp ./PSCyr/dvips/pscyr/*.map ./PSCyr/fonts/map/
cp ./PSCyr/dvips/pscyr/*.enc ./PSCyr/fonts/enc/
echo "fadr6t AdvertisementPSCyr "T2AEncoding ReEncodeFont"" > ./PSCyr/fonts/map/pscyr.map
sudo cp -R ./PSCyr/* $(kpsewhich -expand-var='$TEXMFLOCAL')
sudo texhash
updmap --enable Map=pscyr.map
sudo mktexlsr
sudo touch /usr/share/texlive/template.tex
touch md2pdf
echo "#!/bin/bash" > md2pdf
echo "pandoc --output=$1.pdf --from=markdown_github --latex-engine=pdflatex --listings --template=/usr/share/texlive/template.tex $1" >> md2pdf
sudo cp md2pdf /usr/bin/
sudo chmod 111 /usr/bin/md2pdf

Spusťte ho pomocí příkazu:

user@hostname:~$ sudo bash $HOME/installmd2pdf.sh

Nezapomeňte, že /usr/share/texlive/template.tex musíte vyplnit uvedeným obsahem v sekci "LaTeX šablona pro konverzi md2pdf".

Použití md2pdf

Jednoduše otevřete složku s Markdown souborem (some_file.md) v Terminálu a proveďte příkaz:

user@hostname:~$ md2pdf some_file.md

Výsledkem bude soubor v složce some_file.md.pdf.

Závěr

Na základě popsané metody lze vytvořit jakýkoliv styl PDF souborů, lze také konvertovat jiné formáty než md, všechny podporované Pandoc. Doufám, že jednou tato instrukce bude užitečná pro 3 a půl lidí.

Zdroj: habr.com