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.
MdBook – A command line tool to create books with Markdown
41–50 of 123 posts
Re: MdBook – A command line tool to create books with Markdown
#42> 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.
Re: MdBook – A command line tool to create books with Markdown
#43Why? 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?
Re: MdBook – A command line tool to create books with Markdown
#44IIRC, 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.
Re: MdBook – A command line tool to create books with Markdown
#45> 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…
> *Note:* my complete disregard for
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
Re: MdBook – A command line tool to create books with Markdown
#46I’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. - Ant…
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…
Re: MdBook – A command line tool to create books with Markdown
#47I 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?
Re: MdBook – A command line tool to create books with Markdown
#48I'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 environm…
I have been planning to learn haskell thanks for sharing the book
you welcome :)
Re: MdBook – A command line tool to create books with Markdown
#49I 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 bloc…
.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.
Re: MdBook – A command line tool to create books with Markdown
#50I’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. - Ant…
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).