3 ms·

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 fro

by ognarb 6y ago

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 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 https://invent.kde.org/documentation/develop-kde-org.

programbreeding 6y ago
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.
- ognarb 6y ago
  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/-/archive/developement/develop-kde-org-developement.zip?path=content/docs/getting-started/commandline https://invent.kde.org/documentation/develop-kde-org/-/archi... [1]: https://invent.kde.org/documentation/develop-kde-org/-/blob/developement/layouts/shortcodes/doxysnippet.html https://invent.kde.org/documentation/develop-kde-org/-/blob/... [2]: https://invent.kde.org/documentation/develop-kde-org/-/blob/developement/layouts/docs/_markup/render-link.html https://invent.kde.org/documentation/develop-kde-org/-/blob/...
breck 6y ago
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.
- ognarb 6y ago
  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 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 https://carlschwan.eu/2020/10/30/kde-org-hugo.html
  - breck 6y ago
    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.
    - ognarb 6y ago
      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.
      - breck 6y ago
        Wow that was fast! Awesome, works great. Thanks.

by ognarb 6y ago

programbreeding 6y ago

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.

ognarb 6y ago
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/-/archive/developement/develop-kde-org-developement.zip?path=content/docs/getting-started/commandline https://invent.kde.org/documentation/develop-kde-org/-/archi... [1]: https://invent.kde.org/documentation/develop-kde-org/-/blob/developement/layouts/shortcodes/doxysnippet.html https://invent.kde.org/documentation/develop-kde-org/-/blob/... [2]: https://invent.kde.org/documentation/develop-kde-org/-/blob/developement/layouts/docs/_markup/render-link.html https://invent.kde.org/documentation/develop-kde-org/-/blob/...

breck 6y ago

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.

ognarb 6y ago
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 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 https://carlschwan.eu/2020/10/30/kde-org-hugo.html
- breck 6y ago
  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.
  - ognarb 6y ago
    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.
    - breck 6y ago
      Wow that was fast! Awesome, works great. Thanks.