UNPKG

docdash-extended-xkloveme

Version:
188 lines (150 loc) 6.84 kB
# Docdash Extended Clement Moron excellent Docdash template extended with support for @category plugin and some navigation improvements. # Docdash [![license](https://img.shields.io/npm/l/docdash.svg)](LICENSE.md) A clean, responsive documentation template theme for JSDoc 4. ![docdash-screenshot](https://cloud.githubusercontent.com/assets/447956/13398144/4dde7f36-defd-11e5-8909-1a9013302cb9.png) ![docdash-screenshot-2](https://cloud.githubusercontent.com/assets/447956/13401057/e30effd8-df0a-11e5-9f51-66257ac38e94.jpg) ## Example See http://clenemt.github.io/docdash/ for a sample demo. :rocket: ## Install ```bash $ npm install docdash-extended-xkloveme ``` ## Usage Clone repository to your designated `jsdoc` template directory, then: ```bash $ jsdoc entry-file.js -t path/to/docdash-extended-xkloveme ``` ## Usage (npm) In your projects `package.json` file add a new script: ```json "script": { "generate-docs": "node_modules/.bin/jsdoc -c jsdoc.json" } ``` In your `jsdoc.json` file, add a template option. ```json "opts": { "template": "node_modules/docdash-extended-xkloveme" } ``` ## Sample `jsdoc.json` See the config file for the [fixtures](fixtures/fixtures.conf.json) or the sample below. ```json { "tags": { "allowUnknownTags": false }, "source": { "include": "../js", "includePattern": "\\.js$", "excludePattern": "(node_modules/|docs)" }, "plugins": ["plugins/markdown", "node_modules/docdash/categories"], "opts": { "template": "assets/template/docdash-extended-xkloveme/", "encoding": "utf8", "destination": "docs/", "recurse": true, "verbose": true }, "templates": { "cleverLinks": false, "monospaceLinks": false }, "categoriesFile": "./categories.json" } ``` ## Options Docdash supports the following options: ```json5 { "docdash": { "static": [false|true], // Display the static members inside the navbar "sort": [false|true], // Sort the methods in the navbar "sectionOrder": [ // Order the main section in the navbar (default order shown here) "Categories", "Classes", "Modules", "Externals", "Events", "Namespaces", "Mixins", "Tutorials", "Interfaces" ], "disqus": "", // Shortname for your disqus (subdomain during site creation) "openGraph": { // Open Graph options (mostly for Facebook and other sites to easily extract meta information) "title": "", // Title of the website "type": "website", // Type of the website "image": "", // Main image/logo "site_name": "", // Site name "url": "" // Main canonical URL for the main page of the site }, "meta": { // Meta information options (mostly for search engines that have not indexed your site yet) "title": "", // Also will be used as postfix to actualy page title, prefixed with object/document name "description": "", // Description of overal contents of your website "keyword": "" // Keywords for search engines }, "search": [false|true], // Display seach box above navigation which allows to search/filter navigation items "commonNav": [false|true], // Group all html code for <nav> in a nav.inc.html fetched on each page (instead of include it in each html page, save {navSize}×{nb html pages} which can be huge on big project) "collapse": [false|true|top], // Collapse navigation by default except current object's navigation of the current page, top for top level collapse "wrap": [false|true], // Wrap long navigation names instead of trimming them "typedefs": [false|true], // Include typedefs in menu "navLevel": [integer], // depth level to show in navbar, starting at 0 (false or -1 to disable) "private": [false|true], // set to false to not show @private in navbar "removeQuotes": [none|all|trim],// Remove single and double quotes, trim removes only surrounding ones "scripts": [], // Array of external (or relative local copied using templates.default.staticFiles.include) js or css files to inject into HTML, "ShortenTypes": [false|true], // If set to true this will resolve the display name of all types as the shortened name only (after the final period). "menu": { // Adding additional menu items after Home "Project Website": { // Menu item name "href":"https://myproject.com", //the rest of HTML properties to add to manu item "target":"_blank", "class":"menu-item", "id":"website_link" }, "Forum": { "href":"https://myproject.com.forum", "target":"_blank", "class":"menu-item", "id":"forum_link" } }, "scopeInOutputPath": [false|true], // Add scope from package file (if present) to the output path, true by default. "nameInOutputPath": [false|true], // Add name from package file to the output path, true by default. "versionInOutputPath": [false|true] // Add package version to the output path, true by default. } } ``` Place them anywhere inside your `jsdoc.json` file. ## Categories Docdash supports custom categories through jsdoc plugin - plugin is available from docdash package. To use categories you need to load the plugin in your jsdoc.json and point location of your categories file: ```json "plugins": [ "node_modules/docdash-extended-xkloveme/categories", ], "categoriesFile": "./categories.json" ``` Next you need to create your json with your category definitions where key is your category keyword - example categories.json ```json { "model": { "displayName": "Models and Collections" }, "component": { "displayName": "Components" } } ``` Now you can use @category tag in your docs. ```js /** * @category model */ ``` **If you have custom sectionOrder you need to add "Categories".** It is best to add Categories before all other sections because of how Docdash generates navigation elements. ## Contributors Thanks to [docdash](https://github.com/clenemt/docdash), [lodash](https://lodash.com) and [minami](https://github.com/nijikokun/minami). ## License Licensed under the Apache License, version 2.0. (see [Apache-2.0](LICENSE.md)).