Show HN: Docute – Fast way to create a documentation site | Hacker News Reader

Show HN: Docute – Fast way to create a documentation site

docute.org

81 points0x14285725 comments

I don't get the point. Why is javascript required for this? Static site generators are a thing that exist, and solve this problem a lot more reliably than this will.

No build step. That’s the advantage.

There is though. Every time someone visits a page.

There are no server side components.

This appears to be a static site generator in that regard. Just that it outputs a single-paged app as opposed to a linked directory.

Static site generator is a very well defined thing. Content, static pages out.

This isn't 'generating static pages'. It's rendering a page every time you access it, you've just moved the rendering to the browser's JS runtime.

I don't get what the fear around building is. Many static site generators don't even require you to install additional toolchains[0], so churning out static HTML content from markdown should be just as easy.

It's better to spend just a couple minutes setting up a static site generator into your workflow than to have every user who pulls up your STATIC website perform template rendering and all that garbage. I know computers are fast and it doesn't seem like it really makes that much of a difference, but thinking like this often leads to inefficiencies in other applications as well.

[0]: https://github.com/keats/gutenberg

I mean it's hard to compete with installation instructions as simple as "commit this file in the root of your docs/ directory" and point GH pages at it.

All though I agree with the JS comment. It's still an interesting idea to generate a document hub from markdown. This makes a lot of sense. I do agree again that the JS is a bit overboard but I'm not that turned away by it.

What regular SSG wouldn't let you do the same? A SSG is ridiculously simple to hookup to a CI/CD chain to publish changes once pushed to the repo.

If I knew what the acronyms meant, maybe I could tell you. https://en.wikipedia.org/wiki/SSG

??? I know what markdown is.

Static site generator?

[0] https://github.com/myles/awesome-static-generators

I built a documentation-orientated static site generating CMS that acts as a git repository.

I lost a bit of momentum with the project as I had paid work to do, but in the meantime the landscape has filled up with competition.

https://www.graphia.co.uk

I agree entirely, here is a great example of documentation created with static CMS https://marketplace.getpublii.com/products/documentation/

Thanks for making this, it looks very nice and I’m always looking for things like this.

> renders them as a single-page application.

The problem with SPA’s is that unless there’s server-side-rendering with routing, they will not be reliably crawled by search engines.

One of the benefits of having published documentation is that each page gets indexed by google and so each page is essentially a hyper-targeted marketing page with specific keywords.

Just wanted raise a concern I’ve experienced with hosting websites as SPA’s. I see in your comparisons you list other tools that render static HTML. Do you think in your roadmap you would have an option to export a directory of HTML pages?

> If you care about SEO, you may like using tokio [1] to prerender your website.

[1]: https://github.com/egoist/tokio

Yes, indeed. Routing on SPA's is HARD. Especially in production. One of these things you have to experience before you fully appreciate.

I've found mkdocs to be fantastic for this, especially when paired with its material theme:

https://www.mkdocs.org/

https://github.com/squidfunk/mkdocs-material

There's a docker image that makes getting started with both quite easy:

https://squidfunk.github.io/mkdocs-material/getting-started/...

It seems that mkdocs is a generator that requires a build step. Docute does all of that work clientside at render time, according to TFA. That makes it compatible with ipfs with no additional build step, which I think is super cool.

Alternatively, this is much, much better: https://docusaurus.io/

How is it better? Does it do the same thing?

If you write your docs in RST or Markdown, readthedocs is also a great choice. With a GitHub webhook they'll automatically build and publish your docs. Point your own domain at it and it couldn't be easier.

Wow, this is beautiful and so simple to start using, I will give it a try.

Not having a build step makes life 100X easier.

We use a similar system (based on UI kit) but I've found Docsify and Docute to be much easier/cleaner.

One really cool thing is we added a "interactive coding tutorial" system to the MD renderer, letting you do some pretty powerful documentation demos (see https://gun.eco/docs/Todo-Dapp for example).

This should be able to be packaged up as a plugin for docsify/docute, anybody interested in helping, so other projects can use it out of the box?

HN hug of death ?

Just a heads up, website is down for me.

Reply on news.ycombinator.com