search

backdrop-ops / docs.backdropcms.org

Website for displaying Backdrop CMS documentation and API source code.
https://docs.backdropcms.org/
6 stars 6 forks source link

[DX] Install Token Filter module and enable for GitHub Labels tokens #167

Closed bugfolder closed 2 years ago

bugfolder commented 2 years ago

This is a follow-up to https://github.com/backdrop-ops/docs.backdropcms.org/issues/165.

The newly installed GitHub Labels module supports HTML representations of GitHub labels of the form

<span class="gh-label gh-label-pr-needs-work"></span> for a label titled "PR - Needs Work".

The module also provides tokens for labels, so you could also use

[gh-label:pr-needs-work] for a label titled "PR - Needs Work".

This is much simpler for editors. And, perhaps more significantly, it is compatible with CKEditor (which is installed for the Documentation text filter). The HTML version is not; CKEditor rewrites the HTML, losing all the formatting information.

To allow the use of tokens within page body text, though, we would need to install and enable the Token Filter, and then add the "Replace tokens" filter to the Documentation and Standard text filters.

Shall we do this? A possible concern is it would allow those with the Editor and Developer role to use any tokens (not just the GitHub Labels tokens) in page text.

Currently, there are 3 pages on docs.b.org that use the HTML versions of GitHub labels from backdrop/backdrop-issues. There was a request on Zulip to document the labels from backdrop-ops/contrib, which would call for a new page on docs.b.org. It would be nice to use tokens in CKEditor, rather than raw HTML, to generate that page (and to go back and tokenize the three existing pages).

ghost commented 2 years ago

CKEditor has a Styles dropdown list. Can you add something to that so that you can highlight text then style it as per a label? Note that this would require changing the way labels work so that the text is actually part of the HTML, see https://github.com/backdrop-contrib/github_labels/issues/1

bugfolder commented 2 years ago

The color for labels is text-specific. Having CKEditor recognize the text and then figure out which color, background color, and border to apply seems like it might be tricky. Would need to use path_clean_string() on the text to figure out the key to use to get the right CSS.

ghost commented 2 years ago

Maybe just a generic class for the wrapping <span>, then use JS to apply the right colour...?

bugfolder commented 2 years ago

I"ll open an issue on the module for the CKEditor support https://github.com/backdrop-contrib/github_labels/issues/9 and look into it further.

A note on this issue's question of installing Token Filter module: we are currently using it on events.backdropcms.org, so there is some precedent.

bugfolder commented 2 years ago

This past week there was a request to put User Time Zone Tokens onto b.org](https://github.com/backdrop-ops/backdropcms.org/issues/864), which I've done (and so which includes installing and enabling Token Filter). So Token Filter is now on b.org and events.b.org.

I'd like to suggest that I go ahead and put Token Filter on the docs site, and enable the "replace tokens" filter for Documentation and Standard text formats, so that we can use the GitHub Labels tokens. If I (or a contributor) gets a CKEditor-style-based solution into the GitHub Labels module, we can switch to that if it turns out to be preferable from a usability point of view.