I am looking for a system to document my research findings, in this case about FS25 mapping and modding.

Possible systems include CMS systems, git based systems, static content generators, web applications, frameworks, …

These webpages are my experiment to see if Hugo is a good fit as a solution.

Features I am looking for

  • Changes need to be traceable
    • Figure out when something changed, and how it changed.
    • Optionally who changed it, but less important because it’s mostly me.
  • Typography needs to be clean, big and readable.
  • Have some way to display code snippets
  • Be fast
    • How long does it take to fix a simple typo?
  • Searchable of the docs
  • The system shouldn’t waist time to maintain
  • Markdown based
    • MD has just the right balance between markdown-code and content-code.

Gitlab Buildin wiki attempt

Results after trial experiment.

Positives

  • It provides some basic markdown functionality.
  • Its completly git first and can be edited from the web-IDE.
  • Markdown based.

Negatives

  • Its functionality is limited
  • Their is not really a way to extend it.
  • It’s confusing how it is linked to the repo itself.

I decided not to continue this path and search for a more advanced solution.

This current solution : Hugo + LotusDocs

Hugo https://gohugo.io/ is a static site builder to compile markdown files into servable html pages.

LotusDocs is a custom theme https://github.com/colinwilson/lotusdocs that provides some extra build-in options:

  • Edit this page git back-reference
  • Auto menus
  • Some basic clean page-template that looks good

Positives

  • MD works really wel both in VSCode and the online gitlab web-IDE
  • Template overwrites can be added in the content repo and take precedent over the theme
  • The theme and typo looks good by default
  • Free building and deploying with gitlab pipelines.
  • Search works out of the box
  • Their is an option to pull in the complete theme to adjust everything
  • Very low boiler-plate/code overhead
  • Navigations and breadcrumbs work by default
  • Edit in gitlab, and latest modified from git-source

Negatives

  • Their is a root landing-page. I can’t seem to mount the docs folder under root.
  • Adjusting this landing page can only be done with some general parameters
    • For really adjusting it I would have to pull in the complete theme
  • Page weights are messy and manual work.
    • Wrong weights cause some strange/confusing Previous/Next article buttons

Conclusion

For now it looks like a good fit, let’s see how the content evolves.

Edit this page

Last updated 30 Mar 2025, 00:09 +0100 . history