Hacker News Reader

Comment by Kolja | Hacker News Reader

I thought so, too. I've switched to mdbook[1], which is more lightweight, and (at least at the time) was one of the few solutions that compiled down to a directory that can be used without limitations while offline.

[1]: https://rust-lang.github.io/mdBook/ – the website itself is a demo of the sites produced by mdbook.

View on HN

Docusaurus has a PWA plugin with offline support

https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-pw...

We'll look into more "offline supports" in the future including producing pdf files etc (it already exists but as community plugins)

I'm sure that Docusaurus can do a lot, and more in the future. I think the resulting pages feel a little heavy to use (how they load and react in a browser), but that's just my personal opinion.

I had tried to find a tool that would be simple, quick to use, and as close to a static HTML page as possible while still retaining a "book" character. Even a Vimwiki HTML export would have been an option, were Vimwiki's Markdown support better. Mdbooks fit the bill, and does not seem to stray too much from that initial direction, as far as I can tell.

Just curious whether rust is an advantage for this sort of a tool? I don't know much about rust but my impression is that it's a systems language like C/C++. Is security a major problem for this sort of a build tool? It just seems like of I were writing something that processes text using a C/C++ class language isn't going to maintain well or be easy to adapt, extend or customize.

IMHO Rust is useful for its speed. Many frontend tools use Rust today (like swc, napi-rs...).

We are willing to include Rust in Docusaurus in the future (alongside Node.js), as it can help to build the static doc site faster. BTW our docusaurus prod site (docusaurus.io) is built using swc already (https://swc.rs/)

Now using a 100% Rust tool to build a doc site would be great too, but at the end of the day if you want a great experience you'll also need some JS and not just plain static HTML files. And Rust devs are more likely less "frontend-y" (I've been a backend Scala dev 10 years ago, I know how good looking UIs are produced by backend devs ^^). So I guess a combination of Node.js + Rust is great, and the frontend community that care about UI/UX is more likely to contribute to the JS side to polish things.

I guess I'm just thinking in terms of these tools as being text in, text out transformers. And it seems like an embarassingly parallel workload. So speed seems like the wrong thing to optimize to me.

I am not able to understand what you mean here sorry. What is the thing to optimize then?

Time required for customization, feature implementation and maintenance should be minimized. Documentation generation often needs to be extended and customized. So the question is how much developer time gets sunk into adapting the tooling vs buying CPU time.

We optimize for features, easy of customization and easy of upgrades in priority

Now we have large docs sites with thousands of pages, and it's painful if their static site takes forever to build, so we should also optimize for speed. Build-time speed reduces the feedback loop and it also saves developer time. It's like having a better computer somehow.

I'm confused. Is docusaurus implemented in a system's programming language such as rust or C/C++? Wouldn't the easiest way to improve build time be to get a parallel build system (assuming it doesn't have one) and then throw more CPUs at it?

We build a single page application and use Webpack (nodejs build tool to create SPAs). In 2018 there weren't many alternatives to Webpack so we pick that, but may reconsider in the future. We don't have the bandwidth to create our own frontend build tool, we focus on the features.

Docusaurus is also IO intensive as we read a lot of markdown files on the disk and also emit intermediate files.

Webpack already builds things in parallel, but it remains nodejs, and IO/CPU are both bottlenecks at different steps of our build.

No idea, actually (not a Rust developer myself). What I have noticed is that Rust seems to provide good tooling for building monolithic executables that contain a complete application, including assets. That's quite nice for trying stuff out or managing a few of those without a package manager, but has nothing to do with documentation generation per se.

Oh, that's nice and I do agree about that! I've noticed go does that sort of thing, too (hugo, etc).Some of these systems out there include so many moving parts that it's really difficult to just even try them out (i.e. supabase vs pocketbase).

Reply on news.ycombinator.com