!esdoc-plugin-enhanced-navigation
A plugin for ESDoc that replaces the left-hand navigation / class browser with an enhanced version which includes a folder accordion, a context menu that opens associated Github / NPM links and support for grouping managed packages via JSPM (and soon NPM) in separate sections from the local source.
Installation steps:
- Install esdoc in devDependencies in package.json.
- Install esdoc-plugin-enhanced-navigation in devDependencies in package.json.
- Optionally install esdoc-plugin-jspm if using JSPM / SystemJS in devDependencies in package.json.
- Create an .esdocrc or esdoc.json configuration file adding the plugin.
- Optionally add an .esdocrc or esdoc.json configuration file in all JSPM managed packages to link.
- Run ESdoc then profit!
For more information view the ESDoc tutorial and ESDoc Config documentation.
It should be noted that all TyphonJS repos now are standardizing on .esdocrc for the ESDoc configuration file. Both .esdocrc and esdoc.json are supported by the esdoc-plugin-jspm and forthcoming esdoc-plugin-npm plugin.
As an alternate and the preferred all inclusive toolchain please see typhonjs-npm-build-test for a NPM package which contains several dependencies for building / testing ES6 NPM modules including all TyphonJS ESDoc plugins. A separate package only containing the TyphonJS ESDoc plugins is also available: typhonjs-node-esdoc
Additionally typhonjs-core-gulptasks provides a NPM package which contains several pre-defined Gulp tasks for working with JSPM / SystemJS, ESLint and ESDoc generation.
For the latest significant changes please see the CHANGELOG.
If installing and working directly with esdoc-plugin-enhanced-navigation the following is an example integration including JSPM support via esdoc-plugin-jspm for package.json:
``
{
...
"devDependencies": {
"esdoc": "^0.4.0",
"esdoc-plugin-enhanced-navigation": "^0.1.0",
"esdoc-plugin-jspm": "^0.6.0", // Optional if using JSPM
"jspm": "^0.16.0" // Optional if using JSPM
},
"scripts": {
"esdoc": "esdoc -c .esdocrc"
},
"jspm": {
"main": "",
"dependencies": {
...
},
"devDependencies": {
...
}
}
}
`
And the .esdocrc or esdoc.json configuration file:
`
{
"title": "",<br /> "source": "src",<br /> "destination": "docs",<br /> "plugins": <br /> [ <br /> { "name": "esdoc-plugin-jspm" }, // Optional if using JSPM<br /> { <br /> "name": "esdoc-plugin-enhanced-navigation",<br /> "option:<br /> {<br /> "showAllFiles": "true" // (Optional) If set to true then all doc tags will show the associated file name; default is false.<br /> }<br /> }<br /> ]<br />}<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"></code>esdoc-plugin-enhanced-navigation<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> accepts the following configuration option:<br />- showAllFiles - If set to true then all doc tags will show the associated file name; default is false. </p><p class="my-3">By default for folders where all files export a single default or named export which matches the file name then the file name for this single export is hidden. This is useful for efforts like TyphonJS which has a strict naming policy where each file only has a default export which matches the file name. </p><p class="my-3">------</p><p class="my-3">Given the NPM script defined in </code>package.json<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> then simply run </code>npm run esdoc<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">.</p><p class="my-3">------</p><p class="my-3">Below is a demo image of the replaced left-hand navigation. A few of the pertinent details include that the local source is grouped at the top section with any JSPM / NPM managed source code grouped in follow up sections. For folders where all files export a single default or named export which matches the file name the file name is omitted. While not pictured a context click on folders and source code opens a context menu which will provide links to Github or NPM depending on the code being managed. For the context menu links to work for NPM packages you must include the <a href="https://docs.npmjs.com/files/package.json#repository" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">repository field</a> in </code>package.json`. JSPM currently supports packages from Github and NPM; Github packages are colored orange and NPM packages are colored light red. Aliased JSPM packages where the assigned name does not match the package name the package / folder uses italic styling with the aliased name followed by the actual package name in parentheses. </p><p class="my-3">!<a href="https://i.imgur.com/JBgVSKZ.png" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">esdoc-plugin-enhanced-navigation demo</a><br /></p></div><div class="flex justify-center absolute inset-x-0 bottom-0 bg-gradient-to-t from-background via-background to-transparent pb-4 pt-16"><button data-slot="button" class="inline-flex items-center justify-center whitespace-nowrap text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50 h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevron-down mr-1 h-4 w-4"><path d="m6 9 6 6 6-6"></path></svg>Show more</button></div></div></div><template id="P:3"></template><template id="P:4"></template></div></div></div><script>self.__next_f.push([1,"2b:[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}]\n2c:[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^0.0.4\"}]\n2d:[\"$\",\"$L5\",\"taffydb\",{\"href\":\"/package/taffydb\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"taffydb\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^2.0.0\"}]]}]\n"])</script><script>self.__next_f.push([1,"2e:[\"$\",\"div\",null,{\"data-slot\":\"card\",\"className\":\"bg-card text-card-foreground flex flex-col gap-6 rounded-xl border shadow-sm py-4 lg:col-span-2\",\"children\":[[\"$\",\"div\",null,{\"data-slot\":\"card-header\",\"className\":\"@container/card-header grid auto-rows-min grid-rows-[auto_auto] items-start gap-2 px-6 has-data-[slot=card-action]:grid-cols-[1fr_auto] [.border-b]:pb-6 pb-2\",\"children\":[\"$\",\"div\",null,{\"data-slot\":\"card-title\",\"className\":\"font-semibold flex items-center gap-2 text-base\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-wrench h-4 w-4\",\"children\":[[\"$\",\"path\",\"cbrjhi\",{\"d\":\"M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94l-3.76 3.76z\"}],\"$undefined\"]}],\"Dev Dependencies\",[\"$\",\"span\",null,{\"data-slot\":\"badge\",\"className\":\"inline-flex items-center justify-center rounded-md border px-2 py-0.5 font-medium w-fit whitespace-nowrap shrink-0 [\u0026\u003esvg]:size-3 gap-1 [\u0026\u003esvg]:pointer-events-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive transition-[color,box-shadow] overflow-hidden border-transparent bg-secondary text-secondary-foreground [a\u0026]:hover:bg-secondary/90 ml-auto text-xs\",\"children\":3}]]}]}],[\"$\",\"div\",null,{\"data-slot\":\"card-content\",\"className\":\"px-6\",\"children\":[\"$\",\"div\",null,{\"className\":\"grid gap-1 sm:grid-cols-2 lg:grid-cols-3\",\"children\":[[\"$\",\"$L5\",\"jspm\",{\"href\":\"/package/jspm\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"jspm\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^0.16.0\"}]]}],[\"$\",\"$L5\",\"typhonjs-config-eslint\",{\"href\":\"/package/typhonjs-config-eslint\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"typhonjs-config-eslint\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^0.4.0\"}]]}],[\"$\",\"$L5\",\"typhonjs-npm-build-test\",{\"href\":\"/package/typhonjs-npm-build-test\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[\"$L30\",\"$undefined\"]}],\"typhonjs-npm-build-test\"]}],\"$L31\"]}]]}]}]]}]\n"])</script><script>self.__next_f.push([1,"30:[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}]\n31:[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^0.4.0\"}]\n"])</script><div hidden id="S:3"><div data-state="inactive" data-orientation="horizontal" role="tabpanel" aria-labelledby="radix-_R_aav5ubrb_-trigger-dependencies" hidden="" id="radix-_R_aav5ubrb_-content-dependencies" tabindex="0" data-slot="tabs-content" class="flex-1 outline-none mt-6"></div></div><script>$RS=function(a,b){a=document.getElementById(a);b=document.getElementById(b);for(a.parentNode.removeChild(a);a.firstChild;)b.parentNode.insertBefore(a.firstChild,b);b.parentNode.removeChild(b)};$RS("S:3","P:3")</script><div hidden id="S:4"><div data-state="inactive" data-orientation="horizontal" role="tabpanel" aria-labelledby="radix-_R_aav5ubrb_-trigger-versions" hidden="" id="radix-_R_aav5ubrb_-content-versions" tabindex="0" data-slot="tabs-content" class="flex-1 outline-none mt-6"></div></div><script>$RS("S:4","P:4")</script><script>$RC("B:1","S:1")</script></body></html>