Frequently Asked Questions

How do I group the docs generated from multiple JS file under the same route / page?

Simply define a name for that group of files by using an object. Example docma.json for build configuration:

    "src": { 
        "my-lib": [
    "app": {
        "routing": "query"
    "dest": "./docs"

The route for my-lib docs will be ?api=my-lib when routing method is "query", and api/my-lib when it's set to "path".

Should I group my JS files under the route name "api"?

No. "api" is the default group/route name and it's a reserved word. Any ungrouped JS files will be grouped under "api". e.g. { src: "lib/**/*.js" } is available at the route /?api (if routing method is "query") or /api (if routing method is "path").

How can I document my and rename its route?

You simply define an object within the src option.

    "src": [
        { "guide": "./" }
    "dest": "./docs"

The route for README content will be ?content=guide when routing method is "query", and guide/ when it's set to "path". See build configuration for more details.

Can I create deeper paths/routes for my grouped JS API docs?

Yes. You can use forward slash / in your group names which will be reflected in corresponding route names.

    "src": [
        ".src/core/*.js",                           // route @ api/
            "web": "./src/web/**.js",               // route @ api/web/
            "web/utils": "./src/web/utils/*.js",    // route @ api/web/utils/
            "other/deep/path": "./other/**/*.js",   // route @ api/other/deep/path
    "app": {
        "routing": "path"
    "dest": "./docs"

This is useful when routing method is set to "path". But it also works for "query" routing method. e.g. ?api=web/utils

Note that you should NOT use "api" or "api/.." when naming your groups. For JS files, "api" is already used as the default root path. For example, docs generated from JS files grouped with name "web" is available at route api/web.

How does linking work in JSDoc comments and Markdown files?

For links to get parsed, you should use the JSDoc @link tag in JSDoc comments. Links in markdown work no differently. But you should take some rules into consideration.

Linking in JSDoc Comments

In JSDoc, links are typically formated as {@link pathOrURL|label}. For the same route/page, you can simply use the namepath of the symbol to link to it as a bookmark. When linking to a symbol or bookmark on another route; the reference of the link should be considered depending on the routing method set in your build configuration.

For example, we want to reference our symbol: MyClass

Linking On/From Routing Method route/group name: mylib no group name
Same page doesn't matter {@link #MyClass|MyClass} {@link #MyClass|MyClass}
Different page query {@link ?api=mylib#MyClass|MyClass} {@link ?api#MyClass|MyClass}
Different page path {@link api/mylib/#MyClass|MyClass} {@link api/#MyClass|MyClass}

Note that when routing method is path and linking from a different page, the link reference is not preceded with a slash. A leading slash would make the link absolute, rather than relative; which wouldn't work with the application base path (if set).

More JSDoc Examples:

 *  {@link /absolute|Absolute path}         «—— navigates from domain root
 *  {@link relative/|Relative path}         «—— app.base is taken into account
 *  {@link MyClass|Symbol bookmark}         «—— symbol bookmark (parsed to #MyClass)
 *  {@link api/#MyClass|Symbol link}        «—— MyClass in default API route
 *  {@link api/mylib|`mylib`}               «—— mylib API route. Relative link
 *  {@link api/mylib#MyClass|`mylib`}       «—— MyClass in mylib API route. Relative link
 *  {@link ?api=mylib#MyClass|`mylib`}      «—— Same when routing method is `query` instead of `path`
 *  {@link #bookmark|Bookmark}              «—— regular bookmark, similar to symbol link

Linking in Markdown Files

Examples in Markdown:

[Absolute path](/absolute)
[Relative path](relative)
[Same Relative path](relative/)
[`MyClass` in default API route](api/#MyClass)
[`mylib` API route](api/mylib)
[`MyClass` in `mylib` API route](api/mylib#MyClass)
[Same when routing method is `query`](?api=mylib#MyClass) 
[Regular bookmark](#bookmark)
Link Usage {@link|External} OK
// {@link //|External} OK {@link|External} NOT OK. This will break the link as it would be considered a symbol name path.
Can I include additional static files within my documentation output?

Yes. You can define static asset files such as images, ZIPs, PDFs, etc via the assets option in your build configuration, and link to them in your docs. Defined assets will get copied over to the output directory.

Can I force Docma to parse markdown or HTML files with non-standard (or no) extensions?

Yes. For files with markdown content, append :md or :markdown suffix at the end of the file path. For HTML files, append :htm or :html.

    "src": { 
        "license": "./LICENSE:md",          // force-parsed as Markdown. SPA route @ ?content=license (query) or license/ (path routing)
        "article": "file.partial:html",     // force-parsed as HTML. SPA route @ ?content=article (query) or article/ (path routing)
        "my-lib": "./src/**/*.js"           // JS, API files. SPA route @ ?api=my-lib (query) or api/my-lib/ (path routing)
    "dest": "./docs"

For forcing JSDoc on JavaScript files without a proper extension you can use :js or :jsx but this is not recommended. Use jsdoc.includePattern of your build configuration instead.

How can I change the initial (default) page of the generated web app?

You change the entrance by setting the app.entrance option. Use content: prefix if the source is a markdown or HTML file; or api: prefix if the source is JS file(s).

    "src": [
        { "guide": "./" }
    "app": {
        "entrance": "content:guide"
    "dest": "./docs"

Now, the route for README content will be available both at / and ?content=guide (or at guide/ if routing method is "path"). See build configuration for more details.

How can I test the generated documentation (web app)?

Since Docma generates a static SPA, you can use any static files server to test it. For your convenience, Docma includes a simple server. Use docma serve command to serve your documentation locally for testing.

How to configure docma.json so that it is served the same way on both remote (e.g. GitHub Pages) and local?

Some directory structures might not work on some remote environments. For example, if you're using GitHub Pages for multiple documentations, you will need to create a separate directory for each documentation. i.e. <GHP-root>/library. So in this case; for the SPA to work; you need to set the app.base to /library.

When testing locally, it's recommended that you run docma serve from your project root (where docma.json resides); as is, without any target path. It will always adjust to your docma.json.

If your base should be different in your local vs remote/host; set the base for your remote host in your docma.json and run docma serve --base <for-local>. This will override the base while you're testing.

How can I hide/remove some of the content in the output generated from a markdown file?

If you're using the same markdown file on both GitHub repo and your Docma generated documentation; you can wrap that content with an HTML element having docma-ignore for class name. This will hide it in Docma generated output. If you want the content to be removed entirely, use the class name docma-remove instead. (Feature available since Docma v3.0.0).

<div class="docma-ignore">
    This is hidden in Docma generated web app, but visible in GitHub repo.
How can I debug the build process, documentation output and the web app?

Simply build your documentation with docma --debug (or set buildConfig.debug to true) which will enable all the following features:

Is there any example build configuration?

Docma is very configurable but you're only required to define very few options such as the source files (src) and the destination directory (dest) for a simple build.

For detailed examples, you can see Docma's own configuration file used to document Docma. And you can read the detailed documentation for build configuration, which also includes an example.

Documentation is built but I get ENOENT: no such file or directory error.

This is typically due to incorrect or missing application base definition. For example, try setting app.base to a meaningful path for your host environment, in your build configuration.

Symbols in sidebar outline is displayed incorrectly. (Zebra template)

This is typically a user / documenting issue. (And it's a good thing to see it visually with the sidebar outline).

First of all, run CLI with debug option enabled (i.e. docma --debug) to output parsed JSDoc data as JSON files and inspect how they your symbols/docs are parsed.

Generally this kind of issue is resolved by either using @memberof or @memberof! tags (notice the bang suffix) or instead; organizing via specifying the full name via @name tag. (Note that when you do, you'll also need to specify the type. e.g. @function if it's a method.)

Another reason for this could be that you are missing some symbols in your documentation. JavaScript files are generally grouped under a route name by specifying a group name in the src of the build configuration. Or if no group is specified, they'll be merged under the default group. If any level of a symbol is not defined in your documentation, you will get a broken tree. e.g. UndocumentedNamespace.DocumentedObject.

See this thread for more details.

Can I create my own template(s)?

Yes. See this section on creating/publishing custom templates.

Your question is not answered here? See issues here. Or open a new issue.