Show HN: Docup – single-page documentation for your open source projects | Hacker News Reader

Show HN: Docup – single-page documentation for your open source projects

docup.now.sh

53 points0x14285716 comments

Why would you choose that over a simple static site generator that converts a markdown file into a static html file that works without JavaScript and doesn't cause any problems for search engines?

This one command does just that and you don't have to "prerender" your pages in an "additional build step" as suggested in the other comment.

pandoc -f markdown -t html5 -o output.html input.md -c style.css

That command is essentially what I mean by "prerender".

I will add this feature to docup later, for people who want to have a static html file instead.

So why all that extra work when in the end the only feature of Docup that would be used is the CSS which could also just be fed into pandoc?

First it's for people who don't want a build step, but they can prerender if they want.

And it does more than adding some CSS, JavaScript is also used for interactions.

Except that you (and everyone in your team/contributor) needs to have pandoc installed when updating the docs. I wrote mdwiki (http://mdwiki.info) ages ago to exactly avoid this.

How will it cope when content starts to grow? It will require a massive single request to fetch the content and then JS will have to build the interface.

Like other commented, better split pages and prefer pre-rendering. Documentation is something I usually need immediately and I really don't care how pretty it looks.

Yea this is my thought. Any sizable project will have enough documentation to make this one page approach unwieldy IMO. MkDocs Material is all I'll ever need for documentation. https://squidfunk.github.io/mkdocs-material/getting-started/

works pretty well for lodash. https://lodash.com/docs/4.17.15

it's indeed a problem for large-scale docs, that's why I have another solution here https://docute.org/

Very nice. In a similar vein, I've used https://ricostacruz.com/flatdoc/ before, which is a bit more full featured and includes support for code samples.

Nice! this one is also quite good https://docsify.js.org/#/

The updating on the left hand side is pretty jarring. If it must be done, can it be scrolled over time instead?

yes, already working on a fix.

Out of curiosity, is it search engine crawlable?

yes, google supports js, not sureabout the others.

you can prerender you website anyways, if you don't mind a build step

Reply on news.ycombinator.com