# docsify-dashboard [![NPM Release](https://img.shields.io/npm/v/docsify-dashboard.svg?logo=npm&style=flat-square)](https://www.npmjs.com/package/docsify-dashboard) [![License: MIT](https://img.shields.io/badge/License-GPLv3-yellow.svg?style=flat-square)](https://github.com/erectbranch/docsify-dashboard/blob/master/LICENSE) A plugin for [Docsify](https://docsify.js.org/#/) that creates a dashboard from a metadata.
## Import To use the dashboard, you need to include the plugin in your Docsify `index.html` file: > **Note:** This plugin requires [docsify-tabs](https://jhildenbiddle.github.io/docsify-tabs/#/) plugin. (Make sure to include it after the docsify-dashboard plugin) **Add stylesheet** ```html ``` **Add script** ```html ``` ## Structure The following directory structure is used: - `tags.md`: Empty file for rendering a dashboard by tags in the URL. (e.g., `#/tags?tag=plugin`) - `posts.json`: Metadata file containing the posts information. ```bash . └── docs ├── index.html └── tags.md └── metadata └── posts.json ``` Metadata file example(`metadata/posts.json`) > **Notes**: "*subtitle*", "*category*" information is optional ```json [ { "time": "2025.04.06", "title": "Shanwei, China", "tag": "5 min read", "image": "assets/images/shanwei.jpg", "href": "#/topic-one" }, { "time": "2025.04.05", "title": "Melbourne, Australia", "tag": "3 min read", "image": "assets/images/melbourne.png", "href": "#/topic-two", "subtitle": "A beautiful city in Australia", "category": "travel" } ] ``` ## Usage ### Dashboard You can create a dashboard by adding the following code to your markdown file: ```markdown ``` To display posts from a specific category only, you can use the following code: ```markdown ``` ### Tag-dashboard You can display a tag list by adding the following code to your markdown file: - **In sidebar file**: display all tags in the metadata. - **In markdown file**: only display the current page's tags. ```markdown ``` It will redirect to the tag-dashboard containing all posts that have the same tag. ## Example ### Footer with Page Tags Add a page footer to display the tags on each page. ```javascript window.$docsify = { plugins: [ function pageFooter(hook, vm) { var footer = [ '', '
', ].join(''); hook.afterEach(function (html) { return html + footer; }); }, ], }; ``` --- ## Configuration To configure the dashboard, you can set options in your `index.html` file. The available options are: - **Theme**: `default`, `cards`, `list` | Option | Type | Default | Description | | --- | --- | --- | --- | | `numTabContent` | `Int` | 3 | Number of cards to show in a docsify-tabs slide. | | `metadataUrl` | `String` | 'metadata/posts' | JSON URL to fetch metadata. | | `sort` | `Boolean` | false | Sort the posts by time. (`YYYY.MM.DD`, `YYYY/MM/DD`) | | `theme` | `String` | 'default' | Theme for the dashboard. | | `tagboardTheme` | `String` | 'default' | Theme for the tag-dashboard. | | `categoryTheme` | `Object` | {} | Theme for the specific categories. (`'categoryName': 'default'`) | | `pagination` | `Boolean` | false | Enable pagination for the dashboard tabs. | ```javascript window.$docsify = { dashboard: { numTabContent: 3, metadataUrl: 'metadata/posts', // do not include '.json' extension sort: false, // sort the posts by time theme: 'default', // (1) default, (2) cards, (3) list tagboardTheme: 'default', // options are same as above categoryTheme: {}, pagination: false // enable pagination for the dashboard } }; ``` --- ## Customization The dashboard can be customized using CSS. You can override the following CSS variables. ### Dashboard To change the styles, you can add the following CSS to your `index.html` file: ```html ``` ### Tag-dashboard To change the tag-list styles, add the following CSS: ```html ``` --- ## License This project is licensed under the GNU General Public License v3.0. - Original work © 2023–2025 李亦楊 ([@pikapikapikaori](https://github.com/pikapikapikaori)) - Modified work © 2025 Sungjae Jeon ([@erectbranch](https://github.com/erectbranch)) See [LICENSE](LICENSE) for more details. --- ## Contribution Please feel free to submit a pull request or open an issue on the GitHub repository. Your contributions are welcome and appreciated! ---