11–20 of 123 posts
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.
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
> 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.
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.
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.
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.
I maintain a simple knowledge base for myself https://til-mraza007.vercel.app/
I love how simple it is
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 bloc…
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.
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.
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.
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.