Membuat PDF dari Markdown dengan Pandoc dan LaTeX

mata teras

Pengarang artikel ini Chris Ward menerangkan cara menukar fail markdown ke PDF menggunakan Pandoc dan LaTeX untuk kedai cip permainan papan sumber terbuka mereka. Komponen permainan ditulis menggunakan Markdown, dan laman web permainan juga dihasilkan oleh fail -fail ini.

Pandoc (alat penukaran markup sumber terbuka) dan lateks (sistem pengisytiharan dan susun atur dokumen) digunakan untuk menjana PDF dari fail markdown. Walaupun keupayaan mereka yang kuat, mereka tidak dapat menggabungkan pelbagai PDF ke satu halaman, jadi Ward menggunakan alat perintah PDFJAM untuk memenuhi keperluan ini.

Penulis memberikan panduan terperinci tentang cara memasang kebergantungan yang diperlukan (Markdown, Jekyll, Pandoc, LaTeX, Pdfjam), dan secara beransur -ansur memperkenalkan proses membina, termasuk menjana PDF dari markdown, membuat fail lateks, dan menggunakan pdfjam untuk memindahkan kad untuk memindahkan kad untuk memindahkan kad untuk memindahkan kad untuk memindahkan kad untuk memindahkan kad untuk memindahkan kad untuk memindahkan kad Gabungkan pada satu halaman.

aliran kerja yang ideal penulis adalah untuk menghasilkan fail PDF semasa menjana laman web, dan bukannya apabila pelawat memintanya. Pendekatan ini juga membolehkan versi kad PDF kelihatan berbeza dari halaman HTML tanpa menggunakan peraturan CSS kompleks.

Jika anda telah membaca beberapa catatan saya di SitePoint atau di tempat lain, anda mungkin tahu saya sedang mengerjakan permainan papan. Permainan ini, yang dipanggil Chip Shop, membolehkan anda menjalankan syarikat komputer pada tahun 1980 -an Amerika.

Sebagai sebahagian daripada projek, saya cuba membuka sumber keseluruhan permainan sebanyak mungkin. Selepas beberapa percubaan, saya memutuskan untuk menggunakan Markdown sebagai rangka asas untuk kebanyakan komponen permainan (terutamanya kad dan arahan).

Sejak laman web permainan menggunakan Jekyll, laman web permainan dihasilkan dari fail markdown. Saya akan membuat versi pra-kotak premium dan dicetak sendiri dari permainan, yang saya perlukan untuk menghasilkan PDF dari fail markdown.

Target

aliran kerja yang ideal saya adalah untuk menjana fail PDF semasa menjana laman web, bukan apabila pelawat memintanya. Ini tidak termasuk pilihan wkhtmltopdf yang biasanya saya gunakan untuk generasi PDF, kerana ia menghasilkan PDF dari HTML yang dihasilkan. Sebab lain ialah saya mahu versi kad PDF kelihatan berbeza dari halaman HTML, dan Jekyll tidak mempunyai sebarang fungsi "mod view" untuk mencapai ini tanpa menggunakan peraturan CSS yang kompleks.

Fail templat kad permainan Chip Shop Game mengandungi banyak medan pra-maklumat markdown untuk mekanik permainan, tidak semua bidang digunakan pada setiap kad. Untuk percetakan mudah, saya perlu meletakkan kad pada halaman A4 sebanyak mungkin -dalam kes ini, grid 3 × 3. Akhirnya, halaman perlu dicetak di kedua -dua belah pihak, tetapi saya belum melaksanakannya.

Pandoc dan latex

Mana -mana carian web yang menghasilkan penyelesaian PDF dari Markdown akan membawa anda ke jalan Pandoc. Pandoc adalah alat penukaran tanda pisau Swiss Swiss Tentera Swiss yang menyokong pelbagai format input dan output.

Untuk menjana PDF menggunakan Pandoc, lateks diperlukan. Latex berasal dari komuniti penyelidikan saintifik dan merupakan sistem pengisytiharan dan susun atur dokumen. Digabungkan dengan Pandoc dan LaTeX, kita boleh menggunakan pembolehubah untuk menjana PDF dari satu siri fail markdown dan pra-maklumat sokongan markdown.

Walaupun Pandoc dan Latex yang kuat, saya tidak dapat mencari cara untuk menggabungkan pelbagai PDF (kad) ke satu halaman, terutamanya apabila menggunakan pembolehubah dalam fail markdown. Selepas banyak penyelidikan, saya memilih PDFJam, alat baris arahan mudah untuk keperluan ini.

Memasang Dependencies

Markdown

Anda tidak memerlukan perisian markdown tambahan selain mungkin memerlukan editor, terdapat banyak editor, dan saya cadangkan anda membaca beberapa artikel SitePoint untuk membuat pilihan anda.

Jekyll

Saya akan terus menggunakan Jekyll untuk menggambarkan proses binaan dalam contoh -contoh yang diambil dari permainan saya, tetapi jika anda tidak memerlukan laman web, ia bukan sebahagian daripada generasi PDF yang diperlukan.

Pandoc

Pada Mac saya, saya memasang Pandoc menggunakan homebrew, tetapi semua sistem operasi mempunyai pilihan yang sepadan.

LaTeX

Terdapat banyak perkataan mengenai cara terbaik untuk memasang lateks, bergantung kepada keperluan anda atau bagaimana anda berhasrat menggunakannya. Pemasangan penuh alat dan perpustakaannya mungkin hampir dengan 2GB, tetapi untuk kebanyakan tujuan pemasangan minimum adalah mencukupi. Baca halaman muat turun projek untuk mencari pilihan yang paling sesuai untuk anda.

Dalam tutorial ini, kami akan menggunakan enjin Xelatex kerana saya menggunakan fon tersuai. Walau bagaimanapun, anda boleh memilih mana -mana enjin yang menyediakan ciri -ciri khusus yang anda perlukan.

pdfjam

Bergantung pada cara anda memasang lateks, anda mungkin memasang pdfjam. (Jenis pdfjam yang mana di terminal untuk memeriksa.) Jika anda tidak memasangnya, cari butiran pemasangan di sini.

Proses bangunan

Selepas beberapa pertimbangan, saya menjalankan skrip bash yang berjalan secara tempatan nampaknya menjadi pilihan terbaik pada masa ini. Terdapat cara yang lebih baik, tetapi ia berfungsi, dan saya dapat memperbaiki proses kemudian, memindahkannya ke sistem integrasi berterusan atau cangkuk git.

Lihat skrip bash pada GitHub.

mari memperkenalkan langkah skrip ini dengan langkah sekarang.

Tetapan

<code class="language-bash">bundle install
bundle update

rm -dfr _site
rm -dfr pod</code>

Perintah ini memastikan bahawa kebergantungan ruby ​​yang diperlukan oleh Jekyll untuk membina laman web adalah terkini, dan kami memadamkan mana -mana laman web dan folder cetak yang sedia ada.

Bina laman web

<code class="language-bash">jekyll build
mkdir -p pod/pdf/cards</code>

Seterusnya, kami membina laman web dan membuat folder untuk versi cetak kad.

menjana pdf dari markdown

mari buat folder yang mengandungi setiap versi markdown versi pdf:

<code class="language-bash">for filename in _cards/*.md; do
  echo $filename
  pandoc --from=markdown+yaml_metadata_block --template _layouts/cards.latex -o pod/pdf/cards/"$(basename "$filename" .md)".pdf --latex-engine=xelatex $filename
done</code>

Skrip ini mengendalikan setiap fail markdown dalam direktori _cards, pastikan untuk memerhatikan medan pra-maklumat markdown. Menggunakan templat kad.LATEX (yang akan kami sampaikan kemudian), enjin lateks yang betul mengeluarkan PDF dengan nama yang sesuai.

fail lateks

Kebanyakan sihir menjana fail kad dari Pandoc berlaku dalam templat lateks.

Lihat templat lateks pada github.

lateks baru kepada saya, tetapi ia tidak terlalu rumit. Saya akan menerangkan apa yang saya ubah dari fail lateks lalai (terletak di Pandoc_install_dir/data/templat/default.latex) untuk mendapatkan kad berfungsi dengan betul. Saya cadangkan ShareLateX.com untuk pratonton mereka semasa mengedit fail lateks.

<code class="language-bash">bundle install
bundle update

rm -dfr _site
rm -dfr pod</code>

Kami memerlukan saiz halaman tertentu dan kami akan menggunakan lajur untuk menunjukkan kos dan skor kad kemudian. Kami menggunakan grafik dan fon tersuai, jadi kami memerlukan pakej ini.

Kami cuba membuat susun atur yang jelas dan ringkas. Inilah cara kami melaksanakannya:

<code class="language-bash">jekyll build
mkdir -p pod/pdf/cards</code>

Saya fikir banyak perkara di atas agak mudah difahami untuk sesiapa yang digunakan untuk kod atau penandaan. Kami mencipta unsur -unsur kad, menjajarkannya, menetapkan saiz fon dan memeriksa jika terdapat nilai, dan kemudian mengeluarkannya supaya kad itu tidak berakhir dengan medan kosong.

kami mengubah saiz imej ke saiz tertentu dan memusatkannya. Nilai kos dan skor disusun dalam dua lajur, ditetapkan menggunakan perintah permulaan {tabular}, dan bilangan lajur ditetapkan menggunakan bilangan l.

menggabungkan kad pada satu halaman

kami menggunakan pdfjam untuk membuat fail pdf besar dengan setiap kad PDF individu:

<code class="language-bash">for filename in _cards/*.md; do
  echo $filename
  pandoc --from=markdown+yaml_metadata_block --template _layouts/cards.latex -o pod/pdf/cards/"$(basename "$filename" .md)".pdf --latex-engine=xelatex $filename
done</code>

Gunakan arahan ini, kami menentukan yang berikut:

orientasi halaman harus selalu menegak
setiap pdf individu harus dibingkai
saiz grid
Suffix Nama Fail
Nama fail

pdfjam boleh memberikan ralat jika anda tidak mengeluarkan ke direktori kerja, jadi saya memindahkan fail ke tempat yang saya mahukan (mudah -mudahan ia akan diselesaikan pada masa akan datang). Di sini kita juga boleh memadam satu fail PDF jika kita tidak memerlukannya.

Itu sahaja - kami mempunyai PDF laman web dan kad permainan yang boleh dicetak.

Jalankan skrip

Saya menggunakan

untuk menjalankan skrip binaan. Oleh kerana terdapat banyak imej dan pemprosesan PDF, ia mengambil masa kira -kira lima hingga sepuluh minit. Kemudian saya mempunyai skrip berasingan untuk menggunakan folder ini ke pelayan web.

./build.sh

Langkah seterusnya

Proses ini membawa saya sedikit masa untuk mendapatkannya dengan betul, tetapi cukup baik sekarang untuk terus memperbaiki proses dan susun atur selepas ujian permainan.

Saya harap anda dapati penyelidikan dan eksperimen saya berguna untuk projek anda. Sekiranya anda mempunyai komen atau cadangan, sila beritahu saya.

FAQs (FAQs) tentang membuat PDF dari Markdown menggunakan Pandoc dan LaTeX

bagaimana memasang pandoc dan lateks pada sistem saya?

Untuk memasang Pandoc, anda boleh menggunakannya dari laman web rasmi (

https://www.php.cn/link/8f1dd6e7a88b9cf615c146330c591ba9

.

Bolehkah saya menyesuaikan penampilan PDF yang dibuat menggunakan pandoc dan lateks?

Ya, anda boleh menggunakan templat lateks untuk menyesuaikan penampilan PDF. Pandoc menggunakan templat lalai untuk menjana PDF, tetapi anda boleh menentukan templat anda sendiri menggunakan pilihan --template. Anda boleh membuat templat anda sendiri atau menggunakan salah satu daripada banyak templat yang terdapat dalam talian, seperti yang terdapat di Repositori GitHub Template Wandmalfarbe Pandoc.

Bagaimana untuk menukar fail markdown ke PDF menggunakan pandoc dan lateks?

3 Ganti

dengan nama fail markdown anda dan pandoc yourfile.md -o yourfile.pdf dengan nama yang dikehendaki dari fail pdf anda. Perintah ini memberitahu Pandoc untuk menukar fail markdown ke PDF menggunakan templat lateks lalai. yourfile.md yourfile.pdf (seluruh kandungan FAQ adalah sama dengan teks asal, ditinggalkan di sini untuk mengelakkan pertindihan)

Atas ialah kandungan terperinci Membuat PDF dari Markdown dengan Pandoc dan LaTeX. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!