Skip to content

Update documentation for auto-start and prism.ts #3885

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.

Sign up for GitHub

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

Open
wants to merge 1 commit into
base: v2
Choose a base branch
from
Open

Update documentation for auto-start and prism.ts #3885

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 9 additions & 5 deletions src/auto-start.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,23 +4,27 @@ import autoloader from './plugins/autoloader/prism-autoloader';
Prism.components.add(autoloader);

export const PrismConfig = {
// TODO: Update docs
/**
* By default, Prism will attempt to highlight all code elements (by calling {@link Prism#highlightAll}) on the
* current page after the page finished loading. This might be a problem if e.g. you wanted to asynchronously load
* By default, Prism will attempt to highlight all code elements (by calling {@link Prism.highlightAll}) on the
* current page after the page finishes loading. This might be a problem if e.g. you wanted to asynchronously load
* additional languages or plugins yourself.
*
* By setting this value to `true`, Prism will not automatically highlight all code elements on the page.
*
* You obviously have to change this value before the automatic highlighting started. To do this, you can add an
* empty Prism object into the global scope before loading the Prism script like this:
* You have to change this value before the automatic highlighting starts. To do this, you can add an
* empty Prism object into the global scope before the Prism script loads like this:
*
* ```js
* window.Prism = window.Prism || {};
Copy link
Member

@DmitrySharabin DmitrySharabin Apr 4, 2025

Choose a reason for hiding this comment

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

Do we still rely on window? Shouldn't we use globalThis here or something?

* Prism.manual = true;
* // add a new <script> to load Prism's script
* ```
*
* or you can set `data-manual` on the script tag used to load PrismJs:
* ```html
* <script src="prism.js" data-manual></script>
Copy link
Member

@DmitrySharabin DmitrySharabin Apr 4, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

It feels like examples of that kind depend on what Prism would look like in v2. I thought it should become ESM-first, no?

So it should be either <script src="prism.js" type="module" data-manual></script> or <script src="prism.mjs" data-manual></script>. Or something similar.

Copy link
Member

@LeaVerou LeaVerou Apr 6, 2025

Choose a reason for hiding this comment

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

You can’t get a reference to the script element that triggered loading in ESM. It would need to be an attribute placed anywhere (eg data-prism-manual) or we’d key on the fil name or we’d also support non-ESM imports (by having an entry point that uses dynamic import to load everything else). Or all of the above 😀

Copy link
Collaborator Author

@robert-j-webb robert-j-webb Apr 7, 2025

Choose a reason for hiding this comment

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

This is a really good point, I'll try redoing the examples as an actual 3rd party project instead of doing it locally

* ```
*
* @default false
Copy link
Member

@DmitrySharabin DmitrySharabin Apr 4, 2025

Choose a reason for hiding this comment

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

By the way, we have options here. Either use @default and get
image

Or we can use the TypeDoc @defaultValue and get the result I find a bit more readable
image

* @public
Copy link
Member

@DmitrySharabin DmitrySharabin Apr 4, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

I'd remove it. If I'm not mistaken, the property visibility is already described in the code (if not specified, it's public by default). TypeDoc also mentions that this tag is redundant (and not desirable). And the result TypeDoc produces is not that good:
image

*/
Expand Down
34 changes: 24 additions & 10 deletions src/core/prism.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,13 +25,13 @@ export class Prism {

/**
* This is the most high-level function in Prism’s API.
* It queries all the elements that have a `.language-xxxx` class and then calls {@link Prism#highlightElement} on
* It queries all the elements that have a `.language-xxxx` class and then calls {@link Prism.highlightElement} on
* each one of them.
*
* The following hooks will be run:
* 1. `before-highlightall`
* 2. `before-all-elements-highlight`
* 3. All hooks of {@link Prism#highlightElement} for each element.
* 3. All hooks of {@link Prism.highlightElement} for each element.
*/
highlightAll (options: HighlightAllOptions = {}) {
const { root, async, callback } = options;
Expand Down Expand Up @@ -63,7 +63,7 @@ export class Prism {
* The following hooks will be run:
* 1. `before-sanity-check`
* 2. `before-highlight`
* 3. All hooks of {@link Prism#highlight}. These hooks will be run by an asynchronous worker if `async` is `true`.
* 3. All hooks of {@link Prism.highlight}. These hooks will be run by an asynchronous worker if `async` is `true`.
* 4. `before-insert`
* 5. `after-highlight`
* 6. `complete`
Expand Down Expand Up @@ -162,7 +162,13 @@ export class Prism {
* Usually a language definition like `Prism.languages.markup`.
* @returns The highlighted HTML.
* @example
* Prism.highlight('var foo = true;', 'javascript');
* import { Prism } from './src/core/prism';
Copy link
Member

@DmitrySharabin DmitrySharabin Apr 4, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

I might miss some essential things, but shouldn't those imports be ”shorter“ (if I could say so)? Like, import Prism, { Token } from "prismjs", import javascript from "prismjs/languages". Is this something we should fix in package.json? Do I understand correctly that we use these examples to show how to use Prism as an NPM package?

Copy link
Member

@LeaVerou LeaVerou Apr 6, 2025

Choose a reason for hiding this comment

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

On a higher leve, these are meant to be small snippets, not full code examples. I think it’s ok if this doesn’t include the import code, which is different depending on tooling/env.

* import javascript from './src/languages/prism-javascript';
* const prism = new Prism();
* prism.components.add(javascript);
* prism.highlight('var foo = true;', 'javascript')
* // Returns:
* `<span class="token keyword">var</span> foo <span class="token operator">=</span> <span class="token boolean">true</span><span class="token punctuation">;</span>`
Comment on lines +169 to +171
Copy link
Member

@DmitrySharabin DmitrySharabin Apr 4, 2025

Choose a reason for hiding this comment

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

I wonder if it makes sense also to use modern JS in examples, like here, to use let instead of var?

Comment on lines +165 to +171
Copy link
Member

@DmitrySharabin DmitrySharabin Apr 4, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

I think

* ```js
* import { Prism } from './src/core/prism';
* import javascript from './src/languages/prism-javascript';
* const prism = new Prism();
* prism.components.add(javascript);
* prism.highlight('var foo = true;', 'javascript')
* ```
* Returns:
* ```html
* <span class="token keyword">var</span> foo <span class="token operator">=</span> <span class="token boolean">true</span><span class="token punctuation">;</span>
* ```

produces a slightly better result
image

What do you think?

*/
highlight (text: string, language: string, options?: HighlightOptions): string {
const languageId = this.components.resolveAlias(language);
Expand Down Expand Up @@ -199,14 +205,22 @@ export class Prism {
* Usually a language definition like `Prism.languages.markup`.
* @returns An array of strings and tokens, a token stream.
* @example
* let code = `var foo = 0;`;
* let tokens = Prism.tokenize(code, Prism.getLanguage('javascript'));
* tokens.forEach(token => {
* if (token instanceof Token && token.type === 'number') {
* console.log(`Found numeric literal: ${token.content}`);
* }
* import { Token } from './src/core';
* import { Prism } from './src/core/prism';
* import javascript from './src/languages/prism-javascript';
*
* const prism = new Prism();
* prism.components.add(javascript);
*
* const tokens = prism.tokenize(`var foo = 0;`, prism.components.getLanguage('javascript')!);
Copy link
Member

@DmitrySharabin DmitrySharabin Apr 4, 2025

Choose a reason for hiding this comment

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

Nit, why not single quotes here instead of ` and `?

* tokens.forEach((token: Token | string) => {
* if (token instanceof Token && token.type === 'number') {
* console.log(`Found numeric literal: ${token.content}`);
* }
* });
* // Logs: Found numeric literal: 0
Comment on lines +208 to +221
Copy link
Member

@DmitrySharabin DmitrySharabin Apr 4, 2025

Choose a reason for hiding this comment

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

I'd mark it as a code block (```ts in this case). That way, TypeDoc will know this snippet should be highlighted appropriately.

*/

tokenize (text: string, grammar: Grammar): TokenStream {
const customTokenize = grammar[tokenize];
if (customTokenize) {
Expand Down