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"
.
"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"
).
README.md
and rename its route?
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 routeapi/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.
/
, it's an absolute path. e.g. /absolute
/
but it's either in the middle or at the end, it's a relative path. e.g. relative/
or deep/relative
./
, then it's considered a symbol name path and parsed as a bookmark. e.g. name
parsed to #name
.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
.guide/
(when routing method is path
)?content=guide
(when routing method is query
)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
*/
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 | |
---|---|---|
https://domain.com |
{@link https://domain.com|External} |
OK |
//domain.com |
{@link //domain.com|External} |
OK |
domain.com |
{@link domain.com|External} |
NOT OK. This will break the link as it would be considered a symbol name path. |
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.
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 (wheredocma.json
resides); as is, without any target path. It will always adjust to yourdocma.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:
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.
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.
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.
Your question is not answered here? See issues here. Or open a new issue.