Find a way to communicate allowed syntax to commenters

[ix5]

There should be a way for commenters to know which elements of markdown they are allowed to use.
Since every Isso server might be configured differently, this should ideally be generated on-the-fly.

Two ideas pop into my head:

1. Having a page generated by Isso that the client links to that lists the available markdown options.
2. Displaying a little (inline) pop-up on the client side with the most essential formatting ([foo](bar) is a link, *foo* is bold, etc.)
3. Having a small button/area with Adding bold or italic text or create link... as a label that makes a small markdown explanation slide out, animated

Suggestions are very much welcome!

Examples in the wild:

• https://blog.mdosch.de/2017/02/19/kommentarbenutzung/#markdown

[Fryboyter]

As a user, I always consider pop-ups annoying. I would prefer an area above or below the form with the most important formatting and a link to the rest. Or a link to a complete overview. For example, like https://www.deimeke.net/dirk/blog/index.php?/archives/4129-Meine-Firefox-Addons-Ende-2021.html

[ix5]

I've tried tackling this by providing a /syntax endpoint and generating some kind of small explanatory text based on which [markup] flags and [markup] options are enabled, as well as based on allowed-elements/attributes.

The permutations here are already a bit iffy to deal with. What made me abort though was having to now also deal with translations on the server side (the markdown explanation will be displayed to users and thus has to be translated). One might re-use the JS translation files, but all in all, it's just a really messy affair.

---

Instead, I propose simply leaving the explanation of allowed syntax to site admins which can place an explanatory text above the comment box. An example with phrasing help should be added to the docs.

[BBaoVanC]

Maybe we could do it in a similar way to Remark42? It has some buttons on the top of its post box that can do simple styling (actually GitHub has this too!), and it also has a little sentence that says it supports styling with Markdown. Although this would need to change the layout of the postbox a bit since currently it's just a plain text input box.

[ix5]

It has some buttons on the top of its post box that can do simple styling (actually GitHub has this too!)
[...]
Although this would need to change the layout of the postbox a bit since currently it's just a plain text input box.

That would require us to build or integrate some sort of WYSIWYG editor. As long as it stays simple, I'm all for that. The current contentEditable way is causing a lot of issues. I'd say to investigate how e.g. Quill.js and other editors do this.

and it also has a little sentence that says it supports styling with Markdown.

Yes, that's the least we should do. But keep in mind that each server might be configured differently (has tables enabled/disabled, renders _ as either underline or emphasis, ...). As such, a generic guide would not be accurate. That freedom we allowed Isso admins to have is now biting us back a bit. See ix5/isso@syntax-page for my attempt.

[BBaoVanC]

It has some buttons on the top of its post box that can do simple styling (actually GitHub has this too!)
[...]
Although this would need to change the layout of the postbox a bit since currently it's just a plain text input box.

That would require us to build or integrate some sort of WYSIWYG editor. As long as it stays simple, I'm all for that. The current contentEditable way is causing a lot of issues. I'd say to investigate how e.g. Quill.js and other editors do this.

What I had in mind was just like how on GitHub when you press the buttons, it just inserts the markdown code. That would keep it as plaintext. Although Quill.js does look pretty cool, and I imagine it would be nicer, and definitely worth looking into.

If you haven't already done anything, I'll have to try and experiment myself with Quill.js.

and it also has a little sentence that says it supports styling with Markdown.

Yes, that's the least we should do. But keep in mind that each server might be configured differently (has tables enabled/disabled, renders _ as either underline or emphasis, ...). As such, a generic guide would not be accurate. That freedom we allowed Isso admins to have is now biting us back a bit. See ix5/isso@syntax-page for my attempt.

Hmm that definitely complicates things. I wonder if we would be better off removing the markdown customization so it can be simpler.

Regardless a WYSIWYG editor (maybe with the option to view raw source) is probably the best solution from an end-user perspective. I wonder if this could solve our issues with textarea vs contenteditable? Hopefully then we could use the exact same editor for admin and client, so there isn't any difference in behavior.

[ix5]

What I had in mind was just like how on GitHub when you press the buttons, it just inserts the markdown code. That would keep it as plaintext. Although Quill.js does look pretty cool, and I imagine it would be nicer, and definitely worth looking into.

If you haven't already done anything, I'll have to try and experiment myself with Quill.js.

The GH way definitely appeals to me, although it certainly assumes a bit of technical savvy/not being intimidated by weird symbols as a non-technical user.

Feel free to experiment with quill, but keep in mind our bundle is already heavily overloaded (60kb vs e.g. commento's ~10kb? or schnacks's ~8kb).

Hmm that definitely complicates things. I wonder if we would be better off removing the markdown customization so it can be simpler.

Per Isso's defaults, e.g. images are disallowed and LaTeX extensions are disabled. Would we want to enable those for everyone for the sake of simplicity? Would we want everyone to also be able to enter plain HTML? Would we want the list of allowed plain HTML elements to match what a user might enter through markdown syntax anyway? A few questions to be decided, for sure.

But in the end, I think that might be the winning solution going forward. Standardize on e.g. CommonMark or GitHub-Flavored-Markdown or any other widely-accepted standard and stick to it, giving sensible defaults.

If we want to keep allowing admins to allow/disallow syntax, I think it would better be done through some options like

[markdown]
enable-images = true
enable-plain-html = false

instead of essentially exposing the full misaka API and forcing admins to understand its intricacies.

Regardless a WYSIWYG editor (maybe with the option to view raw source) is probably the best solution from an end-user perspective. I wonder if this could solve our issues with textarea vs contenteditable? Hopefully then we could use the exact same editor for admin and client, so there isn't any difference in behavior.

Hmm, I think discussing a WYSIWYG editor belongs more into #465. In general, toggling between raw source and rendered preview is something we should keep, IMO.

Both GH and remark42 use external links for explaining syntax, btw (rm42, GH)

[BBaoVanC]

Feel free to experiment with quill, but keep in mind our bundle is already heavily overloaded (60kb vs e.g. commento's ~10kb? or schnacks's ~8kb).

Well I started playing with it for a couple minutes, then realized that it probably is nicer to just have the split plaintext & preview menu (like it already is).

Also, I tried out your syntax-page branch, but when going to the /syntax endpoint, I just get an error which I don't really understand:

2022-05-16 17:41:50,171 ERROR: GET /syntax
Traceback (most recent call last):
  File "/home/bbaovanc/git-repos/isso/isso/__init__.py", line 146, in dispatch
    response = handler(request.environ, request, **values)
  File "/home/bbaovanc/git-repos/isso/isso/views/__init__.py", line 88, in show
    return render_template('syntax.html',
  File "/home/bbaovanc/git-repos/isso/isso/utils/__init__.py", line 114, in render_template
    translations = gettext.translation(
  File "/usr/lib/python3.10/gettext.py", line 592, in translation
    raise FileNotFoundError(ENOENT,
FileNotFoundError: [Errno 2] No translation file found for domain: 'isso'

Thinking this through though, this probably is the best solution.

[ix5]

Well I started playing with it for a couple minutes, then realized that it probably is nicer to just have the split plaintext & preview menu (like it already is).

👍

Also, I tried out your syntax-page branch, but when going to the /syntax endpoint, I just get an error which I don't really understand:

2022-05-16 17:41:50,171 ERROR: GET /syntax
Traceback (most recent call last):
  File "/home/bbaovanc/git-repos/isso/isso/__init__.py", line 146, in dispatch
    response = handler(request.environ, request, **values)
  File "/home/bbaovanc/git-repos/isso/isso/views/__init__.py", line 88, in show
    return render_template('syntax.html',
  File "/home/bbaovanc/git-repos/isso/isso/utils/__init__.py", line 114, in render_template
    translations = gettext.translation(
  File "/usr/lib/python3.10/gettext.py", line 592, in translation
    raise FileNotFoundError(ENOENT,
FileNotFoundError: [Errno 2] No translation file found for domain: 'isso'

I don't quite remember how I set up the .po/.mo translation files, but in my commit message, I noted down these commands:

pybabel extract --mapping babel.cfg --output-file=locale/isso.pot .
pybabel update --domain=isso --input-file=locale/isso.pot --output-dir=locale
cp locale/isso.pot locale/en/LC_MESSAGES/isso.po
pybabel compile --domain=isso --directory=locale --use-fuzzy

Also keep in mind that that branch was just my experimentation, and I decided for myself that dynamically generating the syntax docs (and also in different languages) is just a giant pain. YMMV.

Thinking this through though, this probably is the best solution.

Which one is?

[BBaoVanC]

Which one is?

Having a separate /syntax page which we can then link somewhere in the postbox area.