Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix and improve highlighting with highlight.js #435

Merged
merged 2 commits into from
Mar 1, 2022

Conversation

mmattel
Copy link
Collaborator

@mmattel mmattel commented Mar 1, 2022

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

src/css/doc.css Outdated Show resolved Hide resolved
src/css/doc.css Outdated Show resolved Hide resolved
src/css/doc.css Outdated Show resolved Hide resolved
src/js/vendor/highlight.js Outdated Show resolved Hide resolved
@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
Copy link
Contributor

@xoxys xoxys left a comment

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
Copy link
Contributor

@xoxys xoxys Mar 1, 2022

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
Collaborator 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