Documentation requires JavaScript

[iv-org]

Documentation requires JavaScript

[TheFrenchGhosty]

This was already discussed in the Matrix room months ago, but I'll explain it here:

I am the one who recommended WikiJS, I know that the fact that it's a JS frontend is a bad thing, and I perfectly agree with people who think it's a bad idea.

However it's sadly currently the only wiki software that does something that ease things for us:

We want a documentation website that can pull it's content from a git repository so that the VPS isn't "critical" and can be replaced without data loss. We want a documentation written in "standard" markdown.

WikiJS is the only one that can do that.

Personally, I also wanted an included editor, WikiJS has that.

Obviously, it's not ideal, but feature wise WikiJS is the only one that does what we want.

Obviously if one day, a documentation project works without JS and does those things we will move to it... until then, it's WikiJS.

If you really don't want to enable JS you can read the documentation directly from the git repo/Github.

[smithfred]

Why not use something like Sphinx to generate static HTML from Markdown? It can be self-hosted, or auto-generated by and hosted on Read the Docs or similar.

• We want a documentation website that can pull it's content from a git repository
• We want a documentation written in "standard" markdown.

What am I missing?

[TheFrenchGhosty]

The standard markdown isn't displayed this way, it's HTML generated from markdown, it's not great.

[smithfred]

It's always going to be HTML generated from Markdown (unless you're doing something insane like drawing directly on a <canvas> element). You're either generating HTML server-side from the Markdown, or generating it client-side via JS.

Not great how?

[TheFrenchGhosty]

We're generating HTML from the markdown and we're using those HTML files, we're not directly using the markdown files. This is what isn't great.

[smithfred]

The Markdown files are not being used directly either way. Web browser do not have built-in Markdown renderers. WikiJS is just client-side rendering from Markdown to HTML every single time, on everyone's machine individually, instead of once on a server when something changes in the relevant repo. It's an incredibly inefficient and pointless exercise, reinventing a worse wheel than the original (serving HTML to be rendered directly).

This is what isn't great.

Why?