Penukar README kepada PDF

Fail README.md ialah dokumen Markdown yang menerangkan projek, repositori, pakej, aplikasi, dataset atau aliran kerja.

Fail README biasanya termasuk:

• tajuk projek dan ringkasan;
• arahan pemasangan;
• contoh penggunaan;
• keratan baris arahan;
• contoh konfigurasi;
• senarai ciri;
• senarai tugasan;
• jadual;
• tangkapan skrin;
• lencana;
• arahan sumbangan;
• maklumat lesen atau sokongan;
• pautan ke dokumentasi dan rilis.

Sambungan .md bermakna fail tersebut ditulis dalam Markdown. Menukarnya kepada PDF mencipta dokumen tetap sambil mengekalkan sumber Markdown sebagai versi yang boleh diedit.

PDF berguna apabila README perlu meninggalkan repositori asalnya atau disemak sebagai dokumen berasaskan halaman.

Sebab biasa termasuk:

• berkongsi dokumentasi projek dengan pelanggan atau pihak berkepentingan;
• melampirkan gambaran keseluruhan teknikal pada e-mel atau tiket;
• menyerahkan dokumentasi untuk disemak atau diluluskan;
• mencipta snapshot luar talian bagi repositori pada titik masa tertentu;
• mencetak arahan persediaan atau runbook operasi;
• mengarkibkan dokumentasi rilis;
• mengedarkan README kepada pembaca yang tidak menggunakan GitHub;
• menyemak kod panjang, persamaan, gambar rajah dan jadual dalam susun atur tetap.

README asal harus tetap menjadi sumber yang boleh diselenggara. Jana semula PDF selepas README berubah.

SolConverter menyokong elemen Markdown yang biasanya digunakan dalam fail README.

Ini termasuk:

• Tajuk ATX dan Setext;
• teks tebal, condong dan bergaris potong;
• senarai tersusun dan tidak tersusun;
• senarai bersarang;
• senarai tugasan GFM;
• petikan blok;
• pautan Markdown dan pautan automatik;
• kod sebaris;
• blok kod berpagar menggunakan backticks atau tilde;
• label bahasa pagar kod;
• jadual GFM dengan penjajaran;
• jadual HTML mentah yang selamat;
• bahagian details dan summary;
• kbd, sub, sup, figure dan figcaption;
• sauh tajuk;
• YAML front matter di permulaan sumber.

Pagar kod yang mengandungi tanda dolar atau pembatas mirip LaTeX kekal sebagai kod berbanding ditafsirkan sebagai persamaan.

Fail README sering mengandungi arahan pemasangan, fail konfigurasi, contoh API, pemboleh ubah persekitaran dan keratan kod sumber.

SolConverter menggunakan penyerlahan sintaks dengan Highlight.js apabila bahasa pagar kod dicam. Bahasa yang tidak dicam mengekalkan sumber asal dengan selamat.

Blok kod menggunakan font monospace khusus dan gaya cetakan yang memisahkannya daripada penjelasan di sekelilingnya. Kod kekal kiri-ke-kanan walaupun dalam README kanan-ke-liri.

README teknikal mungkin mengandungi formula, matriks, notasi saintifik, ekspresi kebarangkalian atau kimia.

SolConverter menyokong output MathJax SVG untuk pembatas matematik Markdown biasa, persekitaran persamaan AMS, Presentation MathML, Content MathML asas dan ekspresi kimia yang ditulis dengan \ce{...}.

Matematik yang didukung termasuk:

• ekspresi sebaris $...$ dan \(...\);
• ekspresi paparan $$...$$ dan \[...\];
• persekitaran persamaan dan penjajaran;
• pecahan, punca kuasa, hasil tambah, kamiran, had dan matriks;
• makro skop dokumen;
• ekspresi penambahan panjang yang memerlukan pemutusan baris.

Matematik dihasilkan sebagai SVG untuk kekal tajam dalam PDF. Matematik yang tidak sah boleh kembali kepada alternatif tempatan tanpa menghentikan baki README secara automatik.

Fail README kerap menggunakan gambar rajah untuk menerangkan seni bina, urutan, keadaan, aliran kerja atau hubungan komponen.

Blok berpagar Mermaid yang didukung dihasilkan secara tempatan sebagai SVG. ZenUML disokong melalui integrasi Mermaid yang dibundel. Gambar rajah dihadkan kepada lebar halaman yang tersedia dan diproses secara bebas.

Jika satu gambar rajah tidak sah, penukar memasukkan alternatif dengan sumber dan terus menghasilkan bahagian yang tinggal.

PlantUML, Graphviz, D2, WaveDrom, BPMN, Nomnoml, dan TikZ penuh tidak disokong pada masa ini dan tidak sepatutnya diiklankan di halaman ini.

Penukar menyokong imej HTTP dan HTTPS awam serta imej data base64 yang sah dalam format PNG, GIF, JPEG, WebP dan SVG.

Imej diskalakan untuk muat pada halaman dan mengekalkan nisbah aspeknya. Rajah, kapsyen, teks alternatif, tajuk, dimensi selamat dan penjajaran boleh dikekalkan.

Walau bagaimanapun, banyak README repositori menggunakan laluan relatif seperti:

./images/screenshot.png
docs/architecture.svg
../assets/demo.gif

Aliran kerja muat naik semasa tidak membungkus folder repositori atau menyelesaikan aset relatif tersebut secara automatik. Tukarkannya kepada URL imej awam atau imej data base64 yang disokong sebelum mencipta PDF.

Lencana biasanya menggunakan URL imej awam dan boleh dihasilkan apabila hos imej boleh diakses secara awam. Jika lencana atau imej tidak dapat dimuatkan, SolConverter memasukkan ruang letak tempatan dan meneruskan penukaran.

Pautan Markdown di dalam README boleh berupa pautan mutlak, relatif repositori atau pautan fragmen halaman.

Pautan HTTP dan HTTPS mutlak kekal bermakna di luar repositori. Pautan relatif seperti ./docs/setup.md atau ../CONTRIBUTING.md mungkin tidak menunjuk ke destinasi yang berguna setelah README menjadi PDF mandiri.

Sebelum berkongsi PDF:

• gantikan pautan relatif penting dengan URL mutlak awam;
• tulis arahan kritikal berbanding hanya bergantung pada fail yang dipautkan;
• sahkan pautan tajuk selepas rendering;
• semak sama ada dokumen masih masuk akal tanpa navigasi repositori;
• sertakan maklumat versi atau rilis apabila PDF dimaksudkan sebagai arkib.

A GitHub README masih fail Markdown, tetapi GitHub mungkin menambah konteks repositori yang tidak terkandung dalam fail yang dimuat naik itu sendiri.

PDF boleh mengekalkan struktur GFM yang disokong seperti jadual, senarai tugasan, kod berpagar, pautan automatik dan tajuk. Ia juga boleh menghasilkan ekspresi MathJax dan gambar rajah Mermaid yang disokong.

Penukar tidak mengeluarkan semula setiap elemen antara muka GitHub. Tab repositori, bilangan isu, widget rilis, pemilih cawangan, kad yang dijana secara dinamik dan elemen halaman GitHub lain bukan sebahagian daripada sumber Markdown.

Untuk PDF mandiri yang paling bersih, pastikan README menyertakan identiti projek, konteks versi dan pautan penting dalam dokumen itu sendiri.

A PDF README boleh berfungsi sebagai penyerahan teknikal yang ringkas apabila pembaca memerlukan:

• gambaran keseluruhan projek;
• langkah pemasangan dan persediaan;
• arahan contoh;
• keperluan konfigurasi;
• gambar rajah seni bina;
• contoh API;
• nota operasi;
• arahan penyelesaian masalah;
• butiran sumbangan atau sokongan.

Untuk set dokumentasi yang besar, layan README sebagai dokumen masuk berbanding memaksa setiap panduan ke dalam satu fail. PDF yang dijana daripada README yang sangat panjang masih boleh berguna, tetapi dokumen berasyar mungkin lebih mudah untuk diselenggara dan dinavigasi.

Repositori berubah dari semasa ke semasa. Menukar README kepada PDF mencipta snapshot boleh dibaca yang dikaitkan dengan rilis, penghantaran, semakan atau pencapaian.

Sebelum mengarkib:

1. add the project or package version;
2. sertakan tarikh atau pengecam rilis yang berkaitan;
3. sahkan arahan dan contoh konfigurasi;
4. gantikan pautan sementara;
5. semak imej, gambar rajah dan persamaan;
6. jana dan periksa PDF akhir;
7. simpan PDF di sebelah rekod rilis.

PDF yang dijana ialah snapshot, bukan pengganti README yang dikawal sumber.

Fail README boleh mengandungi HTML mentah, URL imej jauh dan blok yang salah format.

SolConverter menapis HTML yang dihasilkan, membuang skrip dan pengendali peristiwa, menolak URL yang tidak selamat, mengehadkan HTML mentah ke senarai dibenarkan, mengehadkan rentang jadual, menggunakan dasar keselamatan kandungan yang ketat, dan menyekat permintaan pelayar di luar dasar imej yang dibenarkan.

Fail tempatan, destinasi localhost, literal IP peribadi, URL javascript:, dan skema sumber yang tidak disokong disekat. Imej, persamaan dan gambar rajah yang tidak sah dikendalikan secara tempatan jika boleh supaya baki README boleh terus dihasilkan.

SolConverter menggunakan susun atur dokumen yang konsisten pada fail README.

Borang web semasa menggunakan:

• Saiz halaman A4;
• orientasi potret;
• margin terurus untuk output yang boleh dibaca;
• penomboran halaman semasa / jumlah;
• tajuk output berdasarkan nama fail README;
• latar belakang bercetak.

Susun atur potret direka untuk bacaan umum. Sentiasa pratonton jadual lebar dan kod sebelum memuat turun.

Gunakan halaman berfokuskan README ini apabila sumbernya ialah README projek dan anda memerlukan panduan tentang pagar kod, struktur GFM, lencana, imej relatif repositori dan pautan repositori.

Gunakan penukar Markdown kepada PDF utama untuk laporan, dokumen matematik, nota teknikal, cadangan, dokumen berbilang bahasa dan fail .md umum.

Kedua-dua halaman menggunakan keupayaan penukaran teras yang sama, tetapi ia berfungsi untuk tugasan pengguna yang berbeza dan menyediakan panduan penyediaan yang berbeza.

• Tukar mana-mana fail Markdown kepada PDF
• Tukar PDF kepada Markdown
• Tukar HTML kepada Markdown
• Tukar Word kepada Markdown
• Daftar semua alat file-ke-Markdown