Provide docs that explain how templates work

[hegemonic]

If you're trying to write a JSDoc template, we don't have much documentation that would help you figure out how to do that. In practice, most third-party templates have just forked the default template.

We should provide at least some high-level guidance on how you might go about writing a template.

[primeare]

Any changes here since 2015?

[hinell]

Any changes here since 2018?

[blackdrago]

I was wondering the same thing. In one of the defect comments, there was mention of baseline: https://github.com/hegemonic/jsdoc-baseline - as far as I can tell, this uses Handlebars (.hbs) instead of Javascript template (.tmpl) files. But most of the JSDoc templates I've used still use .tmpl files.

I'm working on making my own custom JSDoc template, and I've noticed a few things:
(1) if you want to change things like color scheme, this is a fairly simple asset update
(2) if you want to change structural elements, such as overall design, you can do it via modifying the .tmpl files (or .hbs though I haven't worked with those) - but, depending on your changes, you have to be careful
(3) if you want to add something that JSDocs does not currently have (like, say, adding "categories" or ... adding weird icon tags based on something-or-other) this is less clear and can be a bit more difficult to handle, since it involves digging into the publish.js code

It would be very cool if we could have a skeleton JSDoc Template with its own JSDoc-generated code files. (I am working on this myself, but it's a trial-and-error process...) If other users are interested in such a thing, perhaps we can start a repo and get people to contribute... ?

[hinell]

I spent a little bit of my time by digging up default template and I have just found that the most of functionality of the html generation engine is hidden inside publish.js script.

It gets called by the cli command built in into JSDoc. So it's pretty simple. The primary function from publish.js that gets called by the cli.js is obviously called .pulish():

https://github.com/jsdoc/jsdoc/blob/617b3236bf19d86763b8b046de174196b185594c/cli.js#L425-L441

        try {
            template = require(`${env.opts.template}/publish`);
        }
        catch (e) {
            logger.fatal(`Unable to load template: ${e.message}` || e);
        }


        // templates should include a publish.js file that exports a "publish" function
        if (template.publish && typeof template.publish === 'function') {
            let publishPromise;


            logger.info('Generating output files...');
            publishPromise = template.publish(
                taffy(props.docs),
                env.opts,
                resolver.root
            );

Hope someone finds this helpful.

[alystair]

The great irony of providing a documentation system and not documenting it, this ticket has been open for 10 years, might be easier to work with the AST output instead.