{"id":22903018,"url":"https://github.com/amekusa/docolatte","last_synced_at":"2025-07-14T20:38:24.345Z","repository":{"id":57214129,"uuid":"296827754","full_name":"amekusa/docolatte","owner":"amekusa","description":"🍫 Bittersweet theme for JSDoc 4","archived":false,"fork":false,"pushed_at":"2024-03-30T08:42:38.000Z","size":17463,"stargazers_count":8,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"trunk","last_synced_at":"2025-07-07T06:46:47.841Z","etag":null,"topics":["documentation","jsdoc","jsdoc-template","jsdoc-theme","responsive","theme"],"latest_commit_sha":null,"homepage":"https://amekusa.github.io/docolatte/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amekusa.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-19T09:01:19.000Z","updated_at":"2025-06-27T15:52:53.000Z","dependencies_parsed_at":"2024-09-23T20:04:11.905Z","dependency_job_id":"101aefdd-055a-4af5-86d4-a5d434b94e50","html_url":"https://github.com/amekusa/docolatte","commit_stats":{"total_commits":311,"total_committers":2,"mean_commits":155.5,"dds":0.1961414790996785,"last_synced_commit":"971b8eee9d28a33da128d54b19eb8e6e6024b3fb"},"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"purl":"pkg:github/amekusa/docolatte","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amekusa%2Fdocolatte","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amekusa%2Fdocolatte/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amekusa%2Fdocolatte/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amekusa%2Fdocolatte/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amekusa","download_url":"https://codeload.github.com/amekusa/docolatte/tar.gz/refs/heads/trunk","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amekusa%2Fdocolatte/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265344886,"owners_count":23750570,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","jsdoc","jsdoc-template","jsdoc-theme","responsive","theme"],"created_at":"2024-12-14T02:30:44.057Z","updated_at":"2025-07-14T20:38:24.307Z","avatar_url":"https://github.com/amekusa.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [Docolatte](https://amekusa.github.io/docolatte/)\n[![NPM Version](https://img.shields.io/npm/v/docolatte?style=for-the-badge\u0026label=npm%20package)](https://www.npmjs.com/package/docolatte) [![NPM License](https://img.shields.io/npm/l/docolatte?style=for-the-badge)](https://github.com/amekusa/docolatte/blob/trunk/LICENSE)\n\n:chocolate_bar: Bittersweet theme for JSDoc 3 \u0026 4\n\n\u003c!-- TOC depthfrom:2 --\u003e\n\n- [Docolatte v4 is out! :tada:](#docolatte-v4-is-out-tada)\n    - [New Features](#new-features)\n    - [Fixes](#fixes)\n- [Notes for users](#notes-for-users)\n- [Screenshots](#screenshots)\n    - [Light Theme](#light-theme)\n    - [Dark Theme](#dark-theme)\n    - [Source](#source)\n    - [Mobile](#mobile)\n- [Working Sample](#working-sample)\n- [Features](#features)\n    - [Keyboard-only Search \u0026 Navigation](#keyboard-only-search--navigation)\n    - [Interactive TOC Table of Contents](#interactive-toc-table-of-contents)\n- [Install](#install)\n- [Usage](#usage)\n- [Customize](#customize)\n    - [Available Options](#available-options)\n- [Custom Assets](#custom-assets)\n    - [More complex options](#more-complex-options)\n        - [Loading remote CSS \u0026 JS](#loading-remote-css--js)\n        - [Importing Node modules](#importing-node-modules)\n        - [Private import](#private-import)\n        - [Ordering imports](#ordering-imports)\n- [Customizing CSS Variables](#customizing-css-variables)\n- [License](#license)\n\n\u003c!-- /TOC --\u003e\n\n## Docolatte v4 is out! :tada:\n\n### New Features\n- **[New]** Now it's **fully compatible with JSDoc 4!** (from Docolatte v4.3)\n- **[New]** Nicely format multi-line `@license` text.\n  - Converts line-breaks into `\u003cbr\u003e` tags.\n  - Converts URLs begin with `http(s)://` into `\u003ca\u003e` tags.\n  - Can be toggled `Show all/Hide`.\n- Finally, **dark theme** is implemented!\n- All the colors and fonts are now **CSS variables**, which means you can customize the overall look \u0026 feel of Docolatte just by overwriting the variables in your custom CSS. On top of that, you can customize light theme and dark theme separately.\n- A lot of design improvements\n- Added icons to variables and functions in TOC\n- Added \"Scroll to Top\" button\n- URL hash is now synced with the current heading as the page scrolls\n- Several new options (See below for details)\n\n### Fixes\n- Eliminated the possibilities of broken links shown in search results.\n- Now SVG icons are properly shown without any warning for a local site (browsed with `file://` protocol).\n\n## Notes for users\nWhat's new in the latest update?\n\u003e See: [CHANGELOG.md](https://github.com/amekusa/docolatte/blob/trunk/CHANGELOG.md)\n\nWhat's coming out in the next update?\n\u003e See: [TODO.md](https://github.com/amekusa/docolatte/tree/trunk/TODO.md)\n\nIs this compatible with JSDoc v4.x?\n\u003e Yes! Now it's fully compatible with JSDoc 4. JSDoc 3 is still supported as well.\n\n\n## Screenshots\n\n### Light Theme\n![screenshot class](https://raw.githubusercontent.com/amekusa/docolatte/trunk/gallery/light.png)\n\n### Dark Theme\n![screenshot class](https://raw.githubusercontent.com/amekusa/docolatte/trunk/gallery/dark.png)\n\n### Source\n![screenshot source](https://raw.githubusercontent.com/amekusa/docolatte/trunk/gallery/source.png)\n\n### Mobile\n| Menu:Off | Menu:On  |\n|:--------:|:--------:|\n| ![screenshot mobile menu off](https://raw.githubusercontent.com/amekusa/docolatte/trunk/gallery/mobile.png) | ![screenshot mobile menu on](https://raw.githubusercontent.com/amekusa/docolatte/trunk/gallery/mobile-menu.png) |\n\n## Working Sample\n[https://amekusa.github.io/docolatte](https://amekusa.github.io/docolatte/)\n\n\n## Features\n- Switchable dark/light themes\n  - Theme preference can be saved to the browser's local storage\n  - Can be synced with the user's system preference\n- Responsive design with a wide variety of screen widths supported\n- Indexed search, which:\n  - is very quick\n  - works on the local, without a server\n- Code highlighting with [highlight.js](https://highlightjs.org/)\n- Customizability\n  - You can customize:\n    - Header text, URL, and icon in the header\n    - Copyright \u0026 license text in the footer\n    - Meta tags, language settings, etc.\n  - All the highlight.js themes are supported\n  - Custom CSS and JS are supported\n  - All the colors and fonts are easily customizable thanks to CSS variables\n- Lightweight, no bloat\n  - Docolatte doesn't rely on any frameworks for its front-end codebase. They are just basic JS, CSS, and HTML, but coded with good care.\n\n### Keyboard-only Search \u0026 Navigation\nYou can easily navigate the entire site without using a mouse but only a keyboard. You don't need to click on the search box to type in.\n\n[\u003cimg src=\"https://raw.githubusercontent.com/amekusa/docolatte/trunk/gallery/demo-keyboard-only-navigation.png\"\u003e](https://www.youtube.com/watch?v=-HefBq5ZA40)\n\n### Interactive TOC (Table of Contents)\nThe TOC on the sidebar is always synced with the current section you are looking at.\n\n[\u003cimg src=\"https://raw.githubusercontent.com/amekusa/docolatte/trunk/gallery/demo-interactive-toc.png\"\u003e](https://www.youtube.com/watch?v=Ejo8vogt920)\n\n\n## Install\n```sh\nnpm i --save-dev docolatte\n```\n\n\n## Usage\nSpecify the path to docolatte ( normally: `node_modules/docolatte` ) as the JSDoc template with `-t` option of `jsdoc` command:\n\n```sh\njsdoc entry-file.js -t node_modules/docolatte\n```\n\nOr set the path to `opts.template` in your JSDoc configuration file:\n\n```json\n{\n  \"opts\": {\n    \"template\": \"node_modules/docolatte\"\n  }\n}\n```\n\n\n## Customize\nYou can customize docolatte by setting options in JSDoc configuration file like this example:\n\n```json\n{\n  \"templates\": {\n    \"docolatte\": {\n      \"import\": [\n        \"custom.css\",\n        \"custom.js\"\n      ],\n      \"branding\": {\n        \"title\": \"My Project\",\n        \"link\":  \"https://example.com/project/\",\n        \"icon\":  \"home\",\n        \"font\": {\n          \"size\":   \"1.5em\",\n          \"family\": \"Helvetica, sans-serif\"\n        }\n      },\n      \"code\": {\n        \"theme\": \"nord\"\n      },\n      \"meta\": {\n        \"title\":       \"My Project\",\n        \"description\": \"Welcome to my project.\",\n        \"keywords\":    \"awesome, cool\",\n      },\n      \"footer\": {\n        \"copyright\": \"\u0026copy; 2023 John Programmer\",\n        \"license\":   \"Licensed under the Apache License 2.0\"\n      }\n    }\n  }\n}\n```\n\nYou can see **the full list of available options here: [lib/defaults.json](https://github.com/amekusa/docolatte/blob/trunk/lib/defaults.json)**. Copy this file and edit it as you like.\n\n### Available Options\nThe following list is written in YAML format for the sake of readability.\nYou need to write the actual config in JSON format just like the above example.\n\n```yml\n# Docolatte specific options\ntemplates.docolatte:\n  import: Custom asset files to import (Explained later)\n  minify: Whether to use minified JS and CSS [default:true]\n\n  # Settings for the header on the top left\n  branding:\n    title: Title text\n    link:  Link URL of the title\n    icon:  Icon on the left [default:'home']\n           # See https://feathericons.com/\n\n    # Font settings for the title\n    font:\n      size:   Font size\n      family: Font family\n\n  # Settings for code blocks\n  code:\n    theme: highlight.js theme [default:'base16/espresso']\n           # See https://highlightjs.org/static/demo/\n\n    # Settings for `@example` blocks\n    examples:\n      captionPrefix: Prefixes to mark a line as a caption\n        # Default values:\n        - '// '\n        - '- '\n        - '# '\n        # Example:\n        #   `@example // This text is parsed as a caption`\n\n  # Settings for light/dark themes\n  lightSwitch:\n    hide: Whether to hide the switching button [default:false]\n    default: Default theme [default:'auto']\n             # NOTE: 'auto' theme tries to sync with\n             #       user's system preference\n    icons: Icons of the button for each theme\n\n  # Settings for search\n  search:\n    limit: Max number of items shown in a dropdown menu [default:8]\n    placeholder: Placeholder text for the search box\n\n    hint:\n      hide: Whether to hide the hint [default:false]\n      body: Hint text\n\n    keys: Keys of a doclet to match for search queries\n          # See https://www.fusejs.io/api/options.html#keys\n\n  # Settings for TOC\n  toc:\n    icons:\n      variables: Whether to hide icons for variables\n      functions: Whether to hide icons for functions\n\n    # List of menu sections in order\n    menus: {\n      # Key   = Section key\n      # Value = Heading text of the section\n      #\n      # Available section keys:\n      #   tutorials\n      #   modules\n      #   externals\n      #   namespaces\n      #   classes\n      #   interfaces\n      #   events\n      #   mixins\n      #   globals\n    }\n\n    allowHorizontalScroll: [default:false]\n      # If false, Docolatte tries to insert \u003cwbr\u003e tags into TOC items\n      #    to avoid long item names to trigger horizontal scroller.\n      # If true, Docolatte does not try to insert \u003cwbr\u003e tags.\n\n  # Settings for the home page (index.html)\n  home:\n    package:\n      hide: Whether to hide the package.json info [default:false]\n\n  # Settings for README \u0026 tutorials\n  readme:\n    truncate: Whether to enable the truncation tags [default:true]\n      # This removes the content between\n      # \u003c!--TRUNCATE:START--\u003e and \u003c!--TRUNCATE:END--\u003e\n\n    emoji:\n      replace: Type(s) of emoji to be replaced [default:'colons']\n        # Available types:\n        - 'colons'\n        - 'unified'\n        - 'emoticons'\n        - 'emoticons_with_colons'\n\n      options: # Options for js-emoji\n        replace_mode: [default:'unified'],\n        allow_native: [default:true]\n        # See https://github.com/iamcal/js-emoji\n\n  # Settings for meta tags\n  meta:\n    lang:        `lang` attribute of \u003chtml\u003e [default:'en']\n    title:       Content of \u003ctitle\u003e element [defaults to `branding.title`]\n    description: `content` attribute of \u003cmeta name=\"description\"\u003e\n    keywords:    `content` attribute of \u003cmeta name=\"keywords\"\u003e\n    author:      `content` attribute of \u003cmeta name=\"author\"\u003e\n    favicon:     Favicon image URL(s). Use array for multiple entries\n\n  # Settings for the footer\n  footer:\n    copyright: Copyright text\n    license:   License text\n    hide:      Whether to hide the footer\n\n  # Settings for data manipulation\n  data:\n    exlude: Doclet items to exclude (longname)\n    removeOrphans: Whether to remove orphaned doclet items [default:true]\n\n  # Settings for minor tweakings\n  tweak:\n    nojekyll: If `true`, places `.nojekyll` file\n              at the root of the output directory [default:true]\n              # This is useful if you publish the docs to github-pages\n\n    syncHash: When to sync location hash [default:'scrollend']\n      # Available values:\n      - 'scroll'     # This may result in \"flooding\" browser history\n      - 'scrollend'  # Recommended\n      - false        # Doesn't sync location hash at all\n\n# All the options for the JSDoc's default theme\n# are also compatible with Docolatte.\ntemplates.default: { ... }\n# See https://jsdoc.app/about-configuring-default-template.html\n```\n\n## Custom Assets\nWith the **`import`** option, you can use your own assets like CSS, JavaScript images, etc. for your documentation site.\n\n```json\n\"import\": [\n  \"my-scripts/alfa.js\",\n  \"my-styles/bravo.css\",\n  \"my-fonts/charlie.woff\"\n]\n```\n\nThis config results in copying the files to subdirectories under the JSDoc output directory.\nThe subdirectory name is determined by the file extension.\n\n| File Ext. | Output Directory |\n|----------:|:-----------------|\n| `.js`     | `scripts/`       |\n| `.css`    | `styles/`        |\n| others    | `assets/`        |\n\nThen, Docolatte writes the proper `\u003cscript\u003e` and `\u003clink\u003e` tags linking to the imported scripts and styles in HTML like this:\n\n```html\n\u003chead\u003e\n  ...\n  \u003cscript src=\"scripts/alfa.js\"\u003e\u003c/script\u003e\n  \u003clink rel=\"stylesheet\" href=\"styles/bravo.css\"\u003e\n  ...\n\u003c/head\u003e\n```\n\n### More complex options\nInstead of just a file path, you can use an **object** to specify more complex rules for each file to import.\n\n```json\n\"import\": [\n  { \"src\": \"my-scripts/alfa.js\",  \"dst\": \"foo/bar\" },\n  { \"src\": \"my-scripts/bravo.js\", \"dst\": \"foo/bar\", \"as\": \"delta.js\" }\n]\n```\n\n- **`dst`** property specifies the destination directory of import.\n- **`as`** property specifies a new filename for the imported file.\n\n#### Loading remote CSS \u0026 JS\nWith the **`resolve`** property, you can specify how Docolatte looks up the `src`.\nIf you set `resolve` to `false`, Docolatte won't attempt to copy the file. Instead, only write `\u003cscript\u003e` (or `\u003clink\u003e` for `*.css`) tag pointing at the `src` in HTML.\n\n```json\n\"import\": [\n  { \"resolve\": false, \"src\": \"https://example.com/hello.js\" }\n]\n```\n\n#### Importing Node modules\nBy setting the `resolve` property to `'module'`, you can import files from Node modules in the dependencies of your current project.\n\n```json\n\"import\": [\n  { \"resolve\": \"module\", \"src\": \"p5/lib/p5.js\" }\n]\n```\n\n#### Private import\nIf you set the **`private`** property to `true`, Docolatte will copy the file to the JSDoc output directory normally, but won't write `\u003cscript\u003e` or `\u003clink\u003e` tags in HTML.\n\nThis is useful if you want to `@import` a CSS file from other CSS.\n\n```json\n\"import\": [\n  { \"src\": \"my_styles/style.css\" },\n  { \"src\": \"my_styles/variables.css\", \"private\": true }\n]\n```\n```css\n/* style.css */\n@import \"variables.css\";\n```\n\n#### Ordering imports\nThe order of `\u003cscript\u003e` and `\u003clink\u003e` tags for imports is determined by the **`order`** property of each import.\nThe default value of `order` is `0`. The greater the value, the lower the tag is placed.\nA negative value makes the tag placed earlier than the default scripts \u0026 styles of Docolatte.\n\n```json\n\"import\": [\n  { \"order\": 5, \"src\": \"second.css\" },\n  { \"order\": 5, \"src\": \"third.css\" },\n  { \"order\": 2, \"src\": \"first.css\" }\n]\n```\n```html\n\u003chead\u003e\n  ...\n  \u003clink rel=\"stylesheet\" href=\"styles/first.css\"\u003e\n  \u003clink rel=\"stylesheet\" href=\"styles/second.css\"\u003e\n  \u003clink rel=\"stylesheet\" href=\"styles/third.css\"\u003e\n  ...\n\u003c/head\u003e\n```\n\n\n## Customizing CSS Variables\nAll the CSS variables that Docolatte is using are defined in [src/styles/skin.css](https://github.com/amekusa/docolatte/blob/trunk/src/styles/skin.css).\nTo customize those variables, copy the file and `import` it. Then, edit the variable values as you like.\n\n\n## License\n```txt\nCopyright 2020 Satoshi Soma\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famekusa%2Fdocolatte","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famekusa%2Fdocolatte","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famekusa%2Fdocolatte/lists"}