Hubzilla Help System

2025-03-04 06:26:32

documentation@hubzilla.org

Scott M. Stolz wrote the following post Tue, 04 Mar 2025 06:26:47 +0100

Hubzilla Help System

What do we need to do to get the documentation from @Der Pepe (Hubzilla) ⁂ ⚝ converted to the existing Hubzilla help system?

Are there any instructions on how to update the help? And are we waiting for any dev updates to the help system, or are we using the existing help system without changes?

#^https://help.hubzilla.hu/en/ - English
#^https://help.hubzilla.hu - German

cc: @Harald Eilertsen @Mario Vavti @Ema エマ @𝓒𝓱𝓻𝓲𝓼

show all 22 comments

2025-03-04 08:14:03

Jupiter Rowland

jupiter_rowland@hub.netzgemeinde.eu

How well has it been reviewed so far? Especially from the point of view of a non-dev, non-admin user and more so from the point of view of a beginner?

2025-03-04 08:15:32

Harald Eilertsen

harald@hub.volse.no

@Scott M. Stolz I've been meaning to look into that. Last time I tried codeberg was down so I didn't get to it. Hope to get time to have another go one of these days.

As for plan, I just thought I'd start with transferring the files, recreate the index and see how far that gets us.

2025-03-04 10:14:01

Der Pepe (Hubzilla) ⁂ ⚝

pepecyb@hub.hubzilla.hu

@Harald Eilertsen

As for plan, I just thought I'd start with transferring the files, recreate the index and see how far that gets us.

Please feel free to do so. Codeberg is up and running again. They were recently the victim of an attack, but have now recovered.

2025-03-04 10:16:42

Harald Eilertsen

harald@hub.volse.no

@Der Pepe (Hubzilla) ⁂ ⚝ Yeah, I know. Just happened to be just when I had time to look at it last :) I'll try again as soon as I have some time to devote to it.

2025-03-04 10:54:10

Harald Eilertsen

harald@hub.volse.no

One issue I can see right away is that the file and directory names are translated as well. This does of course make perfectly sense when each language is seen in isolation, but it will cause some trouble with our fall-back mechanism when a certain topic has not yet been translated to a given language.

Currently we will look for the help topic in the users preferred language, and if it can't be found, we fall back to the file with the same name in the English docs. This will break when using translated file names.

It's not an unsolvable problem, just takes some work. How important do we think it is to be able to use translated file and directory names for the help files?

2025-03-04 11:30:38

Der Pepe (Hubzilla) ⁂ ⚝

pepecyb@hub.hubzilla.hu

Good point and good suggestion.

You're right. I hadn't thought of that. Please don't bother. I'll change it locally so that the filenames from the English version are also used in the German version. I'll let you know when I'm done (shouldn't take too long) and then the repo will be updated.

2025-03-04 11:43:24

Harald Eilertsen

harald@hub.volse.no

@Der Pepe (Hubzilla) ⁂ ⚝ If you think that's a better solution, I'm fine with it. But I also think it's quite nice that the url makes sense in the native language... As said, it's all solvable, we just need to decide how we want it to work :)

Another question I have is: Will this be a one-time operation?

That is, will we move the docs into the hubzilla help system and any future improvements and additions will be done there, or do we consider keeping the docs source in the separate repo and in mdBook format, and then periodically sync this into the hubzilla help system?

2025-03-04 12:01:24

Der Pepe (Hubzilla) ⁂ ⚝

pepecyb@hub.hubzilla.hu

@Harald Eilertsen

That is, will we move the docs into the hubzilla help system and any future improvements and additions will be done there, or do we consider keeping the docs source in the separate repo and in mdBook format, and then periodically sync this into the hubzilla help system?

In the end, it doesn't matter to me. We can do it either way.

I just need a brief explanation of how the help page works internally at Hubzilla. How do I get an entry in the index (sidebar) if, for example, I write another text that wasn't there already? Does Hubzilla do this automatically by analysing the help files and then adding a link to them in the sidebar?

I haven't quite figured it out yet. Maybe you can help me understand it...

2025-03-04 12:19:23

Harald Eilertsen

harald@hub.volse.no

@Der Pepe (Hubzilla) ⁂ ⚝ The sidebar is a separate html file under the respective language directory. E.g. help/en/toc.html.

Personally I'm not too fond of that. If we decide to make some adjustments to the markup, that change has to be done manually in each file. I'm tempted to rather see if we can use the mdBook SUMMARY.md files directly instead. That will probably be a next step, though. So toc.html for now.

2025-03-04 12:21:16

Harald Eilertsen

harald@hub.volse.no

@Der Pepe (Hubzilla) ⁂ ⚝ Note also, that only the files are listed in the toc.html. The subheadings are generated by some javascript magic.

2025-03-04 12:24:55

Der Pepe (Hubzilla) ⁂ ⚝

pepecyb@hub.hubzilla.hu

It would be feasible and sensible to use the toc.html. The SUMMARY.md can easily be converted to html and then only the entries for ‘About this hub’ would have to be adapted.

2025-03-04 12:26:47

Der Pepe (Hubzilla) ⁂ ⚝

pepecyb@hub.hubzilla.hu

@Harald Eilertsen

The subheadings are generated by some javascript magic.

I see. Then it's not quite so simple after all.

2025-03-04 12:29:12

Der Pepe (Hubzilla) ⁂ ⚝

pepecyb@hub.hubzilla.hu

Although... it's not that bad after all. Then toc.html only contains the top headings and I hope that the JS then pulls the subheadings from the source files that toc.html refers to... correct?

2025-03-04 12:36:01

Harald Eilertsen

harald@hub.volse.no

@Der Pepe (Hubzilla) ⁂ ⚝

In the end, it doesn't matter to me. We can do it either way

The reason I ask is that there are some trivial changes needed to the files as it is now. It's no problem to do these manually if it's a one off job. If we want to be able to keep the original sources in mdBook format, we need tooling to help with the conversion.

2025-03-04 12:45:31

Der Pepe (Hubzilla) ⁂ ⚝

pepecyb@hub.hubzilla.hu

I've thought about it again and I think the best solution would be the following:

When the help system is integrated into Hubzilla, new entries and changes should only be made in the Hubzilla repo. I would do it that way too. At the same time, I maintain my Codeberg repo for myself because I use it to implement the help website I run.

If someone wants to offer a translation in another language, they can use the sources from the Hubzilla repo directly as a template and don't have to use mdBook like I do.

I had chosen this approach (with mdBook) for the rebuild because the old help site was a confusing jumble of documents in a wide variety of formats (md, bb, html, txt) and I wanted to bring it onto a uniform basis (for revision and new creation).

2025-03-04 13:02:03

Harald Eilertsen

harald@hub.volse.no

@Der Pepe (Hubzilla) ⁂ ⚝ Yeah, it picks up the tags from the generated HTML, and populates the toc from that. The sidebar only displays levels 2 and 3 (1 is assumed to be the document title,) while the toc at the top of each page displays all the heading levels iirc.

2025-03-04 14:27:12

Der Pepe (Hubzilla) ⁂ ⚝

pepecyb@hub.hubzilla.hu

@Harald Eilertsen

Ok, then I'll adjust the headings too. 1 for title and then 2 and 3.

I had used higher levels because the display in mdBook was becoming legible. But that's not a problem.

2025-03-04 14:29:14

Harald Eilertsen

harald@hub.volse.no

@Der Pepe (Hubzilla) ⁂ ⚝ No need, I'm adjusting as needed when moving the files anyways.

2025-03-04 14:44:02

Der Pepe (Hubzilla) ⁂ ⚝

pepecyb@hub.hubzilla.hu

Ok...

2025-03-04 15:35:40

𝓒𝓱𝓻𝓲𝓼

chris@im.allmendenetz.de

> When the help system is integrated into Hubzilla, new entries and changes should only be made in the Hubzilla repo.

maybe it would make sense to have an own git repo just for the documentation and merge this if needed into the core Hubzilla repo time by time.

@Der Pepe (Hubzilla) ⁂ ⚝ could be the maintainer of this own git repo - this repo should be on framagit

2025-03-04 17:35:39

Harald Eilertsen

harald@hub.volse.no

@𝓒𝓱𝓻𝓲𝓼 There's some upsides, but also significant downsides to this. Some of it can be fixed with tooling, but there's always the chance that stuff changes one place and not the other.

One of the major advantages of keeping it in the main repo is imo that we can require that merge requests that change behaviour or visuals also update the docs before getting merged. That's a lot more difficult to coordinate (but not impossible) if it's in a separate repo.

Another advantage is that it's easy to check your changes to the docs in your dev environment right away. This makes it less likely that your change breaks something, or don't work as you intended it to.

2025-03-04 20:46:11

Der Pepe (Hubzilla) ⁂ ⚝

pepecyb@hub.hubzilla.hu

@Harald Eilertsen

So, done...

All filenames of the German version are now identical to those of the main version (English). I've tried it and found no dead links.

The Codeberg repo is updated.