Document how to create code blocks with syntax highlighting

[Onnno]

I use TypeDoc successfully now, but I can't get Highlight.js make my example code being highlighted.
I installed TypeDoc as a local development package (--save-dev) and I think it installed highlight.js automatically. However, because there was no highlighting happening, I updated highlight.js.
I don't really know why things don't work.
I used some example Code in a .ts code file comment (/** I put example code like code you can see below here */) as well as in my introductory .md markup file.
Nothing works, also not with a class indicator, neither Typescript, typescript, TypeScript or ts.
My example code simply was something like:
myExampleFunc(n: a.INotification): string {
this.ExampleResource.markUsed({ id: n.Id });
return "OK";
}

Can anyone help me get this running?

[jonchardy]

What do your docstrings look like? Highlighting works for us using this style:

/**
 * Here is a docstring that contains some code...
 *
 * Code example:
 * ```js
 * function foo() {
 *   console.log('Welcome to foo');
 * }
 * ```
 */
public methodA() {
  // ...
}

[aciccarello]

Would it be better if TypeDoc defaulted code to TypeScript?

[Onnno]

@jonchardy Thanks a lot. Works now.
I couldn't find that ```-syntax on the web.

Instead, I found this:

This will find and highlight code inside of <pre><code> tags;
it tries to detect the language automatically.
If automatic detection doesn’t work for you,
you can specify the language in the class attribute:
<pre><code class="typescript">...</code></pre>

on https://highlightjs.org/usage/

@aciccarello: Now that I know the syntax I can mark code as Typescript - however, of course it makes sense to default typedoc to typescript.

[9oelM]

why would highlightjs not automatically detect the language here?

typedoc/src/lib/output/plugins/MarkedPlugin.ts

/**
     * Highlight the synatx of the given text using HighlightJS.
     *
     * @param text  The text taht should be highlightes.
     * @param lang  The language that should be used to highlight the string.
     * @return A html string with syntax highlighting.
     */
    public getHighlighted(text: string, lang?: string): string {
        try {
            if (lang) {
                return HighlightJS.highlight(lang, text).value;
            } else {
                return HighlightJS.highlightAuto(text).value;
            }
        } catch (error) {
            this.application.logger.warn(error.message);
            return text;
        }
    }

anyhow, if we wanted to default the language to typescript, we could just set the default param (lang) to "typescript" here and make some few lines of changes accordingly?

[Onnno]

Yes, works without 'ts'. Thanks. No need for default param.
Also found that triple accent syntax now :-).
Thanks for help and sorry for some maybe simple questions. I'm new to this :-O

[aciccarello]

That's true, it should be autodetecting the language. We can add a note about code fences and highlightjs to the doccomments documentation.

[9oelM]

is typedoc-site the right place to submit a PR on that?

[Onnno]

TypeDoc's howto document is here: TypeDoc and links to HighlightJS on github.
So people may expect an explanation rather on one of these pages I guess.
I'd prefer to see it in github HighlightJS page.

[aciccarello]

@9oelM I'm working on some changes to the website infrastructure so I'll make this change myself. Thanks!

[9oelM]

@aciccarello great! looking forward to seeing the website also getting optimized for mobile view.