Frequently Asked Questions

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

{ 
    "src": { 
        "my-lib": [
            "./dir/**/*.js", 
            "./another.js",
            "!./exclude/*.js"
        ]
    },
    "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".

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").

You simply define an object within the src option.

{
    "src": [
        { "guide": "./README.md" }
    ],
    "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.

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.

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.

• Absolute: If the link reference has a leading /, it's an absolute path. e.g. /absolute
• Relative: If it has a / but it's either in the middle or at the end, it's a relative path. e.g. relative/ or deep/relative.
• Symbol Bookmark: In JSDoc comments, if it has no /, then it's considered a symbol name path and parsed as a bookmark. e.g. name parsed to #name.
• API or Symbol Link: In both JSDoc and Markdown; if you're linking a symbol served from a different route, you should always include the full route path with the api keyword. For example;
  • api/ or api/mylib or api/mylib/#MyClass (when routing method is path)
  • ?api or ?api=mylib or ?api=mylib#MyClass (when routing method is query)
• Bookmark: You can still use regular bookmarks such as #bookmark.
• Content Link: Similar to relative link description above;
  • guide/ (when routing method is path)
  • ?content=guide (when routing method is query)

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

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)

External Links

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.

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.

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": "./README.md" }
    ],
    "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.

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.

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.

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.
</div>

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

• The build process will output detailed logs to the console,
• The web application will output web logs,
• Scripts running the app will not be minified,
• Docma will output raw JSDoc documentation data in JSON format; for each grouped JS files parsed.

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.

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.

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.

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