dmd-readme-api
v1.0.0-beta.8
Published
A jsdoc2md template plugin generating elegant, compact one-page APIs in markdown, suitable for embedding in a README.md.
Downloads
22
Maintainers
Readme
dmd-readme-api
A jsdoc2md template plugin generating elegant, compact one-page APIs in markdown, suitable for embedding in a README.md
.
Installation
npm i --save-dev dmd-readme-api @liquid-labs/jsdoc-to-markdown @liquid-labs/dmd
Though designed as a plugin to the standard jsdoc2md, 'dmd-readme-api 'relies on additional features not present in the baseline tool. Refer to the custom jsdoc2md notes for additional details.
Usage
npx jsdoc2md \
--configure ./jsdoc.config.json \
--files 'src/**/*' \
--global-index-format grouped \
--name-format \
--plugin dmd-readme-api \
--plugin @liquid-labs/dmd \
--clever-links \
--no-cache
- You must specify '@liquid-labs/dmd' as the final plugin. See additional notes in the custom jsdoc2md notes.
- You must specify
--plugin
even if it's specified in thejsdoc.config.json
See below for further details on plugin andjsdoc.config.json
setting and refer to the formatting options section for additional options. - The
no-cache
avoids erroneously using previous renderings even when settings have changed. Rendering is fast enough that it's not really worthwhile to have the cache enabled as it can cause problems.
jsdoc.config.json
:
{
"plugins": [],
"recurseDepth": 10,
"source": {
"includePattern": ".+\\.(c|m)?js(doc|x)?$",
"excludePattern": "((^|\\/|\\\\)_|.+\\.test\\.(c|m)?jsx?$)"
},
"sourceType": "module",
"tags": {
"allowUnknownTags": true,
"dictionaries": ["jsdoc","closure"]
},
"templates": {
"cleverLinks": false,
"monospaceLinks": false
}
}
Note that jsdoc2md doesn't do anything with this file. It's passed through to jsdoc
. Some important notes:
- jsdoc2md and jsdoc are not fully integrated at this point; the 'plugins' here is ignored by jsdoc2md.
- You need to
tags.allowUnknownTags
true
or you won't get support for the handy jsdoc2md@category
tag (and a few others). - If you want to pick up
.mjs
and.cjs
files, you must overridesource.encludePattern
. How this works is that jsdoc2md will read in everything matched by the--files
(or"files"
in.jsdoc2md.config.json
) and then apply the include and exclude patterns defined injsdoc.config.json
. - The
templates
are effectively ignored currently and are shown here with their default values.
Features
Extended syntax:
- You can
@hide
or@ignore
function parameters in the documentation; see hide parameters.
New options:
- Adds configurable section title to main output; see the title format option.
- Adds support for simple list and grouped global identifiers; see the global index format option.
Layout improvements (As compared to the base dmd template):
- Only display summary (first line) of documentation in the index and show full documentation in the linked entry. (This makes thins a lot more compact.)
- Added sorting of the underlying data so everything is displayed in a consistent order.
- Add links to the source code where an identifier is defined; see source links option.
- Add links from identifier documentation back to the both identifier "kind" and "category" indexes; see index links options.
- Can suppress the display of 'Category' in identifier documentation. Displaying the category is less important when we have
grouped
the items already, and this makes the code more compact. See category display and index links options. - The
name-format
option is also effective on parameter names in table layout mode. - The
name-format
option is also effective in class name index links and section headers. - Fixes escape issues with the display of 'default values' and displays string values in plain text (rather than monospaced).
- When the identifer category is displayed, the category label is now a link back to the category index.
- Fixes HTML style
<table>
s and uses native Markdown tables instead. - Fixes HTML
<code>
tags and uses Markdown native backtick instead. - Uses compact method signatures in any index; much easier to read.
- Render
@throws
on one line if only one@throws
defined, otherwise generate list. - Makes the 'Examples' section more compact.
- Only display identifier 'kind' when it's complex; otherwise it's obvious based on the section.
Extended syntax
Hide parameters
- A parameter whose description contains the a
@hide
or@ignore
tag will not be included in documentation. - This can be useful for parameters which are intended for use by the code/system.
- Consider noting such variables somewhere in the documentation (under a 'Common parameters' section at the start of the API documentation for example).
Plain and monospace link tags
- Along with '@liquid-labs/dmd', we add support for jsdoc standard
{@linkplain}
and{@linkcode}
tags. - See also the clever and monospace link formatting options.
- These are not implemented in the standard 'dmd' package; see custom jsdoc2md notes for further details.
Format options
Note, some options can be set via the command line and via .jsdoc2md.json
while others can only be set via the .jsdoc2md.json
configuration file (placed in the project root).
title
heading-depth
clever-links
andmonospace-links
no-gfm
global-index-format
member-index-format
module-index-format
param-list-format
hide-categories
source-links
index-links
name-format
private
Title
- By default, the generated document will have a title 'API reference'.
- You can override this by setting "title" in the
.jsdoc2md.json
configuration file (cannot be set via command line options). - Setting the "title" option to literal
false
will suppress the title altogether. This is useful when you have a custom introduction to the API section and you want the API documentation to flow into it. Note that the heading depth is unaffected by this option.
Heading depth
- The default depth of the title header is '2' (e.g., '##').
- You can change this by setting
heading-depth
in the.jsdoc2md.json
configuration file or with--heading-depth
on the CLI.
Clever and monospace links
- By default
{@link}
tags render the link label in plain text. You can use{@linkplain}
and{@linkcode}
tags to explicitly control rendering. - Setting
clever-links
true
will render links pointing to a URL in plain text and all others (which presumably point to internal identifiers such as a function or field) in monospace. - Setting
monospace-links
totrue
will render all{@link}
tags in monospace format. This option is ignored inclever-links
is true. - You can set
clever-links
andmonospace-links
in the.jsdoc2md.json
configuration file or use the--clever-links
and--monospace-links
command line option. (This requires the '@liquid-labs/jsdoc-to-markdown' tool variation; see custom jsdoc2md notes for further details.)
Github flavored markdown
- By default, dmd generated GitHub flavored markdown.
- If this is a problem, you can set
no-gfm
true
in the.jsdoc2md.config.json
or use the--no-gfm
command line option.
Global index format
- Controls how the display of the global identifiers index. The default index format is
dl
, which can be pretty bulky. - This DMD adds support for
grouped
andlist
formats. Other options aredl
,table
. - We recommend the
grouped
setting, which will organize global identifiers by 'kind' and then@category
, if present. If you don't use@category
, thengrouped
is more or less equivalent tolist
. - This option can be set with
global-index-format
in the.jsdoc2md.json
configuration file or with--global-index-format
on the CLI.
Member index format
- Controls how the member identifiers index (of a
@module
or@namespace
for example) is displayed. Default isgrouped
. - May be set using
member-index-format
in.jsdoc2md.config.js
or with--member-index-format
on the command line. Can begrouped
orlist
.
Module index format
- Controls how module identifier indexes are displayed;
dl
by default. - Can be set with
module-index-format
in the.jsdoc2md.config.json
file or with the--module-index-format
option on the command line. Supportsnone
,grouped
,table
, anddl
.
Parameter list format
- Controls how function parameters are displayed;
table
by default. - Can be set with
param-list-format
in the.jsdoc2md.config.json
file or with the--param-list-format
option on the CLI. Supporttable
andlist
.
Category display
- By default, the category of an identifier is included in the documentation when a
{@category}
tag has been included in the jsdoc documentation. - This can be suppressed by setting the
hide-categories
option totrue
. - This option can currently only be set in the
.jsdoc2md.config.js
.
Source links
- By default, a link to the source where an identifier is implemented is included in the identifier documentation.
- You can turn suppress these source links by setting
hide-source-links
to true. - This option can currently only be set in the
.jsdoc2md.config.js
.
Index links
- By default, links back to the 'kind' indexes (if it exists) is displayed in the identifier documentation.
- If
hide-categories
istrue
, we also display a link back to the identifier category index, if any. (The category label itself is a link if present.) - These links can be suppressed by setting the
hide-index-links
totrue
. - This option can currently only be set in the
.jsdoc2md.config.js
.
Name format
- By default, identifier names are rendered in plain case.
- You almost certainly want to override this and set
name-format
in the.jsdoc2md.config.json
file totrue
or include the--name-format
option on the CLI. This will cause identifier names to render in monospace. (e.g.,foo
).
Private identifiers
- Controls the display of identifiers marked
@private
; by default they are hidden. - Can be set with
private
in.jsdoc2md.config.json
(true
orfalse
, the default) or with the--private
option on the CLI.
Examples
History
Our main goal was to embed an easy to read, automatically generated API in our README.md
files.
Our first thought, after some research, was to use Docusaurus, hosted on GitHub. We found this script and, even more promising, this library, which seemed to be exactly what we wanted because Docusaurus supports rendering React components and the script and library promised to generate API documentation as a Docusaurus doc.
Unfortunately, neither worked out. The script has a lot of assumptions and the library just straight up wouldn't work. It loosk like it hasn't been updated since Docusaurus 2.0[^1]. Too bad, it's the right idea.
[^1]:as of 2024-02-09
We instead turned to tackling the goals in two steps. The first step was rendering the jsdocs in markdown and appending those to a simple template.
So, the way jsdocs works is gather's all the doc information into JSON data. The data representing the parsed jsdocs is passed through a templating system to generate the output. We tried many different templates, expecting to find one that worked off the shelf.
However after trying many dmd templates,[^2] we found they were all lacking something we needed (or really wanted). The biggest problem was that none of them handled indexing the methods really well. And we tried all different configurations and setups: using @module
and making everything a @memberof
the module, creating a @namespace
, tricks to create docs by the file (like how Java Docs do it), but nothing came out satisfactorily. The persistent problem was that it was printing the whole description in the index summary, making them difficult to read and entirely redundant.
[^2]: dmd-clean, dmd-bitbucket, npm-clear, and @godaddy/dmd
A little less significant, all the existing templates were using the full method signatures in the index summary too. If the other problem hadn't been dispositive, this also made for clunky reading, though we probably would have lived with it if that was the only problem.
In some of them, the intra-page links didn't work, so those were a no-go. And none of them had really good looking output, in our opinion. May mixed in HTML unecessarily.
But one nice thing about jsdoc2md is it's "relatively" easy to customize. You have to wrap your head around their templating system... and frankly the tag documentation is a bit lacking. It's really not clear when you should use @module
, what's the difference between @kind
and @type
, or what a @namespace
is for, etc.. So it took some experimentation and walking through the template to really understand how things were being used because many details in the output of the existing templates were unexpected in a bad way.
So, anyway, there's a template system called dmd which process handlebarjs and jsdoc2md uses, dmd and you can make little template partials to override snippets of their template. So that's what we did, and that's what this library is.
We tried to cleanup a lot of things in template. You can see the full list of modifications in the DEV_NOTES.md
. The result is a template that, when used jsdoc2md, creates nice, relatively compact Markdown you can attach right to your README.md
.
Custom jsdoc2md notes
'dmd-readme-api' relies on a few features not found in the base implementations 'jsdoc-to-markdown' and 'dmd' implementations. We hope the features are integrated into the baseline tools, but until then, it is necessary to us the '@liquid-labs/jsdoc-to-markdown' and '@liquid-labs/dmd' derivatives.
- '@liquid-labs/dmd' adds support for "clever links" and "monospace links" options. Changes submitted to the 'dmd' project in PR #86 and 'jsdoc-to-markdown' in PR #302.
- '@liquid-labs/dmd' adds support for the
{@linkplain}
and{@linkcode}
tags. Changes also submitted to 'dmd' PR #86. - '@liquid-labs/dmd' adds support for grouping globals as well well as children. This is necessary for our
grouped
global index format option. Changes have been submitted to the 'dmd' project in PR #86. - '@liquid-labs/dmd' adds a
hasMultipleIdentifiers
helper function which is used to determine when some labels can be discarded (thus saving space). These changes have not yet been submitted to the 'dmd' project (waiting on other changes to go through). - '@liquid-labs/jsdoc-to-markdown' adds support for
--clever-link
and--monospace-link
CLI options. Submitted to 'jsdoc-to-markdown' in PR #302. - '@liquid-labs/jsdoc-to-markdown' removes 'dmd' as a hardcoded
require
and allows us to plug in our derivative@liquid-labs/dmd
variation. Changes will be submitted to 'jsdoc-to-markdown' once other changes have been accepted.
TODOs
- Support hiding the 'kind' index independently,
hide-kind-index-links
. - Support explicit control over the 'category' index:
category-links
with possible valuealways
,never
, andconditional
(current behavior and default). - Support
navigation-link-style
with possible valuescompact
(current behavior and default),subtitle
(right under the title),end
(at the end of the entry body), andbookend
(both under the title and at the end of the entry body).
Contributing
Plase feel free to submit any bug reports or feature suggestions. You're also welcome to submit patches of course. We don't have a full contributors policy yet, but you can post questions on our discord channel. It's not monitored 24/7, but you should hear back from us by next business day generally.
Support and feature requests
The best way to get free support is to submit a ticket. You can also become a patron for as little as $1/month and get priority support and request new feature on all Liquid Labs open source software. You can get these benefits and support our work at patreon.com/liquidlabs.