Skip to content

Fix and improve highlighting with highlight.js - #435

Merged
mmattel merged 2 commits into
masterfrom
copy_and_paste_improvements
Mar 1, 2022
Merged

Fix and improve highlighting with highlight.js#435
mmattel merged 2 commits into
masterfrom
copy_and_paste_improvements

Conversation

@mmattel

@mmattel mmattel commented Mar 1, 2022

Copy link
Copy Markdown
Contributor

References: owncloud/docs-server#94 ([QA] Manual copy / paste misses redirects)
References: owncloud/docs#4707 (Add info for the correct use of the source langauge)

Description:

  • When using a language for examples (Antora source block), it is crucial to use the correct one. There is a big difference between using console (shell.js) and bash (bash.js). While bash highlights any recognized bash keyword word from the beginning and let this also be selectable via CSS in the browser, console requires mandatory a bash promt at the beginning to highlight bash keywords correctly - but additionally disables the bash prompt as selectable component in the browser
  • The color of the language selected is now the same color as a bash keyword, which makes the language much better distinctable from the below example block
  • The language selected + the copy symbol are moved up a bit to make it not that close to the example block
  • Additional keywords are added dynamically to the bash language reflecting available commands when a application is installed providing these commands like phpen/dismod or wget ect, see: Adding Keywords to a Language at Startup. Some keywords are added in advance like the a2xxx commands and will automatically be highlighted when the next release of highlight.js gets published, see: enh(bash) $pattern: allow numbers after the first character highlightjs/highlight.js#3494
  • The occ keyword has been added to the above list

NOTE:

  • This PR is the base that things CAN get highlightable correctly. It is essential to use the correct language in the documentation - additional changes may be necessary there. For details using the correct language see the referenced docs PR.
  • The descriptions are added intentionally to understand the behaviour and the reason. This info are hard to find and therefore worth to document it here.

Examples:
(The examples below already reflect a correct language used)

image
image

@jnweiger fyi

Comment thread src/css/doc.css Outdated
Comment thread src/css/doc.css Outdated
Comment thread src/css/doc.css Outdated
Comment thread src/js/vendor/highlight.js Outdated
@mmattel
mmattel merged commit 0c759ba into master Mar 1, 2022
@delete-merged-branch
delete-merged-branch Bot deleted the copy_and_paste_improvements branch March 1, 2022 16:37

@xoxys xoxys left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mmattel I would definitely not recommend it.

* See: https://github.com/highlightjs/highlight.js/wiki/security
* A hljs command has been added in partials/footer-scripts.hbs
* hljs.configure({ ignoreUnescapedHTML: true })
* This is not a security issue for us as we have a static site

@xoxys xoxys Mar 1, 2022

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is simply not true. Someone could sneak in evil code in a docs PR, and it can get merged by someone who is not aware of this potential issue. Why not simply escape the HTML within code blocks as recommended? There is no real reason to disable security mechanisms.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok, thanks for the insight. I will open a new issue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants