Documentation Wiki

2025-02-10 14:46:24

documentation@hubzilla.org

Scott M. Stolz wrote the following post Mon, 10 Feb 2025 14:46:21 +0100

Documentation Wiki

We have some updated documentation now, much thanks to @Der Pepe (Hubzilla) ⁂ ⚝, who did a great job.

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

Repository: (please someone provide a link)

We should probably start porting that over to the Hubzilla website and the built-in help system.

First, is the documentation considered ready to port?

And, how do we want to present the documentation on hubzilla.org?

show all 31 comments

2025-02-10 15:49:56

Der Pepe (Hubzilla) ⁂ ⚝

pepecyb@hub.hubzilla.hu

The documentation is currently more or less ‘finished’ from my side and could be added.

The repo for it: https://codeberg.org/derpepe/hubzilla-doc

2025-02-10 16:32:13

Harald Eilertsen

harald@hub.volse.no

@Der Pepe (Hubzilla) ⁂ ⚝ Cool, if nobody else wants to have a go at integrating it, I can start looking at it. Not much time for Hubzilla contributions these days, so it may take a while.

2025-02-11 00:23:54

Scott M. Stolz

scott@loves.tech

I was looking through it, and I think it could use a bit more formatting.

For example, some of the developer docs request you to type certain things, but they are not formatted as <code> or <kbd>.

We might also consider the fact that Hubzilla wiki and webpages allow both Markdown and HTML on the same page. I am not sure if that is allowed in the built-in help system though.

I'll try to find some time to put the code into Hubzilla and see how it looks.

Does the system that is being used on https://help.hubzilla.hu/en/ allow you to mix Markdown and HTML?</kbd></code>

2025-02-11 00:49:29

Der Pepe (Hubzilla) ⁂ ⚝

pepecyb@hub.hubzilla.hu

@Scott M. Stolz

but they are not formatted as or

In which chapters are the code blocks missing?

Does the system that is being used on ... allow you to mix Markdown and HTML?

mdBook only allows Markdown as a source and generates HTML from it. Therefore, all help files in src are available as Markdown files.

2025-02-11 01:23:00

Scott M. Stolz

scott@loves.tech

@Der Pepe (Hubzilla) ⁂ ⚝

In which chapters are the code blocks missing?

I have not gone through everything, but I did notice a couple:

https://codeberg.org/derpepe/hubzilla-doc/src/branch/master/doc/en/src/develmanual/coding_style.md

The last bullet point mentions code examples, but they are not `code` blocks so novice developers might not know which words are part of the code and which are part of the sentence.

https://codeberg.org/derpepe/hubzilla-doc/src/branch/master/doc/en/src/develmanual/API.md

The curl statement should be a code block.

Plus there are some places where it turned what was supposed to be a code example into a URL.

Just small stuff.

I was playing around with it on Hubzilla to see what it looks like:

https://development.guide/page/hubzilla/api

It looks a bit different on Hubzilla.

2025-02-11 01:27:16

Der Pepe (Hubzilla) ⁂ ⚝

pepecyb@hub.hubzilla.hu

Ok, I'll review the developer manual again.

2025-02-11 06:18:17

Harald Eilertsen

harald@hub.volse.no

@Scott M. Stolz We can (and will need to) make ongoing adjustments and edits after integration as well, so I don't see this as showstoppers.

I've been thinking lately, that we should make updating the docs mandatory for merge requests that add or change a feature. Now that the docs are in a way better shape, this is possible.

2025-02-11 09:48:48

Scott M. Stolz

scott@loves.tech

@Harald Eilertsen I think that is a great idea. The person making the changes would be in the best position to know what changed.

I need to implement such a policy for myself and developers I bring in for Neuhub.

One of the big stumbling blocks I have encountered when bringing in a new developer is explaining where everything is located and the concepts of modules, templates, PDLs, apps, layouts, etc. Some developers were taught a different model of development, so it takes them a bit to wrap their head around how Hubzilla is structured.

In the past, if they work 10 hours on something, most of that work is reverse engineering how Hubzilla works, and I wind up spending at least 3 to 5 hours chatting with them. Most of that chat is explaining the Hubzilla codebase.

I am hoping that a wiki I am creating, combined with the work @Der Pepe (Hubzilla) ⁂ ⚝, will make everyone's lives easier. And reduce how long it takes for me to explain how Hubzilla works.

In the future, instead of explaining how things work in chat, I will create documentation up front, where possible.

For example, here is a wiki for the wiki: https://development.guide/wiki/hubzilla/code/wiki

I am still reverse engineering how the Hubzilla wiki works, as you can see by the document.

It does not contain a reference to every file, but it's not supposed to. Just enough to convey the basics: module, template, pdl, app, layout, and database. And some useful notes related to the URL or file.

And, like you, I want to know what has changed, since a lot of our addons and themes involve modifying the core code's behavior.

2025-02-11 10:15:51

Harald Eilertsen

harald@hub.volse.no

@Scott M. Stolz

a bit to wrap their head around how Hubzilla is structured

I can relate! :) It's taken me quite some time too, and I still get surprised.

Which is also why my main focus so far has been on adding tests and refactoring/cleaning up the code and architecture. The tests are imo a prerequisite for the latter, and will in addition double as executable documentation ensuring that the code actually does what it's supposed to do – regardless of how it's implemented.

Getting some help in expanding test coverage would be really nice!

For example, here is a wiki for the wiki: (....)

Nice!

A quick note about the HTML in Markdown comments: Conforming markdown implementations should allow for mixing HTML with the markdown syntax. See Commonmark and the original spec by John Gruber.

2025-02-11 10:55:08

Der Pepe (Hubzilla) ⁂ ⚝

pepecyb@hub.hubzilla.hu

@Harald Eilertsen

A quick note about the HTML in Markdown comments: Conforming markdown implementations should allow for mixing HTML with the markdown syntax. See Commonmark and the original spec by John Gruber.

I think Hubzilla can definitely do that because it supports ‘multiformat’. It is even possible to use bbCode, Markdown and HTML within a text.

I avoided this in my draft because I'm not sure if mdBook understands it. However, this is only important to me because I use it to develop the documentation, but it is ultimately not applied to Hubzilla. There should be no problem inserting HTML tags in the Markdows document, which is ultimately used for Hubzila.

2025-02-11 11:09:40

Scott M. Stolz

scott@loves.tech

@Der Pepe (Hubzilla) ⁂ ⚝

I think Hubzilla can definitely do that because it supports ‘multiformat’. It is even possible to use bbCode, Markdown and HTML within a text.

I never got BBCode to work when using Markdown. I've tried.

2025-02-11 11:16:05

Harald Eilertsen

harald@hub.volse.no

@Der Pepe (Hubzilla) ⁂ ⚝ mdBook adheres to Commonmark, so I would expect that it allows for html. It's even extensible with preprocessors so we could add bbcode and the Hubzilla specific tags if we want to. (Not sure I see much value in that, but we could :)

2025-02-11 11:22:36

Scott M. Stolz

scott@loves.tech

@Harald Eilertsen Adding it to mdBook probably would be overkill, but it would be useful in Hubzilla.

The BBCode has the entire [observer] set of tags, which allow you to change what is displayed based on whether they are authenticated or not.

It is what I used to create this page: https://hubzilla.monster/page/membership/members

If you are logged in or remotely authenticated, you see a different version.

But I had to put it in BBCode mode, or else it won't work. HTML and Markdown are converted to plain text.

2025-02-11 11:43:40

Der Pepe (Hubzilla) ⁂ ⚝

pepecyb@hub.hubzilla.hu

@Scott M. Stolz

I never got BBCode to work when using Markdown. I've tried.

I wasn't sure whether this only works for posts but not for websites.

But it works. Even with hubzilla-specific bbCode within HTML tags.

Hubzilla converts it into bbCode anyway (for web pages, if you have selected bbCode).

What I haven't tried yet: What happens if you use HTML tags for which there is no equivalent in bbCode.

2025-02-11 12:04:53

Scott M. Stolz

scott@loves.tech

@Der Pepe (Hubzilla) ⁂ ⚝ Posts are handled differently than webpages and wiki.

Ideally I would like to be able to have HTML, Markdown, and BBCode all on the same webpage or wiki entry.

Here is an example of a webpage in Markdown: https://development.guide/page/hubzilla/test

2025-02-11 12:06:25

Harald Eilertsen

harald@hub.volse.no

@Der Pepe (Hubzilla) ⁂ ⚝

What happens if you use HTML tags for which there is no equivalent in bbCode.

They should be filtered out. If you find some that aren't I think that's a bug.

2025-02-11 12:36:02

Der Pepe (Hubzilla) ⁂ ⚝

pepecyb@hub.hubzilla.hu

@Scott M. Stolz

Posts are handled differently than webpages and wiki.

I know, but I've found that with websites using the bbCode type, a mix of markup languages works the same way as with postings.

Also that the content is ultimately converted completely to bbCode after ‘submitting’.

2025-02-11 12:47:27

Scott M. Stolz

scott@loves.tech

@Der Pepe (Hubzilla) ⁂ ⚝

Also that the content is ultimately converted completely to bbCode after ‘submitting’.

For posts, yes. But not for webpages. It is stored in the database in the same format you submitted it in, which includes the HTML.

For example, I can place HTML that has no BBCode equivalent in a wiki or a web page.

<div class="alert alert-danger">This is an alert!</div>

This is stored as HTML, and when you edit the same web page, it is still in HTML.

You can see it on the edit view of this wiki entry:

https://development.guide/wiki/hubzilla/code/wiki

2025-02-11 13:00:33

Der Pepe (Hubzilla) ⁂ ⚝

pepecyb@hub.hubzilla.hu

@Scott M. Stolz

Well, I experience it differently...

I created a test webpage (type: bbCode) with a sentence containing one bbCode, one Markdown and one HTML tag.
In the preview, it was displayed correctly.

After publishing, the webpage was also displayed correctly.

But when I reopened the webpage for editing, all tags had been converted to bbCode.

The same source code in a web page with content type HTML only results in the HTML element being correctly rendered; the bbCode and Markdown elements are displayed unformatted with the tags as normal text. When editing the page, there are also no changes to the source code.
The same applies to the Markdown content type.

If you select bbCode as the content type, the source code is completely converted to bbCode and everything is correctly rendered in the display. With the HTML and Markdown types, the source code remains untouched, but the text markup of the ‘foreign’ markup languages is not rendered formatted.

2025-02-11 16:14:57

Scott M. Stolz

scott@loves.tech

I am using Markdown, which allows HTML and Markdown on the same page, but no BBCode.

- BBCode = Saves BBCode only.
- HTML = HTML only.
- Markdown = Markdown + HTML.
- Text = Plain Text.

What I would like to see is:

- MultiCode = BBCode, Markdown, and HTML.

Note: HTML is filtered unless the admin turns on "Allow Code" for your channel.

2025-02-11 16:27:58

Scott M. Stolz

scott@loves.tech

@Der Pepe (Hubzilla) ⁂ ⚝

I created a test webpage (type: bbCode) with a sentence containing one bbCode, one Markdown and one HTML tag.
In the preview, it was displayed correctly.

That is not how it behaves for me. A couple questions.

- What version of Hubzilla are you using? I am using version 10.0.8.
- Do you have the mdpost addon enabled? I do not.

2025-02-11 16:36:46

Der Pepe (Hubzilla) ⁂ ⚝

pepecyb@hub.hubzilla.hu

I'm using v 1.0.8 with mdpost enabled.

2025-02-11 16:58:51

Scott M. Stolz

scott@loves.tech

@Der Pepe (Hubzilla) ⁂ ⚝ That is what the difference is. The mdpost addon allows you to use Markdown with BBCode, but the downside is that it converts everything to BBCode, which is one of the reasons I leave it disabled.

For example, you can't build this page with BBCode: https://hubzilla.monster/page/membership/home

The mdpost addon also messes up bullets, and I use a lot of bullets.

2025-02-11 16:58:56

Der Pepe (Hubzilla) ⁂ ⚝

pepecyb@hub.hubzilla.hu

@Scott M. Stolz

Content type: bbCode, create page:

Website displayed:

Later editing of the website:

Content type: HTML, create page:

Website displayed:

Later editing of the website:

Content type: Markdown, create page:

Website displayed:

Later editing of the website:

2025-02-11 17:39:37

Der Pepe (Hubzilla) ⁂ ⚝

pepecyb@hub.hubzilla.hu

@Scott M. Stolz

The mdpost addon allows you to use Markdown with BBCode, but the downside is that it converts everything to BBCode, which is one of the reasons I leave it disabled.

Ah, ok. I didn't know that. I guess I'll just disable the addon again.

md is rarely used in posts anyway.

2025-02-11 17:43:45

Scott M. Stolz

scott@loves.tech

@Der Pepe (Hubzilla) ⁂ ⚝ The mdpost addon is fine as long as you don't use bullets.

Markdown and BBCode are very similar in the type of markup they are capable of, which is why it can convert Markdown to BBCode.

2025-02-11 17:45:27

Der Pepe (Hubzilla) ⁂ ⚝

pepecyb@hub.hubzilla.hu

However, multicode in web pages no longer works if I use bbCode as the type. Now I have to consider what is more important to me. As a rule, I write postings in pure bbCode anyway.

2025-02-11 18:00:32

Der Pepe (Hubzilla) ⁂ ⚝

pepecyb@hub.hubzilla.hu

@Scott M. Stolz I thought about it and came to the conclusion that the add-on can be deactivated.

Posts are better formatted with bbCode anyway. And you shouldn't mix websites. That's what the selection of the content type used is for, so that you should decide beforehand whether to use bbCode, Markdown or HTML.

2025-02-11 19:12:12

Scott M. Stolz

scott@loves.tech

@Der Pepe (Hubzilla) ⁂ ⚝ Sometimes you do need to mix formats.

For example, the only way to use the [observer] is if BBCode works.

So if you want to show one HTML button to people logged in and a different HTML Button to people logged out, you can't do it.

2025-02-12 02:13:10

Ema エマ

ema@utasansh.in

I also write in pure bbCode because I need [observer][/observer]. But it‘s a long lasting wish to be able to include html into it for customized formatting such as vertical writing and ruby or for calling bootstrap classes.

2025-02-12 21:31:37

Der Pepe (Hubzilla) ⁂ ⚝

pepecyb@hub.hubzilla.hu

@Scott M. Stolz I have revised the developer manual with regard to code blocks... and hopefully not missed anything.