Initial implementation of manual highlighting

[mAAdhaTTah]

Borrow the manual property of whatever already existing Prism instance
there is.

Fixes #765.

In this setup, the manual property would have to be set before the script is included. Open to suggestions for improvement.

[LeaVerou]

Thanks! See comment.

[mAAdhaTTah]

Updated!

[mAAdhaTTah]

Just a thought: this does require some checks in the code that's supposed to disable Prism, if as in the scenario from the original issue, the "disabling" script can't know whether it's been loaded before or after Prism, but I don't think there's anything we can do about that.

[LeaVerou]

Thanks, merged!

Yeah it does, but it could be as simple as:

(window.Prism = window.Prism || {}).manual = true;

[mAAdhaTTah]

I dont think that'll work because the callback will have already been attached. So more like:

if (window.Prism) {
  document.removeEventListener('DOMContentLoaded', Prism.highlightAll);
else {
  window.Prism = { manual: true };
}

[LeaVerou]

Oh, right. The check for _.manual should be in the callback, not before attaching the event! Is there any problem if we change it to that?

[mAAdhaTTah]

We can; we would break BC for people using the old document.removeEventListener('DOMContentLoaded', Prism.highlightAll) method of removing auto-highlighting, as now the callback we're attaching won't be just Prism.highlightAll.

[LeaVerou]

I think that's ok, since this is much more robust :) What do you think?

[mAAdhaTTah]

Fine by me; if we do that, we should document that somewhere though. Is the CHANGELOG enough or should we include a "how to disable auto-highlighting" somewhere?

[LeaVerou]

Ideally it should be in the docs, alongside the docs for data-manual.

[k-funk]

My use case, which I think is fairly general when wanting to use manual, is to import and use the Prism.highlight function directly. An example of that on the docs would be really helpful.

This is what I'm currently using, with the data-manual on my html/script tag. I'm hoping with this PR I can take that html tag out.

import Prism from 'prismjs';
import 'prismjs/components/prism-json';

// initialize view
Prism.highlight(JSON.stringify(rawJSON, null, 2), Prism.languages.json)

[omeid]

@mAAdhaTTah I am using PrimsJS yet again after many years and hit the same issue that had before, (#366), so thanks for fixing this.

This could use some documentation though. It is not obvious how one would set this option.

[mAAdhaTTah]

@omeid Thanks for the reminder. Open #1402 to track. Would love a PR if you've figured out how to use it 😉