Avoid npm/node dependency #239

zander commented 2022年07月04日 00:34:19 +02:00

The documentation project currently requires the documentation writer to have a javascript developer environment installed in order to see the results of their work.
I'm personally not one of those that has this, or wants this, installed and I kind of expect a lot of documentation writers to be in the same boat.

My first response was, why not use the most used static-site generator hugo (gohugo.io) which is simply one executable on Windows and packaged for Linux.

Is this something people are willing to entertain?

The documentation project currently requires the documentation writer to have a javascript developer environment installed in order to see the results of their work. I'm personally not one of those that has this, or wants this, installed and I kind of expect a lot of documentation writers to be in the same boat. My first response was, why not use the most used static-site generator hugo (gohugo.io) which is simply one executable on Windows and packaged for Linux. Is this something people are willing to entertain?

fnetX commented 2022年07月04日 00:58:33 +02:00

I don't have a strong opinion on that. I can understand your points, I'm no fan of the whole JS ecosystem however (crazy enough we have it in the browser, no need to use it even more IMHO), but I think we can also save the effort and do something more useful instead.

We already invested some time e.g. in redirects and some other features, but what might be worth would be considering a switch that

• solves the issue of translations #136
• adds search #23
• allows easier syncing with upstream Gitea docs #134

There are other alternatives out there. I don't think it makes much difference whether you use e.g. Python or JS, and I don't know if e.g. Hugo has all the benefits. If we switch, we should make sure that it has a larger advantage.

I don't have a strong opinion on that. I can understand your points, I'm no fan of the whole JS ecosystem however (crazy enough we have it in the browser, no need to use it even more IMHO), but I think we can also save the effort and do something more useful instead. We already invested some time e.g. in redirects and some other features, but what might be worth would be considering a switch that - solves the issue of translations #136 - adds search #23 - allows easier syncing with upstream Gitea docs #134 There are other alternatives out there. I don't think it makes much difference whether you use e.g. Python or JS, and I don't know if e.g. Hugo has all the benefits. If we switch, we should make sure that it has a larger advantage.

zander commented 2022年07月04日 16:03:12 +02:00

Hello,

I agree that depending on python doesn't solve too much. More people will have it, but maybe thats going sideways instead of up.

I'm not married to Hugo, its just what I know as I've been maintaining some medium size websites in it. Its also got quite a large community which is useful for continuity.

Translations is indeed solved quite nicely with this. You simply have pageName.de.md next to your default langauge pagename.md the result is that you get a subdir /de/ that copies the main language.

Search may be easier using hugo because you can create a different output format, next to the standard HTML you can creae a JSON "website" (one massive file). I used that in the past to feed it to algolia and provide the javascript on the website to search that.
So, while not a full solution (depends on a closed service) it does help.

Last question, sync with gitea. I might be wrong but this looks like it may be about their 'website' repo, which should indeed be easy as that actually uses hugo already;
https://gitea.com/gitea/website/

Hello, I agree that depending on python doesn't solve too much. More people will have it, but maybe thats going sideways instead of up. I'm not married to Hugo, its just what I know as I've been maintaining some medium size websites in it. Its also got quite a large community which is useful for continuity. Translations is indeed solved quite nicely with this. You simply have `pageName.de.md` next to your default langauge `pagename.md` the result is that you get a subdir /de/ that copies the main language. Search may be easier using hugo because you can create a different output format, next to the standard HTML you can creae a JSON "website" (one massive file). I used that in the past to feed it to algolia and provide the javascript on the website to search that. So, while not a full solution (depends on a closed service) it does help. Last question, sync with gitea. I might be wrong but this looks like it may be about their 'website' repo, which should indeed be easy as that actually uses hugo already; https://gitea.com/gitea/website/

zander commented 2022年07月04日 23:03:14 +02:00

Currently the docs are rendered using the "Pages" service from gitea, which results in annoying bugs like Codeberg/Community#640

Using a static page generator like hugo would simply generate a bunch of html files that you can put behind any off the shelf webserver (like nginx).

Sounds like a win to me ;-)

Currently the docs are rendered using the "[Pages](https://codeberg.org/Codeberg/pages-server)" service from gitea, which results in annoying bugs like https://codeberg.org/Codeberg/Community/issues/640 Using a static page generator like hugo would simply generate a bunch of html files that you can put behind any off the shelf webserver (like nginx). Sounds like a win to me ;-)

TylerLinuxDev commented 2022年07月04日 23:54:34 +02:00

I don't have a strong opinion on that. I can understand your points, I'm no fan of the whole JS ecosystem however (crazy enough we have it in the browser, no need to use it even more IMHO), but I think we can also save the effort and do something more useful instead.

We already invested some time e.g. in redirects and some other features, but what might be worth would be considering a switch that

• solves the issue of translations #136
• adds search #23
• allows easier syncing with upstream Gitea docs #134

There are other alternatives out there. I don't think it makes much difference whether you use e.g. Python or JS, and I don't know if e.g. Hugo has all the benefits. If we switch, we should make sure that it has a larger advantage.

As for Hugo, there are some overhead involved for configuring it to generate documentation with search feature built in, translation configured, and finally syncing with upstream gitea docs could be done since Gitea documentations are written in markdown which is supported in Hugo.

I think it's worth the payoff, although it might require some significant initial investment on configuring Hugo web at first. Maintenance would be a breeze though.

> I don't have a strong opinion on that. I can understand your points, I'm no fan of the whole JS ecosystem however (crazy enough we have it in the browser, no need to use it even more IMHO), but I think we can also save the effort and do something more useful instead. > > We already invested some time e.g. in redirects and some other features, but what might be worth would be considering a switch that > > - solves the issue of translations #136 > - adds search #23 > - allows easier syncing with upstream Gitea docs #134 > > There are other alternatives out there. I don't think it makes much difference whether you use e.g. Python or JS, and I don't know if e.g. Hugo has all the benefits. If we switch, we should make sure that it has a larger advantage. > As for Hugo, there are some overhead involved for configuring it to generate documentation with [search feature](https://gohugo.io/tools/search/) built in, [translation](https://gohugo.io/content-management/multilingual/) configured, and finally syncing with upstream gitea docs could be done since Gitea documentations are written in markdown which is supported in Hugo. I think it's worth the payoff, although it might require some significant initial investment on configuring Hugo web at first. Maintenance would be a breeze though.

n commented 2022年07月05日 19:01:20 +02:00

I agree that using Hugo would be a better experience for newcomers. However, like Otto said, we can save the effort for something more useful. Personally, I'm not interested in working on that right now and am comfortable with Eleventy. If anybody is considering working on switching to Hugo, let's talk.

Currently the docs are rendered using the "Pages" service from gitea, which results in annoying bugs like Codeberg/Community#640

Using a static page generator like hugo would simply generate a bunch of html files that you can put behind any off the shelf webserver (like nginx).

Sounds like a win to me ;-)

Eleventy is a static-site generator too :)
Those errors are a seperate issue.

I agree that using Hugo would be a better experience for newcomers. However, like Otto said, we can save the effort for something more useful. Personally, I'm not interested in working on that right now and am comfortable with Eleventy. If anybody is considering working on switching to Hugo, let's talk. > Currently the docs are rendered using the "[Pages](https://codeberg.org/Codeberg/pages-server)" service from gitea, which results in annoying bugs like https://codeberg.org/Codeberg/Community/issues/640 > > Using a static page generator like hugo would simply generate a bunch of html files that you can put behind any off the shelf webserver (like nginx). > > Sounds like a win to me ;-) Eleventy is a static-site generator too :) Those errors are a seperate issue.

f0sh commented 2023年07月05日 10:39:02 +02:00

I would also vote in favour of a different generator. I am very agnostic to which one, but I share the opinion to avoid npm/node dependencies in the long run.

• Hugo seems fine for me
• mkdocs isn't bad either

I think migration could be done with lesser effort, as all documentation is already in markdown with very little exceptions (ToC, images). But I agree, that's low prio.

Maybe together with #136? As I have no idea how to implement multi-language with Eleventy.

I would also vote in favour of a different generator. I am very agnostic to which one, but I share the opinion to avoid npm/node dependencies in the long run. - Hugo seems fine for me - [mkdocs](https://github.com/mkdocs/mkdocs) isn't bad either I think migration could be done with lesser effort, as all documentation is already in markdown with very little exceptions (ToC, images). But I agree, that's **low prio**. Maybe together with #136? As I have no idea how to implement multi-language with Eleventy.

pat-s commented 2024年06月12日 11:37:21 +02:00

The point of using a different site generator has been discussed multiple times here, without a clear decision so far. Given that PR previews are not in place, one does not need to have a local JS env installed to see a preview of the changes.

This should suffice for now and the general discussion should continue in #409.

The point of using a different site generator has been discussed multiple times here, without a clear decision so far. Given that PR previews are not in place, one does not need to have a local JS env installed to see a preview of the changes. This should suffice for now and the general discussion should continue in #409.