mdBook - Markdown से किताबें बनाने का command-line टूल

 (rust-lang.github.io)
4 पॉइंट द्वारा GN⁺ 2023-07-01 | 1 टिप्पणियां | WhatsApp पर शेयर करें
  • जब दस्तावेज़ और ट्यूटोरियल को किताब के रूप में वितरित करना हो, mdBook 0.5.3 Markdown-आधारित लेखन और आसानी से नेविगेट की जा सकने वाली आउटपुट सामग्री दोनों प्रदान करता है
  • हल्के Markdown syntax और integrated search की वजह से लेखक formatting से ज़्यादा content पर ध्यान दे सकते हैं
  • code block syntax highlighting और theme files के माध्यम से तकनीकी दस्तावेज़ों के लिए ज़रूरी पठनीयता और आउटपुट format को समायोजित किया जा सकता है
  • preprocessors और backends custom syntax, content modification, और कई output formats के rendering के लिए extension points प्रदान करते हैं
  • यह Rust प्रोजेक्ट्स और The Rust Programming Language किताब में इस्तेमाल होने वाला टूल है, इसलिए Rust documentation ecosystem से इसका मजबूत जुड़ाव है

Markdown किताब बनाने के लिए ज़रूरी बेसिक फीचर्स

  • mdBook Markdown से किताबें बनाने का एक command-line टूल है
  • यह product docs, API docs, tutorials, और course materials जैसे साफ-सुथरे और आसानी से नेविगेट होने वाले content बनाने के लिए उपयुक्त है
  • यह writing और reading experience को बेहतर बनाने वाली सुविधाएँ साथ में देता है
    • हल्के Markdown syntax के साथ content writing पर ध्यान केंद्रित किया जा सकता है
    • किताब के भीतर integrated search support
    • कई भाषाओं के code blocks पर color syntax highlighting लागू किया जा सकता है
    • theme files से output format को customize किया जा सकता है

विस्तार और Rust ecosystem से जुड़ाव

  • preprocessors custom syntax extension और content modification संभाल सकते हैं
  • backends के जरिए कई output formats में rendering की जा सकती है
  • mdBook को speed, safety, और simplicity के लिए Rust में लिखा गया है
  • यह Rust code samples के automatic testing को support करता है

वास्तविक उपयोग के मामले और योगदान का तरीका

  • mdBook का अपना documentation, mdBook से बने output का ही एक उदाहरण है
  • Rust programming language project mdBook का उपयोग करता है, और The Rust Programming Language किताब भी इसका एक use case है
  • mdBook एक मुफ्त open source प्रोजेक्ट है
    • source code GitHub पर उपलब्ध है
    • issues और feature requests को GitHub issue tracker पर दर्ज किया जा सकता है
    • योगदान करने के लिए CONTRIBUTING गाइड पढ़कर pull request खोला जा सकता है
  • mdBook का source और documentation Mozilla Public License v2.0 के तहत वितरित किया जाता है

संबंधित पढ़ाई

1 टिप्पणियां

 
GN⁺ 2023-07-01
Hacker News टिप्पणियाँ

  • मुझे याद है कि यह प्लेटफ़ॉर्म लाइब्रेरी को bundle या vendor करने के बजाय CDN-hosted libraries का इस्तेमाल करता है। इसलिए उपयोगकर्ता सिर्फ CDN outage ही नहीं, बल्कि उस सर्वर द्वारा एकत्र किए जाने वाले डेटा के लिए भी exposed रहते हैं
    और भी अफ़सोस की बात यह है कि frontend में Highlight.js और MathJax का इस्तेमाल करने का तरीका बहुत ही wasteful है। हर client को syntax और LaTeX खुद parse और render करना पड़ता है, और हर visit पर वही काम दोबारा करना पड़ता है ताकि वही result मिले। syntax highlighting को build time पर handle किया जा सकता है और JavaScript की ज़रूरत होने का कोई खास कारण भी नहीं है

    • MathJax शायद CDN पर hosted है, और CSS व दूसरी JS files HTML file के बगल में साथ रखी जाती हैं
      लगता है MathJax support optional होने की वजह से ऐसा चुना गया है: https://rust-lang.github.io/mdBook/format/mathjax.html
      फिर भी, बहुत संभावना है कि MathJax JS फिर से CDN से अतिरिक्त files लोड करे, इसलिए यह समझना मुश्किल है कि पूरी MathJax files को generated HTML के बगल में ही क्यों नहीं रखा जाता
    • लगता है इससे संबंधित एक open PR पहले से मौजूद है: https://github.com/rust-lang/mdBook/pull/1918

  • इस thread में जिन documentation·static site tools का ज़िक्र हुआ, वे लगभग 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

    • मैंने nimibook भी इस्तेमाल किया है
      यह mdBook का Nim port है, लेकिन इसमें Nim के JavaScript backend का उपयोग करके interactive content बनाने की क्षमता भी बढ़ाई गई है। मैंने खुद इसे इस्तेमाल नहीं किया, लेकिन ज़रूरत पड़ने पर interactive elements को एक ही जगह बना सकने का विचार अच्छा लगता है: https://pietroppeter.github.io/nimib/interactivity.html
    • Sphinx को भी छोड़ना मुश्किल है। इसका workflow ब्लॉग, फ़ोरम, या thread format की तुलना में book format के लिए ज़्यादा उपयुक्त है
    • HackMD अक्सर तब चुना जाता है जब formula notation support के साथ share और collaborative editing वाली Markdown documents बनानी हों: https://hackmd.io/
    • अच्छा होगा अगर ऐसे tools की feature comparison table या site हो। मैं built-in search, PDF output, ePub output, multiple themes, और बाकी features की तुलना देखना चाहूँगा
    • https://jupyterbook.org/en/stable/ भी है। मैं Jupyter Book में योगदान दे रहा हूँ

  • मैंने MdBook, Jekyll, MkDocs इस्तेमाल किए हैं। MdBook बेसिक प्रोजेक्ट्स के लिए काफ़ी polished है, लेकिन यह कुछ ज़्यादा ही minimal लगा। जिन MdBook साइटों को मैंने पसंद किया, उनके source देखने पर पता चला कि कुछ मामलों में उन्हें custom Rust code से extend किया गया था
    मेरी सिफारिश यह है: MkDocs एक reasonably flexible default विकल्प है, Jekyll उन मामलों के लिए बेहतर है जहाँ landing page या blog जैसी ज़्यादा flexibility चाहिए, और Antora तब सही है जब आप कई projects और कई versions के docs को जोड़कर बेहतरीन documentation site बनाना चाहते हों और उसके लिए काफ़ी मेहनत करने को तैयार हों। AsciiDoc में documentation लिखने के लिए बहुत उपयोगी features हैं
    Hugo, Jekyll की तरह flexible लगता है, लेकिन उसे मनचाहे ढंग से ढालने में और ज़्यादा मेहनत लगती है, और themes के बीच behavior का फ़र्क भी बहुत बड़ा लगता है। जिस theme का मैं इस्तेमाल कर रहा था उसमें ज़रूरी feature नहीं था, इसलिए दूसरे theme पर जाना चाहा, लेकिन migration आसान नहीं थी और आख़िरकार मैंने छोड़ दिया। MdBook काफ़ी सक्रिय दिखता है, इसलिए लगता है कि यह अंततः आगे निकल आएगा

    • मैं पुराना Jekyll उपयोगकर्ता हूँ और blog के लिए यह अब भी शानदार है, लेकिन documentation sites के लिए static site generators में Docusaurus सबसे अच्छा लगा: https://docusaurus.io/
      JavaScript-आधारित tool इस्तेमाल नहीं करना चाहता था, इसलिए लंबे समय तक टालता रहा, लेकिन इस्तेमाल करने पर पाया कि इसे शुरू करना आसान है, यह बहुत तेज़ है, default site सुंदर होती है, और customize करना भी आसान है। MDX support भी बेहतरीन है
    • material mkdocs theme(https://squidfunk.github.io/mkdocs-material/) का landing page सच में बहुत refined है। यह सोचकर और भी प्रभावशाली लगता है कि यह अलग software के लिए बनाया गया theme है
    • science और statistics के क्षेत्र में Quarto बेहतरीन लगता है: https://quarto.org
    • Antora का नाम मैंने पहली बार सुना, लेकिन कई repositories से docs को assemble करना और branches के ज़रिए version manage करना ठीक वैसा ही है जैसा मैं चाहता हूँ। बस यह अफ़सोस है कि मौजूदा docs Markdown और interactive React components के मिश्रण में हैं, इसलिए MDX का इस्तेमाल न होना खलता है
    • मैं MkDocs बहुत इस्तेमाल करता हूँ और इसे बहुत पसंद करता हूँ
      BookStack भी आज़मा रहा हूँ; यह wiki के ज़्यादा क़रीब है, लेकिन जो लोग बहुत technical नहीं हैं उनके लिए अच्छा है। आम तौर पर MkDocs project VSCode में edit किए जाते हैं और Git repository में रखे जाते हैं, जबकि BookStack पूरी तरह web-based है

  • पहले मैं til.secretGeek.net को GitBook से generate करता था, लेकिन समय के साथ यह इतना धीमा हो गया कि site build होने में 45 मिनट लगने लगे, और जिन features का मैं इस्तेमाल करता था वे या तो बंद कर दिए गए या “premium” बना दिए गए। यानी आख़िरकार एनशिटिफिकेशन शुरू हो गया
    अगर आप कोई ऐसा free tool इस्तेमाल कर रहे हैं जो बहुत अच्छा लगता है, तो कुछ साल इंतज़ार कीजिए—उसके बिगड़ जाने की काफ़ी संभावना है। आख़िर में मैंने .NET में खुद एक बहुत minimal static site generator बना लिया, जिससे build फिर से कुछ ही सेकंड में होने लगा। मैं इसे दूसरों को इस्तेमाल करने के लिए promote नहीं करता, क्योंकि अगर यह लोकप्रिय हो गया तो शायद मैं भी आख़िरकार उसी तरह इसे बिगाड़ दूँगा

    • “spruik” ऑस्ट्रेलियाई slang है, जिसका मतलब है किसी चीज़ का सार्वजनिक रूप से, ख़ासकर किसी showman या salesperson की तरह, बढ़-चढ़कर प्रचार करना
      https://www.collinsdictionary.com/jp/dictionary/english/spru...

  • मैंने कई projects में mdBook इस्तेमाल किया है, लेकिन आजकल material for mkdocs ज़्यादा पसंद आता है क्योंकि इसमें built-in features कहीं अधिक हैं
    उदाहरण के लिए, दाईं तरफ़ का page TOC मुझे बहुत पसंद है, और mdBook में यह feature साफ़ तौर पर नहीं है। mdBook में SUMMARY को बहुत विस्तार से बनाना पड़ता है, और जो सामग्री मूल रूप से एक ही page पर रह सकती थी, उसे कई files में बाँटना standard तरीका जैसा लगता है

    • material for mkdocs इतना अच्छा है कि इसके लिए Python install करना और virtual environment सेट करना भी मंज़ूर है
    • मुझे MkDocs काफ़ी समय से पसंद है। यह बहुत कम झंझट में काम पूरा कर देता है, चुनने के लिए themes भी काफ़ी हैं, और खुद customize करना या नया बनाना भी तुलनात्मक रूप से आसान है
    • chapter-wise TOC पाने के लिए मैं https://github.com/JorelAli/mdBook-pagetoc इस्तेमाल करता हूँ

  • कुछ दिन पहले मैंने एक छोटे project के documentation के लिए mdBook इस्तेमाल करना शुरू किया, और यह मेरी ज़रूरत के बिल्कुल मुताबिक़ छोटा static page generator निकला
    HUGO भी इस्तेमाल किया है, लेकिन mdBook की तुलना में वह बहुत बड़ा और भारी लगता है। अभी मैं Obsidian/VIM में docs edit करता हूँ और Gitea पर push करते ही एक मिनट के अंदर public docs बन जाते हैं

    • मैं Hugo के साथ book theme(https://github.com/alex-shpak/hugo-book) इस्तेमाल करता हूँ। अगर आप Hugo से परिचित नहीं हैं तो शुरुआत में थोड़ा समय लगेगा, लेकिन उसके बाद Hugo की shortcode जैसी flexibility बहुत काम आती है
      सही shortcode के साथ images, equations वगैरह की automatic numbering की जा सकती है। सोच रहा हूँ कि क्या mdBook में भी automatic numbering संभव है। इसमें दाईं तरफ़ TOC, tags, और pages को columns में बाँटने जैसी सुविधाएँ भी हैं, और KaTeX support भी अच्छा है। लगता है mdBook MathJax इस्तेमाल करता है, और deployment भी सिर्फ़ push या rsync से आसान हो जाता है
    • हाल ही में मैंने PlantUML extension इस्तेमाल करना शुरू किया है, जो docs में architecture diagrams जोड़ने में मदद करता है

  • हाल में मैंने अपना कुछ content धीरे-धीरे .md से .mdx में शिफ्ट करके देखना शुरू किया, और यह काफ़ी ताज़गीभरा लगा। Markdown की सबसे मुश्किल बात हमेशा यह रही कि हर dialect की सीमाएँ अलग होती हैं, और उन सीमाओं को बढ़ाने का तरीका भी अलग-अलग होता है
    standard GitBook Markdown dialect के 80~90% से मैं काफ़ी संतुष्ट हूँ, लेकिन कभी-कभी complex tables, code blocks जिनमें सिर्फ़ कुछ lines को highlight करना हो और syntax highlighting भी बनी रहे, interactive sliders, दस्तावेज़ में embedded calculator, या कुछ खास graphs और charts की ज़रूरत पड़ती है। बड़ी टीमों में MDX कैसे काम करेगा, यह नहीं पता, लेकिन व्यक्तिगत काम के लिए यह निश्चित रूप से एक सुधार लगता है

    • मैंने पहली बार .mdx के बारे में सुना और [0] देखा। लगता है कि मैं frontend standardization की दिशा को काफ़ी ठीक से follow नहीं कर पा रहा था
      अच्छा होता अगर dialects ख़त्म होकर एक universal approach बनती, लेकिन docs में लिखा है, “MDX React से बंधा नहीं है, और Preact, Vue, Emotion, Theme UI आदि में भी इस्तेमाल किया जा सकता है, साथ ही classic/automatic JSX runtime दोनों को support करता है।” Svelte implementation [1] भी पहले से मौजूद है, इसलिए समझ नहीं आ रहा कि यह फिर से frontend frameworks से बंधे और dialects खोल देने वाला Pandora’s box तो नहीं है। .mdx के अंदर भी बँटवारा हो सकता है और यह .md से compatible भी न रहे
      [0] https://mdxjs.com/docs/what-is-mdx/
      [1] https://mdsvex.com/docs
    • पूरी तरह सहमत। जब मुझे Mdsvex मिला, तो लगा जैसे ज़िंदगी बदल गई हो: https://mdsvex.com
    • .mdx को https://astro.build/ के साथ बहुत आसानी से इस्तेमाल किया जा सकता है। Astro एक JavaScript meta-framework है, और यह static site generation first approach अपनाता है जिसमें client को JS नहीं भेजा जाता
      इस्तेमाल करने लायक themes भी हैं, लेकिन अगर आप modern web developer हैं, तो ख़ुद बनाना भी काफ़ी आसान होगा

  • Markdown आधारित किताबें बनाने के लिए मैंने मुफ़्त open source cross-platform tool KeenWrite बनाया है: https://github.com/DaveJarvis/keenwrite
    KeenWrite document typesetting के लिए ConTeXt को call करता है, और preview mode में math typesetting के लिए KeenType fork का उपयोग करता है। command line से PDF generate किया जा सकता है। जो किताब मैं अभी लिख रहा हूँ, उसमें body के अंदर external files में define किए गए कई variables को refer किया जाता है, metadata के ज़रिए PDF properties pass की जाती हैं, और chapters argument के साथ सिर्फ़ कुछ chapters ही build किए जा सकते हैं। theme directory में colors, fonts, layout, annotations आदि के typesetting instructions होते हैं
    sample output: https://github.com/DaveJarvis/keenwrite-themes/tree/main/exa...

  • मुझे हैरानी होती है कि Markdown या उससे मिलते-जुलते formats किताबों, documentation, और लगभग हर तरह की writing का default format क्यों नहीं हैं। कुछ साल पहले Typora पर आने के बाद, अपनी writing के लिए मुझे Word/Writer की लगभग ज़रूरत नहीं पड़ती; अब उन्हें सिर्फ़ तब खोलता हूँ जब किसी और ने document भेजा हो
    जो किताबें मैं पढ़ता हूँ, उनमें से 90% के लिए भी यह कोई साफ़ वजह नहीं दिखती कि वे Markdown format में क्यों नहीं हो सकतीं। यह समझ में आता है कि paper books को सुंदर ढंग से print करने के लिए proper typesetting चाहिए, लेकिन computer या smartphone पर पढ़े जाने वाले ज़्यादातर text, या MS/LibreOffice से सीधे print होने वाले documents, वैसे भी उस स्तर का typesetting नहीं रखते

    • Markdown एक storage format के रूप में काफ़ी कमज़ोर है। CommonMark जैसा एक semi-official standard है, लेकिन उसमें features कम हैं, इसलिए ज़्यादातर लोग GitHub Markdown जैसी दूसरी variants का उपयोग करते हैं, और कई individual apps Markdown को ऐसे extend करते हैं जो एक-दूसरे से compatible नहीं होते
      AsciiDoc जैसे बेहतर alternatives भी हैं, लेकिन वे documentation के लिए ज़्यादा specialized हैं और Markdown जैसी momentum नहीं रखते। यह देखते हुए कि Markdown एक अपेक्षाकृत बाद में आया format है, शायद बेहतर सवाल यह है कि किताबें Markdown में क्यों होनी चाहिए। binary या XML-based formats की तुलना में Markdown का सबसे बड़ा फ़ायदा यह है कि इसे plain text के रूप में कुछ हद तक पढ़ा जा सकता है, लेकिन ज़्यादातर publishers और readers के लिए यह इतनी अहम बात नहीं है
    • किताबों के typesetting में बहुत सी सूक्ष्मताएँ और जटिलताएँ होती हैं जो बिना प्रशिक्षित नज़र को दिखती भी नहीं, और Markdown+CSS इन्हें संभालने के लिए काफ़ी refined नहीं है। HTML/CSS+JS भी तकनीकी रूप से संभव है, लेकिन digital typesetting के state of the art से अभी काफ़ी पीछे है
      यह एक आम engineer trap भी है—“मैं इससे बेहतर कर सकता हूँ”—इसलिए बिना जाँच-पड़ताल के ऐसा मान लेना ठीक नहीं। typesetting इन tools से कहीं पुराना क्षेत्र है, और इसमें समय के साथ काफ़ी मूल्यवान समझ और तकनीक जमा हुई है; सिर्फ़ इसलिए कि कुछ उपयोगों के लिए Markdown लगभग काफ़ी लगता है, हमें उसे नज़रअंदाज़ नहीं करना चाहिए
    • काम में मैं बहुत documentation लिखता हूँ, और मुझे Markdown को उसके rendered output के साथ side-by-side देखना पसंद है। एक बार syntax की आदत हो जाए, तो Markdown Word जैसे editors से कहीं तेज़ लगता है, और text editor में एक साधारण list बनाना भी उसके बाद झंझटभरा लगने लगता है

  • mdBook इस्तेमाल करने में आसान है, और मुझे ख़ास तौर पर यह पसंद है कि इसमें users theme चुन सकते हैं। मैं इसे मुख्यतः ebooks के online versions [0] और curated materials [1][2] के लिए उपयोग करता हूँ
    [0] https://github.com/learnbyexample/scripting_course#ebooks
    [1] https://learnbyexample.github.io/py_resources/
    [2] https://learnbyexample.github.io/curated_resources/