Automatic Documentation For JavaScript Projects — README, JSDoc & Mermaid

Misty Autumn Forest

Documentation.js

"docs-show": "firefox -new-tab ./docs/index.html -foreground",
"docs-gen": "npx documentation build {​​​​​​​src/utils/*.js,src/logic/*.js}​​​​​​​ --config documentation.yml -f html -o docs",
"docs": "npm run docs-gen && npm run docs-show"
toc:
- name: README
file: README.md
/docs

Pros:

Cons:

Docusaurus v2

/* eslint-disable */
const remarkMermaid = require("remark-mermaid");
const lunrSearch = require.resolve("docusaurus-lunr-search");
module.exports = {
title: "Comparator UI",
tagline: "OneToolBox TestCase Comparator UI",
url: "https://your-docusaurus-test-site.com",
baseUrl: "/",
onBrokenLinks: "throw",
onBrokenMarkdownLinks: "warn",
favicon: "img/favicon.ico",
organizationName: "ericsson", // Usually your GitHub org/user name.
projectName: "comparator-ui", // Usually your repo name.
themeConfig: {
navbar: {
title: "Comparator UI",
logo: {
alt: "Comparator UI Logo",
src: "img/logo.svg"
},
items: []
},
footer: {
style: "dark",
links: []
}
},
scripts: [
"https://cdnjs.cloudflare.com/ajax/libs/mermaid/8.8.4/mermaid.min.js",
"/init.js"
],
presets: [
[
"@docusaurus/preset-classic",
{
docs: {
sidebarPath: require.resolve("./sidebars.json"),
routeBasePath: "/",
remarkPlugins: [[remarkMermaid, { simple: true }]]
},
theme: {
customCss: require.resolve("./src/css/custom.css")
}
}
]
],
plugins: [lunrSearch]
};
/* eslint-disable */
window.addEventListener("load", () =>
mermaid.initialize({ startOnLoad: true })
);
{
"someSidebar": {
"Site Docs": ["README", "api"]
}
}
/docs/docs
"postinstall": "cd docs && npm i && mkdir docs && cd ..",
"docs-readme": "echo -e \"---\nid: README\nslug: /\n---\n$(cat README.md)\" > docs/docs/README.md",
"docs-api": "npx jsdoc2md {src/**/*.js} > docs/docs/api.md",
"docs": "npm run docs-readme && npm run docs-api && cd docs && npm run build && npm run serve"

Pros:

Cons:

Docsify

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Documentation</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
<meta name="description" content="Description" />
<meta
name="viewport"
content="width=device-width, initial-scale=1.0, minimum-scale=1.0"
/>
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple-dark.css"
/>
<style>
/* style the nav-bar to be much more visible */
.app-nav {
text-align: center;
font-size: 1.5rem;
position: relative;
background-color: rgba(0, 0, 0, 0.3);
margin-left: 0 !important;
right: 0 !important;
left: 0;
top: 0;
z-index: 1;
}
.app-nav > ul > li {
padding: 16px;
border-bottom: 4px solid var(--mono-tint2);
}
</style>
</head>
<body>
<div id="app"></div>
<script>
window.$docsify = {
name: "Documentation",
loadNavbar: true,
mergeNavbar: true, // Is this needed ?????????????
auto2top: true,
subMaxLevel: 3,
formatUpdated: "{MM}/{DD} {HH}:{mm}",
// logo: 'logo.png', // Add a logo if you wish
search: ["/", "/api"],
executeScript: true
};
</script>
<script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
<!-- plugins -->
<script src="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/js/docsify-themeable.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.js"></script>
<!-- mermaid -->
<script src="//unpkg.com/mermaid/dist/mermaid.js"></script>
<script src="//unpkg.com/docsify-mermaid@latest/dist/docsify-mermaid.js">
<script>
mermaid.initialize({ startOnLoad: true });
</script>
<style>
/* activate full width for content, for mermaid graphs benefit */
.markdown-section {
max-width: none;
}
</style>
</body>
</html>
* [README](/)
* [API](/api)
/docs/README.md
/docs/api.md
"docs-show": "npx docsify serve ./docs",
"docs-gen": "cp -u README.md docs/ && npx jsdoc2md {src/**/*.js} > docs/api.md",
"docs": "npm run docs-gen && npm run docs-show"

Pros:

Cons:

JSDoc + docdash

JSDoc3

docdash

{
"plugins": ["plugins/markdown"],
"source": {
"include": ["src", "README.md"],
"includePattern": ".+\\.js$",
"excludePattern": "(node_modules/|docs)"
},
"tags": {
"allowUnknownTags": true,
"dictionaries": ["jsdoc", "closure"]
},
"opts": {
"destination": "./docs/",
"readme": "./README.md",
"encoding": "utf8",
"private": true,
"recurse": true,
"template": "./node_modules/docdash"
},
"docdash": {
"search": true,
"scripts": ["https://unpkg.com/mermaid/dist/mermaid.js", "docs-init.js"]
}
}
/* eslint-disable */
window.addEventListener("load", () =>
mermaid.initialize({ startOnLoad: true })
);
"docs-show": "firefox -new-tab ./docs/index.html -foreground",
"docs-mermaid": "npx replace '<pre class=\"prettyprint source lang-mermaid\"><code>(((?!(<\\/code>))(\\s|\\S))+)<\\/code><\\/pre>' '<div class=\"mermaid\">$1</div>' -r --include=\"index.html\" ./docs/",
"docs-gen": "npx jsdoc -c .jsdoc.json && cp -u docs-init.js docs/",
"docs": "npm run docs-gen && npm run docs-mermaid && npm run docs-show"
/docs

Pros:

Cons:

Docma

"docs": "docma && docma serve ./docs"

Pros:

Cons:

DocumentJS

{
"sites": {
"docs": {
"glob": "{src/**/*.js,README.md}"
}
}
}
"docs-show": "firefox -new-tab ./docs/index.html -foreground",
"docs": "npx documentjs && rm -rf docs && mv ../docs . && npm run docs-show"
/docs

Pros:

Cons:

EsDoc

{
"source": "./src",
"destination": "./docs",
"plugins": [
{ "name": "esdoc-standard-plugin" },
{
"name": "esdoc-ecmascript-proposal-plugin",
"option": { "all": true }
},
{
"name": "esdoc-brand-plugin",
"option": {
"title": "Comparator UI",
"description": "The app for the testcase comparator feature",
"repository": "https://github.com/foo/bar",
"site": "http://my-library.org",
"image": "http://my-library.org/logo.png"
}
},
{
"name": "esdoc-undocumented-identifier-plugin",
"option": { "enable": true }
}
]
}
"docs-show": "firefox -new-tab ./docs/index.html -foreground",
"docs": "npx esdoc && npm docs-show"

Pros:

Cons:

EsDoc2

Conclusion

JSDoc with docdash is the winner.

Software architect and developer with web and functional JavaScript close to his heart. Worked many years with web solutions mainly within the IoT field.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store