Comment by ognarb | Hacker News Reader

Comment by ognarb | Hacker News Reader

Interesting that they are moving to a git based approach. In KDE, we did something very similar 3-4 months ago with moving most of our development tutorials from various sources (wikis, old pdf book, ...) to a new Hugo based documentation platform at https://develop.kde.org/docs

The problem was that our documentation was bit rotting in the wiki and the previous mediaWiki wasn't working so well for having consistent formatting across pages, reviewing changes and organizing the content.

Using the new Hugo based software, we now have a few very helpful macros to add links to Doxygen based documentation, include snippets of code from the library repository and automatic generation of navbars and the navigation.

And we also get with Gitlab web editor an easy way for people to contribute. It is still like before one click away to edit the content.

I probably should blog about it one day, but if someone want to check it out: https://invent.kde.org/documentation/develop-kde-org.

Nice. We are currently moving Our World in Data from MySQL to git as well.

Since 2017 I've moved all CMS I am responsible for to Git from MySQL and haven't looked back. You can still preserve any frontend experiences you want, but get to drop a huge dependency, a lot of code, and gain a ton of new capabilities (faster syncing, easier backups, forks, patches, full audit trails, etc). You never need to worry about migrations again or build your own change control logic.

Yes, in KDE we also moved most of our websites to static website generators to Jekyll or Hugo. From the more than 20 websites only a few are still using Drupal 7 or a custom php framework. The last one and biggest website to be migrated https://kde.org was a big challenge because it is an 20 years old websites with thousands of pages and translations.

But my efforts are finally paying off and we saw an increase of 33% in the visitor count of the website and the current codebase made it so much easier to work with and add new content. And this time, I blogged about it: https://carlschwan.eu/2020/10/30/kde-org-hugo.html

Nice! Good writeup too.

When I click "Edit this page" I am asked to sign in. Is there a reason for that? I'd expect to see the source and be able to submit a PR as a normal repo on Gitlab.

You get redirected to the gitlab web editor this is the most sensible things for most editors who already have an account.

I now added a direct link to the source code too.

Wow that was fast! Awesome, works great. Thanks.

Just curious: What is the benefit/reason for the readfile shortcode for displaying code snippets as opposed to just pasting the code in and using the typical syntax highlighting?

I suppose if the actual source file changes then the page would be updated as well which is neat, but if you're specifying certain lines to read from then that could easily become a problem.

Considering how few shortcodes you're using I just felt like there must be a good reason to use it in this way and I was curious why.

The readfile shortcode was added because this sort of code inclusion was used previously and when converting the documentation I needed something with similar semantic. Another advantage is that it allows me to have a compilable code examples that can be easily downloaded using gitlab support for creating zip from directories[0].

More interesting are the doxysnippet shortcode[1] that provides the extraction from the source code or the custom rendering of links[2] that allows this sort of markdown links: [Overlay](docs:kirigami2;OverlayDrawer)

[0]: https://invent.kde.org/documentation/develop-kde-org/-/archi...

[1]: https://invent.kde.org/documentation/develop-kde-org/-/blob/...

[2]: https://invent.kde.org/documentation/develop-kde-org/-/blob/...

Reply on news.ycombinator.com