swatson741•2y
MdBook – A command line tool to create books with Markdowngithub.io
122 comments
  • toastal•2y

    IIRC, this platform uses CDN-hosted libraries rather than bundling/vendoring. As a result, users are exposed to not just outages of the CDNs but also the data collected by these servers. That’s a bummer.

    …but it’s not the only bummer. The usage of Highlight.js + MathJax on the front-end is horribly wasteful. Why? It demands all clients parse & render the syntax/LaTeX which is not only taxing on CPUs and batteries, but this action is idempotent meaning every user agent on every page visit is going to do the same wasteful parsing to get the same result. There is no good reason that syntax highlighting shouldn’t be done at build time nor should it require JavaScript.

    • codetrotter•2y

      Looks like MathJax is hosted on a CDN. Everything else, from css to other js files, is hosted alongside the HTML files.

      Seems a bit strange. I wonder why they chose to use a CDN for that one js file.

      Perhaps because MathJax support is optional? https://rust-lang.github.io/mdBook/format/mathjax.html

      Even though the MathJax js file will in turn probably load more things hosted on the CDN. I don’t understand why they are not putting all of the MathJax files alongside the generated HTML files. So that one does not have to rely on any CDN.

      • toastal•2y

        Now that I’m at my laptop I can see that you are correct on most things at least now being vendored­–though it took me a while to find it since the scripts in the <body> like it’s last decade instead of in the <head> with async or defer attributes.

      • singhrac•2y

        Maybe it’s because MathJax loading slow would delay rendering, and using a CDN-hosted MathJax increases the chance the content is cached?

        That’s usually why people use CDNs. It’s more important for MathJax than, say, interactive scripts, since it can cause rendering.

        I don’t think MathJax loads any additional files (I don’t remember seeing any additional network requests).

        • toastal•2y

          With first-party isolation being the standard for the last couple of years, there are no “shared caches”. A third-party CDNs might load a particular resource faster, but at the cost of user privacy & reliability. You can know, barring exceptional circumstances, that if your site loaded, it can load its own libraries. Look at the news of Cloudflare, Fastly, et al. going down and the ‘internet breaking’ because there’s been too much centralization and bad advice that all site’s need these sorts of ‘optimizations’.

    • Ygg2•2y

      Interesting enough there seems to be an open PR for that: https://github.com/rust-lang/mdBook/pull/1918

  • msravi•2y

    So far, in this thread (in no particular order):

    - [Jekyll](https://jekyllrb.com/)

    - [Hugo Book](https://github.com/alex-shpak/hugo-book)

    - [MdBook](https://rust-lang.github.io/mdBook/)

    - [MkDocs](https://www.mkdocs.org/)

    - [MkDocs Material](https://squidfunk.github.io/mkdocs-material/)

    - [GitBook](https://www.gitbook.com/)

    - [Antora](https://antora.org/)

    - [Docusaurus](https://docusaurus.io/)

    - [Nextra](https://nextra.site/)

    - [Astro](https://astro.build/)

    - [Starlight](https://starlight.astro.build/)

    - [Clowncar](https://github.com/secretGeek/clowncar)

    - [Keenwrite](https://github.com/DaveJarvis/keenwrite)

    - [Quarto](https://quarto.org/)

    - [Honkit](https://github.com/honkit/honkit)

    - [JupyterBook](https://jupyterbook.org/)

  • klodolph•2y

    I’ve tried MdBook, Jekyll, and MkDocs. MdBook is slick for basic projects, but I felt it was too minimalistic for me. When I dug into the source for the MdBook sites that I liked, I saw that they had extended MdBook with some custom Rust code.

    My recommendations are:

    - MkDocs: Good default choice, reasonably flexible.

    - Jekyll: For people who want a little more flexibility—things like landing pages, blogs, etc.

    - Antora: For people who want the best docs, and are willing to put in the most effort. It will manage, for you, the process of generating documentation sites that collect documentation from multiple projects and possibly multiple versions of each project. Asciidoc is full of features you’ll find useful.

    Hugo looks like it has a lot of flexibility like Jekyll, but it seems to take more effort to get everything working the way you want, and it also seems like there’s just too much variation in how the different themes work. To be honest, I never really managed to make anything with it—I found out that the theme I was using didn’t have some features I wanted, so I switched to a different theme, but it’s not easy to switch themes. I was too frustrated and gave up.

    It looks like MdBook is reasonably active, so I’m sure it will catch up.

    • dcchambers•2y

      I am a long time Jekyll user and I still think it's a great tool for blogs, but by far the best SSG for documentation websites I have found is Docusaurus. (https://docusaurus.io/)

      I resisted trying it for the longest time because I didn't want a JavaScript based tool, but I am glad I caved. It's so easy to get started, crazy fast, and the sites are absolutely beautiful out of the box yet easy to customize. The mdx support is awesome too.

      • slorber•2y

        Docusaurus maintainer here, happy to read your feedback ;)

      • klodolph•2y

        Somehow I missed Docusaurus when I surveyed documentation generators—it looks very good!

        I can understand the desire to want something not written in JavaScript, and I certainly have my own language prejudices, but when I surveyed static site generators, language choice was all over the map. Like, I was willing to wrangle Ruby installations and gems to get Jekyll working, something I have nearly no experience with.

      • KRAKRISMOTT•2y

        Also

        https://nextra.site/

    • bccdee•2y

      Wow, what is up with the material mkdocs theme (https://squidfunk.github.io/mkdocs-material/)? That's an extremely spiffy landing page, especially given that it's for a theme designed for a totally separate piece of software.

      • jonasdoesthings•2y

        mkdocs-materials is underselling itself as only a theme imo. It bundles a lot of value that mkdocs is missing out of the box as plugins and tweaks, like a good client-side search, page tags, or easy support for a lot of markdown extensions (e.g. code syntax highlighting, admonitions/callouts).

        From my personal experience mkdocs+mkdocs-material is like GNU+Linux.

        • d4rkp4ttern•2y

          At least for Python documentation, this plus mkdocstrings is great.

      • d4rkp4ttern•2y

        Check out the Pydantic docs pages - they use Mkdocs-material

        https://docs.pydantic.dev/latest/

    • james-bcn•2y

      For science and statistics, I think Quarto is excellent: https://quarto.org

    • dsmmcken•2y

      Thanks, I hadn't heard of Antora, but the behaviours of assembling docs from multiple repos and using branches for versioning is exactly what I want. Too bad it's not using MDX though, as all our existing docs are markdown + interactive react components.

    • Bad_CRC•2y

      I'm a huge user of mkdocs and totally love it.

      I've trying also bookstack and even it's more "wiki" like it's great too for less tech-savvy people (I usually edit my mkdocs projects in vscode and keet them in git repos and bookstack is all web based).

      • ssddanbrown•2y

        > I've trying also bookstack and even it's more "wiki" like it's great too for less tech-savvy people

        Thanks! My main goal when building BookStack was to build a platform that could be used by all departments, of varying technical confidence, of the company that I was working at since existing open source documentation/wiki systems were positioned for a more technical audience.

    • bheadmaster•2y

      I also recommend MkDocs.

      It was the most painless experience I've had with quickly setting up docs from a bunch of .md files, and the plugins give it enough flexibility for most of the usual stuff I need.

  • LeonB•2y

    I used to use gitbook to generate til.secretGeek.net but it got slower and slower over time, would take 45 mins to build the site… and then the parts I was using were either deprecated or made “premium” - something happened. The “enshittification” set in, basically. If there’s some nice free thing you use that’s too good to be true… wait a few years it will go to muck.

    I bit the bullet and wrote my own very minimal static site generator in .net, so the site builds in a few seconds again. Note that I’m not spruiking it for others to use… because if it became popular, no doubt I’d end up enshittifying it too.

    • wumms•2y

      > spruik

      spruik

      - in British English (ˈspruːɪkˈ) [Australian archaic, slang]:

      to speak in public (used esp of a showman or salesman)

      - in American English (ˈspruːkˈ) [Australian slang]:

      to make or give a speech, esp. extensively or elaborately; spiel; orate

      https://www.collinsdictionary.com/jp/dictionary/english/spru...

      • LeonB•2y

        I’m now very self conscious of using the word “spruik” (a feature of Australian culture is that we look down on Australian culture… this is called our “cultural-cringe”) - and just saw “spruik” used in a headline in an Australian news story, which shows it is still a very current word here.

      • LeonB•2y

        Well done. And I am Australian.

  • lwhsiao•2y

    Was using mdbook for a lot of projects, but these days, I feel like material for mkdocs just has so much more built in that makes it nice to use.

    One example, I really like the page TOC on the right side that is notably absent from mdbook, where it seems the standard to set up SUMMARY very detailed and break what could've been a single page into many different files.

    • qbasic_forever•2y

      Yeah material for mkdocs is so good it's worth slogging through a python install/venv to make it work.

    • blooalien•2y

      I been a huge fan of mkdocs for a while now. It really does just get the job done with a minimum of fuss and muss, and has a lotta nice themes to choose from (as well as being fairly easy to customize or build your own).

    • asicsp•2y

      I use https://github.com/JorelAli/mdBook-pagetoc to get Table of Contents for chapters

  • rmrfchik•2y

    Started using mdBook couple days ago for documenting small project. This is exactly what I need: small static pages generator. Tried HUGO, but it seems so huge and bloated comparing to mdBook. Now I edit doc with Obsidian/VIM, push to Gitea and in minute get public documentation.

    • msravi•2y

      I use hugo with the book theme (https://github.com/alex-shpak/hugo-book). It takes a bit of getting used to (if you're not familiar with hugo) but after that it's pretty good with all the flexibility that hugo provides for shortcodes, etc. You can get auto numbering of figures, equations, etc. with appropriate shortcodes. Is it possible to get autonumbering in mdBook?

      It also gives a nice toc/tags on the right side (if you want it), and the ability to split the page into columns. The katex support is good (looks like mdBook uses mathjax) and publishing is easy and is just a push/rsync.

    • bluejekyll•2y

      I’ve started using a plantuml extension for it recently, helps embed architectural diagrams in the docs.

  • eddythompson80•2y

    I recently started exploring, and slowly migrating, to .mdx over .md for content. So far it’s been a breath of fresh air tbh. My biggest problem of markdown was the specific flavor I happen to be using and the type of cliffs I’d run into, then how to extend them.

    I’m extremely satisfied with 80-90% of the standard Gitbook markdown flavor. Then every now and then I really wanna make a complicated table, or a code block highlighting few lines while maintaining syntax highlighting, or an interactive slider, or a formula calculator that’s built-in the documentation instead of a complicated function, or a particular graph/chart etc. I don’t know how something like mdx would work for a large team (ever tried to clone Microsoft’s doc repo?) but at least for my own stuff, it seems like a definite improvement.

    • rapnie•2y

      > My biggest problem of markdown was the specific flavor I happen to be using and the type of cliffs I’d run into, then how to extend them.

      First time I heard of .mdx and looked up the site [0]. I am insufficiently in the loop of frontend standardization. Now it would be great to get rid of flavors and have one universal approach. In the Docs I read:

      > MDX is not coupled to React. You can also use it with Preact, Vue, Emotion, Theme UI, etc. Both the classic and automatic JSX runtimes are supported.

      A sibling comment already mentions a Svelte implementation [1]. So I fail to see how this doesn't open a pandora's box of yet more flavors, this time coupled to frontend frameworks. First in .mdx and then incompatible with .md

      Extensibility. Yes, I guess, if your stack is supported by any of the existing implementations.

      [0] https://mdxjs.com/docs/what-is-mdx/

      [1] https://mdsvex.com/docs

      • friendzis•2y

        JSX is evidence that new generation of programmers are not taught engineering. There are very valid reasons why we went for encapsulation and separation of concerns. JSX throws the baby with the bath water and goes back to PHP5 sites with markup and code interspersed. Even authors of JSX cannot make it work reliably in their flagship product. MDX couples JSX with markdown.

        I cannot see how this yields maintainable source. Sure, spaghetti code is nice for quick, one off scripts, but if you'd volunteer for helpdesk shift to be yelled at rather than fix a bug in 5k SLOC collection of Windows Batch scripts, then maybe you should reconsider mdx.

    • FractalHQ•2y

      I couldn’t agree more. Mdsvex was life changing when I discovered it: https://mdsvex.com

    • FireInsight•2y

      .mdx can be used with https://astro.build/ very easily, which is a JS metaframework and no-JS-shipped SSG-first approach. There are themes you can use, but for any modern web developer it would be pretty easy to roll your own.

  • thangalin•2y

    I wrote KeenWrite, a free and open-source cross-platform tool, to create Markdown-based books. KeenWrite calls out to ConTeXt to typeset the documents and uses my KeenType fork for typesetting math while in preview mode. KeenWrite can generate PDF files from the command-line.

    * https://github.com/DaveJarvis/keenwrite

    For example:

        java -jar keenwrite.jar \
      --all \
      --r-dir=$PWD/bin \
      --r-script=$PWD/bin/editor.R \
      --image-dir=$PWD/images \
      --variables=$PWD/variables.yaml \
      --theme-dir=$HOME/dev/java/keenwrite/themes/boschet \
      --metadata=title={{book.title}} \
      --metadata=byline={{book.author.byline}} \
      --metadata=keywords={{book.keywords}} \
      --metadata=copyright={{book.copyright}} \
      --metadata="reviewer=$1 $2, $3" \
      --chapters="-14" \
      --input="$PWD/chapter/01.Rmd" \
      --output="${TEMP_NAME}"
    That mouthful compiles the book that I'm writing. The book defines numerous variables that are referenced throughout the prose and defined in an external file. Variables can also be passed in as metadata, which tells ConTeXt various PDF properties to embed. The chapters argument allows selecting a subset of chapters to build (e.g., 1-3,5,9-15,22). Lastly, the theme directory points ConTeXt to the instructions to use when typesetting the document, which controls colours, fonts, layout, annotations, etc.

    Some sample outputs:

    * https://github.com/DaveJarvis/keenwrite-themes/tree/main/exa...

  • qwerty456127•2y

    I just wonder why Markdown (or whatever alike, I know there are alternatives superior in numerous ways) is not the default format for books, documents and everything. Some years ago I switched to Typora and discovered I hardly ever need Word/Writer for anything I write and I only use it to open documents others would send me. 90% of books I read don't look like having a serious reason for not being in the Markdown format either. I understand there is typesetting one has to do to print a nice-looking paper book but the majority of the text read on a computer/smartphone or printed from MS/Libre Office lacks this job done anyway.

    • The_Colonel•2y

      Markdown is a really poor storage format. There is quasi-official standard (CommonMark), but since it's feature-poor, people mostly use something else, like GitHub Markdown. Individual apps often extend Markdown in various incompatible ways.

      There are better alternatives (e.g. AsciiDoc, but it's specialized towards documentation), but they don't have anything close to the momentum of Markdown.

      > 90% of books I read don't look like having a serious reason for not being in the Markdown format either.

      Markdown is a late comer to the game, so the better question is - why should books be in Markdown? Markdown's biggest (or the only?) advantage compared to binary/XML based formats is sort-of readability in plain text, but that's just not that important for the majority of publishers and readers.

      • qwerty456127•2y

        > Markdown is a really poor storage format. There is quasi-official standard (CommonMark), but since it's feature-poor, people mostly use something else, like GitHub Markdown. Individual apps often extend Markdown in various incompatible ways.

        I hope GitHub and Obsidian are going to synchronise their MarkDown extensions in near future and this will become The Standard. Whatever a case, anybody can easily write a script to automatically convert any Markdown flavour to another.

        > why should books be in Markdown? Markdown's biggest (or the only?) advantage compared to binary/XML based formats is sort-of readability in plain text, but that's just not that important for the majority of publishers and readers.

        Read anywhere. I mean anywhere. Without a need for software as complex and resource-hungry as a web browser engine ePub would require. I used to read TXT books on a pocket MP3 player during the pre-Android era. Also very easy automated processing.

        In fact my actual preferred format for books is FB2. I mostly convert ePub books to FB2 to read on a PocketBook eInk device because it would use book-specified fonts and pages (which I never want) if I don't and FB2 is sort-of Markdown-like (in terms of its logic and features) XML. FB2 also has a great metadata section to store information about the book.

        And besides books there also are documets. Word/LibreOffice documents others would send me often are real pain to modify as WYSIWYG word processors bundle tons of redundant invisible formatting details for every bit of text even when not asked for.

        “Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.” ©

        • The_Colonel•2y

          > Without a need for software as complex and resource-hungry as a web browser engine ePub would require.

          I know that technology purists love that, but any electronic reading device handles HTML easily (especially the simple HTML in ePubs).

          The point becomes moot when your book contains images/illustrations and you (like a normal reader) want to view them within the content. You will use some Markdown formatter/viewer which is again based on browser.

          > Word/LibreOffice documents others would send me often are real pain to modify as WYSIWYG word processors bundle tons of redundant invisible formatting details for every bit of text even when not asked for.

          Markdown is just insufficient for any non-trivial document. There isn't any standard way to set image size for example. There's no standard way to create even rudimentary tables.

          > “Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.”

          Then go for plain text. All those headings and asterisks are a distraction anyway. Years ago, many e-books used to be distributed in plain text in fact.

          • qwerty456127•2y

            > Then go for plain text. All those headings and asterisks are a distraction anyway. Years ago, many e-books used to be distributed in plain text in fact.

            Markdown is more semantic. E.g. it gives you a ToC (a very important feature of a good book, and it has to be semantic markup-based when you decouple the text from the view by omitting explicit pagination) for free.

            • The_Colonel•2y

              HTML is also semantic. It also has a good standard, its support is omnipresent, is extensible, actually supports tables etc.

              • qwerty456127•2y

                Isn't Markdown meant to be lightweight HTML with shortcuts to declutter it visually? Afaik it even is considered officially correct to use HTML tags in it when necessary.

    • giraffe_lady•2y

      There is a lot of nuance and complication to typesetting books that isn't apparent to an untrained observer, and markdown + css simply isn't sophisticated enough to handle it. Even html/css + js is technically capable but far far behind the state of the art in digital typesetting.

      This is also a very classic "well I could do it better" engineer trap so please don't assume that without some research. It's an ancient domain relative to what we're talking about here and has accumulated a lot of valuable insight & technique that should not be simply discarded because markdown is almost good enough for some things.

      • gglitch•2y

        Do you have recommendations? (La)TeX, maybe, or *roff?

        • giraffe_lady•2y

          I don't have any professional typesetting experience, just some adjacency from having done some work for a type foundry at one point, that gave me some insight into how much actually goes into it.

          Most professionals use expensive professional software for it. Latex or pollen or other pure markup solutions only work for smallish documents, or digital ones. Once you're going to print, esp in different formats, you need to care about page imposition, aligning with folios & signatures, widows & orphans etc. Just generally the physical reality of paper leaking into your abstraction of "the book" in ways markup alone can't accommodate.

    • ghnws•2y

      That looks like a great tool!

      I write a lot of documentation as part of my job and having Markdown side by side with the rendered output is great. Once you get the hang of the syntax, markdown is so much faster to write than using any text editor like Word. Just writing a list in text editors is painful.

  • asicsp•2y

    I found mdBook easy to use, especially like that users can choose themes. I primarily use it for online version of my ebooks [0] and curated resources [1][2]

    [0] https://github.com/learnbyexample/scripting_course#ebooks

    [1] https://learnbyexample.github.io/py_resources/

    [2] https://learnbyexample.github.io/curated_resources/

  • still_grokking•2y

    Tangent question: What are currently viable Markdown alternatives?

    Imho Markdown is a overall terrible and (especially regarding technical writing!) very limited format. But nothing else seems popular. Why actually?

    Are there any realistic alternatives?

    Thanks for some hints!

    • zoogeny•2y

      In all seriousness, HTML started out as a markup language for documents. That is why tags like <p> for paragraphs and <b> for boldness etc. are so prominent.

      If you aren't trying to build a SPA or something like that and you just want to mark up some text for formatted output ... HTML is kinda made for that task.

      That being said, I tend to stick with Markdown since I find angle bracket tags to be noisy and distracting when I view documents in plain text.

      • hoofhearted•2y

        Yes! I agree with this!

        It’s just plain old dumb boring static text that is being moved around the web.

        The internet was essentially created so that CERN could share plain old text documents with others remotely.

        Why do I need a big bloated overly complicated PHP webserver that talks to an overly complicated database, when it’s just plain old static text after all?

    • tpreetham•2y

      org-mode is a brilliant format. The limitation is that you would have to use Emacs or something which support .org files.

      https://youtube.com/playlist?list=PLVtKhBrRV_ZkPnBtt_TD1Cs9P...

      • still_grokking•2y

        What else besides EMACS supports .org files?

        Form the alternatives I've seen so far it looks best. But EMACS? (I'm on Linux, but never liked EMACS or Vi(m)).

        The second best looking alternative seems AsciiDoc. It has some more tooling as I see it.

        But really like the .org syntax best so far. So any recommendations for tooling?

        • BenFeldman1930•2y

          AsciiDoc still has no footnotes, but only endnotes. Therefore not really useful for writing non-fiction books. As org-mode files are only text files, you can use any editor you like. If you want all the goodies (agenda, TODOs etc), you have to use Emacs, yes.

          • still_grokking•2y

            > AsciiDoc still has no footnotes, but only endnotes.

            Does Markdown have footnotes or endnotes? No?

            People are still misusing it for everything! Especially for technical writing, which is just nuts.

        • •2y
          [deleted]
    • pie_flavor•2y

      Markdown is a formalization of formatting conventions that people were using well before it was invented as a separate product. It was slightly different - the link syntax was novel, and asterisks usually meant bold instead of italics - but it was close enough that the allure of 'your reflexes still work' held. Nothing else is as popular as Markdown because it isn't actually Markdown that's popular, it's what preceded it.

      Personally I'm happy for it because it'll finally stop programming languages from inventing their own domain-specific oddly-syntaxed subset of HTML; the way Rust uses it is something others have no reason not to copy. For your own technical writing, AsciiDoc works pretty well.

    • BanazirGalbasi•2y

      > But nothing else seems popular. Why actually?

      I think markdown's popularity comes from its simplicity. For things like bulleted lists, especially nested ones, I can just type an asterisk and keep going. The raw input is still very readable (for the most part) and adding formatting is quick and easy. For anything basic - such as chat systems, social media posts/comments, or quick note systems - I don't think anything more is needed.

      Something like reStructuredText (.rst) is a similar alternative, but I think that if you're irritated by the limits of Markdown then rST isn't going to be any better. If you really want good formatting options, then LaTeX is the best I can think of at the moment.

    • toastal•2y

      In the future, Djot might be up to the task, but currently it’s more fixing issues with Markdown & roadmapping improvements.

    • letmeinhere•2y

      AsciiDoc, org-mode, ReStructured Text are some of the other light markup contenders

  • usrme•2y

    I haven't seen the newcomer Starlight[1] being mentioned, so just throwing that out there as well. It's by the wonderful folks who created Astro[2] and my own limited usage of it has been great!

    [1]: https://starlight.astro.build/

    [2]: https://astro.build/

    • ElCapitanMarkla•2y

      My friend introduced me to Astro the otherday. I have a few Gatsby projects under my belt but I could never really get into it, Astra looks fantastic compared to it

  • harry8•2y

    Way to bury the lede.

    Like gitbook but Free.

    The rust zealotry put me right off fwiw. As it does my interest in the language itself. I wish those guys would calm down they're totally detracting from whatever the strengths of rust are with that nonsense.

    edit: gitbook pricing for comparison https://www.gitbook.com/pricing

    • rapnie•2y

      I don't think it is zealotry. They offer features explicitly for Rust programmers, and the major examples of the project's use are by Rust itself.

      > Automated testing of Rust code samples

      > mdBook is used by the Rust programming language project, and The Rust Programming Language book is another fine example of mdBook in action.

    • valbaca•2y

      What zealotry? Rust isn't mentioned until the last two points of eight:

      mdBook is a command line tool to create books with Markdown. It is ideal for creating product or API documentation, tutorials, course materials or anything that requires a clean, easily navigable and customizable presentation.

      - Lightweight Markdown syntax helps you focus more on your content - Integrated search support - Color syntax highlighting for code blocks for many different languages - Theme files allow customizing the formatting of the output - Preprocessors can provide extensions for custom syntax and modifying content - Backends can render the output to multiple formats - Written in Rust for speed, safety, and simplicity - Automated testing of Rust code samples

      It mentions Rust because it's written in Rust and used by the Rust project.

      In other words, the project wouldn't exist without Rust but

      • harry8•2y

        > What zealotry?

        The headline has been silently edited, hence the confusion. I don't much care for silent editing for just this reason.

    • xcdzvyn•2y

      I think they'd be best served not using the words "Rust" nor "GitBook" in their marketing, given it lacks most of the features of GitBook (that's probably why it isn't free!); mdBook appears to just be a static site generator.

  • gilmi•2y

    I've written an online book with mdbook (https://lhbg-book.link) and it was a breeze. I believe mdbook was one of the reasons I even finished the book.

    1. It's super easy to install. If you have a rust toolchain, just `cargo install mdbook`

    2. One command to initialize: `mdbook init my-book`

    3. One command to get immediate continuous feedback: `mdbook serve`

    4. It allowed me to keep writing in my preferred environment (emacs)

    5. It looked good by default. I could focus on the content.

    6. Setting up auto deploy ci on github is about 30 lines for yaml

    Though one point of improvement would be better support for other export formats such as pdf and epub.

    tl;dr mdbook allowed me to use the path of least resistence to complete my project, and I highly recommend it.

    Also it is possible other platforms can do the same or better but I haven't tried them.

    • mraza007•2y

      I have been planning to learn haskell thanks for sharing the book

  • pietroppeter•2y

    Md book is great! We created a Nim version to support content written with nimib (a framework to publish html pages with Nim code and its results) and it has been very useful! https://pietroppeter.github.io/nimibook/index.html

    As people are sharing other SSG (I think material for MkDocs is the absolute best for documentation sites), let me share a relatively unknown one that I find very interesting: https://github.com/dmulholl/ark

    I have as next project to try and port this ark to Nim/nimib (and ideally nimibook should be refactored to use it).

  • mr_o47•2y

    I have been using Mdbook for a while and its been great,

    I maintain a simple knowledge base for myself https://til-mraza007.vercel.app/

    I love how simple it is

  • dylanowen•2y

    I love MdBook. It's also dirt simple to customize it with plugins or rendering backends: * https://github.com/dylanowen/mdbook-graphviz * https://github.com/dylanowen/mdbook-confluence

  • pickledish•2y

    Since I see a few people in these comments mourning the general dive that gitbook has taken over the last few years, you might like this, an actively-maintained fork of gitbook as it was before it got bad:

    https://github.com/honkit/honkit

    I don’t spent a lot of time looking at these SSGs, so this one’s still my favorite

  • throwawaaarrgh•2y

    > It is ideal for creating product or API documentation, tutorials, course materials or anything that requires a clean, easily navigable and customizable presentation.

    Markdown is really crap for any of that.

    Any real writer knows that the best way to communicate an idea quickly and effectively is to present it the right way. Markdown does not have good presentation. It was not designed for good presentation. It was designed to write an incredibly basic-looking document, such that the plaintext and rendered document look similar.

    I know this is going to be a shock to everyone. But it turns out that ASCII isn't the best way to encode presentation. On behalf of the poor SOBs that have to read what you churn out: Please stop subjecting people to your shitty presentation and get a real document format. Thanks.

    • rcarmo•2y

      I disagree. All it takes is a CSS file, some semantic HTML in the right places and some inline Mermaid diagrams and you have a pretty decent document. I routinely write one-pagers, memos and architecture summaries in Markdown and generate PDFs with weasyprint (or even just iOS’s print to PDF feature), and all I use is a print CSS file and whatever JS is required to render the diagrams.

      I would love to not use a browser engine at all (and moderately detest Mermaid because it cannot work fully in-memory without instantiating one), but it works.

    • toastal•2y

      > *Note:* my complete disregard for <blockquote> semantics because I wanted to put a box around something, but my lightweight syntax doesn’t offer richer features

      ##### This

      * is not a

      * definition list

    • chrisco255•2y

      You know that HTML is valid in Markdown, right?

      • •2y
        [deleted]
  • hoofhearted•2y

    I have used a number of different solutions over the years for simple documentation. Started with Wordpress, ended up on Docusaurus.

    Docusaurus is an amazing tool for startups, but it started to show its weaknesses as we tried to scale it.

    Our project requirements needed something more, so I ended up forking Docusaurus and started working on my own free open-source solution.

    Check it out, I’d love to hear what everyone thinks! :)

    https://github.com/elegantframework/elegant-cli

    https://www.elegantframework.com/docs/installation

  • js2•2y

    For producing online documentation, how does this compare to MkDocs?

    • klodolph•2y

      I’ve used both, I recommend MkDocs over MdBook for most people. MdBook is simpler and easier to get started with, MkDocs has more features, more plugins, more themes. Both MkDocs and MdBook are easy to use. IMO, MdBook is a little too simple.

      Recommend using the material design theme for MkDocs as a starting point. If you are working on a Rust project, use MdBook instead. If you have lots of docs / multiple projects / multiple versions, use Antora. If you want cooler landing pages, use Jekyll.

    • potatochup•2y

      Embarrisngly, I'm using both for docs at work (they were both projects I started).

      Mkdocs is more flexible, has more themes, better ecosystem. Mdbook has better defaults, easier deployment, is more standard across rust projects

  • csk111165•2y

    It suggest that , when I use build command it gives html files, what if I want to compile all these in PDF format? Since PDF format is quite suitable for all the ebooks

  • d4rkp4ttern•2y

    Anyone know what Qdrant uses in their doc pages? I really like the style.

    https://qdrant.tech/documentation/quick-start/#

  • gbraad•2y

    I used to do this with GitBook, but it has not seem active development for some time. Wonder how easy it would be to move from GitBook to an Obsidian workflow with mdbook. The links are written like a wiki as [[]]. Would this tool understand?

  • ShadowBanThis01•2y

    Why? I'm mystified as to why there are vanishingly few VIEWERS for Markdown. One open-source project after another offers up .md files for documentation, but have you ever tried to find a plain VIEWER for Markdown?

    • glebd•2y

      Marked 2 https://marked2app.com/ is a dedicated viewer for Markdown and other text formats, but it's Mac only.

    • wwtdtgotiatl•2y

      vscode has one built in

        ctrl + shift + v
      • ShadowBanThis01•2y

        Thanks, but I mean a dedicated viewer… not an editor that has preview capability. There are several of those.

        Just a lightweight viewer.

  • freediver•2y

    Shout out to MdBook, this is what powers Kagi documentation currently.

    https://help.kagi.com/kagi/index.html

  • bad_username•2y

    > The options and formatting will be different for other output formats such as PDF.

    This is the only reference to PDF in the documentation. Is it possible to render a PDF (presuming a single file)?

  • ra1n•2y

    I have been wondering about using a set of *nix tools backed by a git repository as a planner/diary. This tool seems to be an interesting addition for the presentation front.

  • stonecharioteer•2y

    I use Sphinx with the Furo theme for stonecharioteer.com, and I prefer RestructuredText over markdown, but I get why markdown is more approachable.

  • novakinblood•2y

    My unconscious bias made me read this as “Maryland Book”.

  • xwowsersx•2y

    Me: Are we past "x but in Rust" where Rust is a totally irrelevant internal detail I don't — nor should anyone — care about?

    [Checks HN]: Nope.

    • kinghajj•2y

      Eh, in this case it's a tool created by Rust programmers for generating documentation for the Rust language, and has particular features for validation of Rust code snippets in said documentation. I think in this case, mentioning Rust in the description is reasonable.

    • liberty-dreamer•2y

      Well, if it is implemented in Rust, then who cares whether it works or not? It's implemented in Rust!

      • metabagel•2y

        The good thing is you don’t have to rewrite it!

    • timeon•2y

      I hope not since I use it as keyword filter in my RSS feed. Why are you bothered?

    • valbaca•2y

      It matters in that it helps people contribute, which contributes to growth.

      Oh. and it's free.