mdBook - Alat baris perintah untuk membuat buku dengan Markdown

 (rust-lang.github.io)
4 poin oleh GN⁺ 2023-07-01 | 1 komentar | Bagikan ke WhatsApp
  • Saat perlu mendistribusikan dokumentasi dan tutorial dalam bentuk buku, mdBook 0.5.3 menyediakan penulisan berbasis Markdown sekaligus hasil keluaran yang mudah dinavigasi
  • Berkat sintaks Markdown yang ringan dan pencarian terintegrasi, penulis bisa lebih fokus pada konten daripada format
  • Melalui penyorotan sintaks pada blok kode dan berkas tema, keterbacaan serta penyesuaian format keluaran yang dibutuhkan dokumentasi teknis dapat dicapai
  • Preprocessor dan backend menyediakan titik ekstensi untuk sintaks kustom, modifikasi konten, dan perenderan ke berbagai format keluaran
  • Karena merupakan alat yang digunakan dalam proyek Rust dan buku The Rust Programming Language, keterkaitannya dengan ekosistem dokumentasi Rust sangat kuat

Fitur dasar yang dibutuhkan untuk membuat buku Markdown

  • mdBook adalah alat baris perintah untuk membuat buku dengan Markdown
  • Cocok untuk membuat konten yang rapi dan mudah dinavigasi seperti dokumentasi produk, dokumentasi API, tutorial, dan materi kuliah
  • Menyediakan fitur yang mendukung pengalaman menulis dan membaca
    • Bisa fokus menulis konten dengan sintaks Markdown yang ringan
    • Mendukung pencarian terintegrasi di dalam buku
    • Menerapkan penyorotan sintaks berwarna pada blok kode dalam berbagai bahasa
    • Format keluaran dapat dikustomisasi dengan berkas tema

Ekstensi dan keterhubungan dengan ekosistem Rust

  • Preprocessor dapat menangani ekstensi sintaks kustom dan modifikasi konten
  • Melalui backend, konten dapat dirender ke berbagai format keluaran
  • mdBook ditulis dengan Rust demi kecepatan, keamanan, dan kesederhanaan
  • Mendukung pengujian otomatis untuk contoh kode Rust

Contoh penggunaan nyata dan cara berkontribusi

Bacaan terkait

1 komentar

 
GN⁺ 2023-07-01
Komentar Hacker News

  • Saya ingat platform ini menggunakan library yang di-host di CDN alih-alih membundel atau mem-vendor library. Jadi pengguna terekspos bukan hanya pada gangguan CDN, tetapi juga pada data yang dikumpulkan server tersebut
    Yang lebih disayangkan, cara frontend menggunakan Highlight.js dan MathJax sangat boros. Semua klien harus mem-parse dan me-render sintaks serta LaTeX sendiri, lalu mengulangi pekerjaan yang sama setiap kali ada kunjungan untuk mendapatkan hasil yang sama. Penyorotan sintaks bisa diproses saat build, dan hampir tidak ada alasan mengapa JavaScript diperlukan

    • MathJax tampaknya di-host dari CDN, sementara CSS dan file JS lain diletakkan berdampingan dengan file HTML
      Karena dukungan MathJax bersifat opsional, sepertinya itulah alasan pilihan tersebut dibuat: https://rust-lang.github.io/mdBook/format/mathjax.html
      Namun, karena kemungkinan besar JS MathJax akan memuat file tambahan lagi dari CDN, sulit dipahami mengapa seluruh file MathJax tidak diletakkan saja di samping HTML yang dihasilkan
    • Sepertinya sudah ada PR terbuka terkait hal ini: https://github.com/rust-lang/mdBook/pull/1918

  • Alat dokumentasi/situs statis yang disebut di thread ini kira-kira adalah Jekyll, Hugo Book, MdBook, MkDocs, MkDocs Material, GitBook, Antora, Docusaurus, Nextra, Astro, Starlight, Clowncar, Keenwrite, Quarto, Honkit, JupyterBook
    Jekyll, Hugo Book, MdBook, MkDocs, MkDocs Material, GitBook, Antora, Docusaurus, Nextra, Astro, Starlight, Clowncar, Keenwrite, Quarto, Honkit, JupyterBook

    • Saya juga pernah memakai nimibook
      Ini adalah port mdBook ke Nim, tetapi juga diperluas dengan kemampuan membuat konten interaktif menggunakan backend JavaScript milik Nim. Saya belum mencobanya sendiri, tetapi saya suka gagasan bahwa elemen interaktif bisa dibuat di satu tempat saat dibutuhkan: https://pietroppeter.github.io/nimib/interactivity.html
    • Sphinx juga sulit untuk tidak dimasukkan. Alur kerjanya lebih cocok untuk format buku daripada format blog, forum, atau thread
    • HackMD mendukung notasi rumus dan sering menjadi pilihan saat membuat dokumen Markdown yang bisa dibagikan dan diedit bersama: https://hackmd.io/
    • Akan bagus jika ada tabel atau situs perbandingan fitur untuk alat-alat seperti ini. Saya ingin membandingkan pencarian bawaan, keluaran PDF, keluaran ePub, banyak tema, dan fitur lainnya
    • https://jupyterbook.org/en/stable/ juga ada. Saya sedang berkontribusi pada Jupyter Book

  • Saya sudah mencoba mdBook, Jekyll, dan MkDocs; mdBook terasa rapi untuk proyek bawaan, tetapi juga terasa terlalu minimal. Saat melihat source dari situs mdBook yang saya sukai, beberapa ternyata diperluas dengan kode Rust kustom
    Rekomendasinya: MkDocs adalah pilihan dasar yang cukup fleksibel, Jekyll cocok jika membutuhkan lebih banyak fleksibilitas seperti untuk landing page atau blog, dan Antora cocok jika ingin membangun situs dokumentasi terbaik dengan menggabungkan banyak proyek dan banyak versi dokumentasi serta bersedia mencurahkan banyak usaha. AsciiDoc punya banyak fitur yang berguna untuk penulisan dokumentasi
    Hugo tampak fleksibel seperti Jekyll, tetapi sepertinya butuh lebih banyak usaha untuk menyesuaikannya sesuai keinginan, dan perbedaan cara kerja antar tema terlalu besar. Saya sempat ingin pindah ke tema lain karena tema yang saya pakai tidak punya fitur yang dibutuhkan, tetapi transisinya tidak mudah sehingga akhirnya saya menyerah. MdBook terlihat cukup aktif, jadi pada akhirnya sepertinya akan menyusul

    • Saya pengguna lama Jekyll, dan menurut saya itu masih sangat bagus untuk blog, tetapi di antara static site generator untuk situs dokumentasi, Docusaurus adalah yang terbaik: https://docusaurus.io/
      Saya lama menundanya karena tidak ingin memakai tool berbasis JavaScript, tetapi setelah dicoba ternyata mudah untuk memulai, sangat cepat, situs bawaan tampil indah, dan juga mudah dikustomisasi. Dukungan MDX-nya juga sangat bagus
    • Landing page material mkdocs theme(https://squidfunk.github.io/mkdocs-material/) benar-benar terlihat sangat rapi. Terutama mengesankan jika mengingat ini adalah tema untuk software terpisah
    • Untuk sains dan statistik, menurut saya Quarto sangat bagus: https://quarto.org
    • Saya baru pertama kali mendengar Antora, tetapi cara kerjanya yang merakit dokumentasi dari banyak repositori dan mengelola versi lewat branch persis seperti yang saya inginkan. Namun, agak disayangkan karena dokumentasi yang ada sekarang merupakan kombinasi Markdown dan komponen React interaktif, jadi tidak memakai MDX menjadi kekurangan
    • Saya sering memakai MkDocs dan sangat menyukainya
      Saya juga sedang mencoba BookStack; ini lebih mirip wiki, tetapi bagus untuk orang yang tidak terlalu akrab dengan teknologi. Biasanya proyek MkDocs diedit di VSCode dan disimpan di repositori Git, tetapi BookStack sepenuhnya berbasis web

  • Dulu saya membuat til.secretGeek.net dengan GitBook, tetapi lama-kelamaan makin lambat sampai build situs memakan waktu 45 menit, dan fitur-fitur yang saya pakai dihapus atau diubah menjadi “premium”. Pada akhirnya itu seperti awal dari enshittification
    Kalau Anda memakai tool gratis yang terlihat terlalu bagus, kemungkinan besar dalam beberapa tahun itu akan rusak. Akhirnya saya membuat sendiri static site generator yang sangat minimal dengan .NET sehingga build kembali selesai dalam hitungan detik. Saya tidak benar-benar mempromosikannya untuk dipakai orang lain, karena kalau sampai populer saya mungkin akan merusaknya dengan cara yang sama

  • Saya telah memakai mdBook di beberapa proyek, tetapi belakangan ini terasa material for mkdocs jauh lebih enak dipakai karena fitur bawaannya jauh lebih banyak
    Misalnya saya suka daftar isi halaman di sisi kanan, dan mdBook terasa sangat jelas tidak memiliki fitur itu. Di mdBook, tampaknya praktik standarnya adalah menyusun SUMMARY dengan sangat rinci dan memecah isi yang tadinya bisa ada dalam satu halaman menjadi banyak file

    • material for mkdocs cukup bagus sampai-sampai layak menanggung instalasi Python dan pengaturan virtual environment
    • Saya sudah cukup lama menyukai MkDocs. Ia menyelesaikan pekerjaan dengan kerepotan minimum, punya banyak tema yang bisa dipilih, dan juga relatif mudah untuk dikustomisasi sendiri atau membuat yang baru
    • Saya memakai https://github.com/JorelAli/mdBook-pagetoc untuk mendapatkan daftar isi per bab

  • Beberapa hari lalu saya mulai memakai mdBook untuk mendokumentasikan proyek kecil, dan ini adalah generator halaman statis kecil yang tepat sesuai kebutuhan saya
    Saya juga pernah mencoba HUGO, tetapi dibanding mdBook rasanya terlalu besar dan bengkak. Sekarang saya mengedit dokumentasi di Obsidian/VIM lalu push ke Gitea, dan dalam kurang dari 1 menit dokumentasi publik sudah dibuat

    • Saya memakai Hugo dengan book theme(https://github.com/alex-shpak/hugo-book). Jika belum terbiasa dengan Hugo, memang perlu waktu adaptasi, tetapi setelah itu fleksibilitas seperti shortcode yang disediakan Hugo jadi terasa sangat berguna
      Dengan shortcode yang tepat, Anda bisa melakukan penomoran otomatis untuk gambar, rumus, dan sebagainya. Saya penasaran apakah mdBook juga bisa melakukan penomoran otomatis. Ada juga fitur daftar isi di kanan, tag, serta kemampuan membagi halaman ke dalam kolom, dan dukungan KaTeX juga bagus. MdBook tampaknya memakai MathJax, dan deployment mudah hanya dengan push atau rsync
    • Baru-baru ini saya mulai memakai ekstensi PlantUML, dan itu membantu untuk memasukkan diagram arsitektur ke dalam dokumentasi

  • Saya baru mulai perlahan memindahkan konten terbaru dari .md ke .mdx sambil melihat-lihat, dan rasanya cukup segar. Hal tersulit dari Markdown adalah tiap dialek punya keterbatasan yang berbeda, dan cara memperluas keterbatasan itu juga bermacam-macam.
    Saya sangat puas dengan 80~90% dialek Markdown GitBook standar, tetapi kadang saya membutuhkan tabel yang rumit, blok kode yang hanya menyorot beberapa baris sambil tetap mempertahankan syntax highlighting, slider interaktif, kalkulator yang ditanamkan di dalam dokumen, atau grafik dan bagan tertentu. Saya tidak tahu bagaimana MDX akan bekerja di tim besar, tetapi untuk pekerjaan pribadi ini jelas tampak sebagai peningkatan

    • Saya baru pertama kali mendengar tentang .mdx dan mencari [0]. Rupanya saya tidak cukup mengikuti arus standardisasi frontend.
      Akan bagus kalau dialek-dialek itu hilang dan muncul satu pendekatan universal, tetapi dokumentasinya mengatakan, “MDX tidak terikat pada React dan dapat digunakan juga dengan Preact, Vue, Emotion, Theme UI, dan lainnya, serta mendukung runtime JSX classic maupun automatic.” Sudah ada implementasi Svelte [1], jadi saya tidak yakin apakah ini bukan kotak Pandora lain yang menambah lebih banyak dialek yang terikat ke framework frontend. Bisa saja terpecah juga di dalam .mdx sendiri dan tidak kompatibel dengan .md.
      [0] https://mdxjs.com/docs/what-is-mdx/
      [1] https://mdsvex.com/docs
    • Sepenuhnya setuju. Saat menemukan Mdsvex, rasanya seperti hidup saya berubah: https://mdsvex.com
    • .mdx bisa dipakai dengan sangat mudah bersama https://astro.build/. Astro adalah metaframework JavaScript yang mengambil pendekatan static site generation first tanpa mengirim JS ke klien.
      Ada tema yang bisa dipakai, tetapi bagi web developer modern, membuatnya sendiri juga akan cukup mudah

  • Saya membuat KeenWrite, alat gratis, open source, lintas platform untuk membuat buku berbasis Markdown: https://github.com/DaveJarvis/keenwrite
    KeenWrite memanggil ConTeXt untuk typesetting dokumen, dan dalam mode pratinjau menggunakan fork KeenType untuk typesetting rumus. PDF bisa dibuat dari command line. Buku yang sedang saya tulis sekarang merujuk ke beberapa variabel yang didefinisikan di file eksternal dari isi utama, meneruskan properti PDF lewat metadata, dan dapat membangun hanya sebagian bab dengan argumen chapters. Direktori theme berisi instruksi typesetting untuk warna, font, tata letak, anotasi, dan sebagainya.
    Contoh output: https://github.com/DaveJarvis/keenwrite-themes/tree/main/exa...

  • Saya penasaran kenapa Markdown atau format serupa bukan format dasar untuk buku, dokumentasi, dan hampir semua jenis tulisan. Setelah pindah ke Typora beberapa tahun lalu, saya hampir tidak pernah membutuhkan Word/Writer untuk tulisan saya sendiri, dan hanya memakainya saat membuka dokumen kiriman orang lain.
    Bahkan untuk 90% buku yang saya baca, saya tidak melihat alasan yang jelas mengapa formatnya tidak memakai Markdown. Saya paham bahwa untuk mencetak buku kertas dengan indah dibutuhkan typesetting, tetapi sebagian besar teks yang dibaca di komputer atau ponsel, atau langsung dicetak dari MS/LibreOffice, toh tidak benar-benar mendapatkan pekerjaan typesetting seperti itu

    • Markdown cukup lemah sebagai format penyimpanan. Ada CommonMark sebagai standar semi-resmi, tetapi fiturnya kurang sehingga kebanyakan memakai cara lain seperti GitHub Markdown, dan aplikasi individual juga sering memperluas Markdown dengan cara yang tidak saling kompatibel.
      Ada alternatif yang lebih baik seperti AsciiDoc, tetapi itu lebih khusus untuk dokumentasi dan tidak punya daya dorong yang mendekati Markdown. Mengingat Markdown adalah format yang muncul relatif belakangan, pertanyaan yang lebih tepat justru kenapa buku harus memakai Markdown. Keunggulan terbesar Markdown dibanding format biner atau berbasis XML adalah bahwa ia masih bisa dibaca sampai tingkat tertentu sebagai plain text, tetapi bagi sebagian besar penerbit dan pembaca hal itu tidak terlalu penting
    • Typesetting buku memiliki banyak nuansa dan kompleksitas yang tidak terlihat oleh mata yang tidak terlatih, dan Markdown+CSS tidak cukup canggih untuk menangani semuanya. HTML/CSS+JS juga secara teknis mungkin, tetapi masih jauh tertinggal dari state of the art dalam typesetting digital.
      Ini juga jebakan khas insinyur “saya bisa membuat yang lebih baik”, jadi jangan berasumsi begitu tanpa riset. Typesetting adalah bidang yang jauh lebih tua daripada alat-alat yang dibahas di sini, dan wawasan serta teknik berharga yang telah terakumulasi selama itu tidak boleh dibuang hanya karena Markdown hampir cukup untuk beberapa penggunaan
    • Saya banyak menulis dokumen untuk pekerjaan, dan saya suka cara Markdown dan hasil render-nya bisa dilihat berdampingan. Setelah terbiasa dengan sintaksnya, Markdown jauh lebih cepat daripada editor seperti Word, dan bahkan membuat satu daftar di editor teks terasa merepotkan

  • mdBook mudah digunakan, dan saya terutama menyukai bahwa pengguna bisa memilih tema. Saya terutama memakainya untuk versi online ebook [0] dan materi kurasi [1][2].
    [0] https://github.com/learnbyexample/scripting_course#ebooks
    [1] https://learnbyexample.github.io/py_resources/
    [2] https://learnbyexample.github.io/curated_resources/