Render Documentation to static website
This is a issue for tracking the progress on creating a lean and friendly statically-generated website for our Documentation.
I volunteered to make a prototype in https://codeberg.org/lhinderberger/codeberg-docs-prototype and will make a pull request here once #15 has been decided on.
I will post updates about major progress here.
Feel free to put questions or suggestions to the new prototype here or in the issue tracker of the repo above.
The menu definitely looks better with Rubik Regular. With Light is was hard to read.
I personally think the block of text looks better in Light though 😉
The most recent commit now features an automatically generated menu from the first two hierarchy levels of the files in
src/articles. It also renders responsively across desktop and mobile devices.
It is currently using the menu structure as seen in the screenshots, but it can be adapted to the structure of #16 or vice versa when adding actual documentation content.
This means all essential major functions (except i18n) have now been implemented, with some stylesheet adjustments, meta tags and links still missing.
With #16 merged, what is needed to get this live?
The Bug in lhinderberger/codeberg-docs-prototype#2 needs to be fixed and the license of the logo (Codeberg/Design#16) should be clarified so that the site can be under CC-BY-SA (I'm currently working on looking up how other projects handle their logos).
Then I will integrate that into the prototype, do some last polishing and write a PR here.
We could also use a common service such as readthedocs etc ... I guess I'd prefer that. The theme looks cool, nevertheless. It might get ported to this?
I don't see the need for so many different static site generators. I mean - I love them, but it makes it harder to maintain stuff in the future if the people who are setting it up today are not available tomorrow anymore ... Codeberg already uses Pelican for the blog, and read the docs is an easy standard. I'd rather use one of them.
The main advantages of the approach using Eleventy are its simplicity and flexibility, as well as the fact that we can very easily self-host the resulting page.
Eleventy is a pleasure to work with, because it tries its best to get out of your way - you rarely have to "fight the framework" - and it's very customizable. From a developer perspective, this simple setup means you can be productive in no time, due to being able to quickly gain a complete understanding of what is going on.
Lastly, it's very easy to self-host. It's basically
npm run build and
cp -r _site/* /var/www/html/something.
For the sake of argument, it would be possible to self-host our own RTD instance, as is described in their documentation. Now does that really sound like an easy-to-use alternative, compared to the deployment of a static site? 😉
I have now created a Pull Request with the finished basic static site and I have added issues for all open questions that arose during the development of the prototype.
Deleting a branch is permanent. It CANNOT be undone. Continue?