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?
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.
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.
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.
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.
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.
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?
25 comments
[ 2.7 ms ] story [ 65.9 ms ] thread> 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?
[1]: https://github.com/egoist/tokio
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.
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.
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 know what markdown is.
[0] https://github.com/myles/awesome-static-generators
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
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/...
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?