From f18be6e70871336d884345d8eb9b7c56f0400bb4 Mon Sep 17 00:00:00 2001 From: Alicia Sykes Date: Sun, 8 Aug 2021 22:53:36 +0100 Subject: [PATCH] :memo: Updates docs with instructions for Material-Design-Icons --- README.md | 12 ++++++------ docs/configuring.md | 2 +- docs/icons.md | 24 +++++++++++++++++++++++- 3 files changed, 30 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index be551c04..ee7eb85f 100644 --- a/README.md +++ b/README.md @@ -102,7 +102,7 @@ Are using Dashy? Want to share your dashboard here too - [Submit your Screenshot > For full setup instructions, see: [**Deployment**](./docs/deployment.md) -#### Deploying from Docker Hub 🐳 +### Deploying from Docker Hub 🐳 You will need [Docker](https://docs.docker.com/get-docker/) installed on your system @@ -122,13 +122,12 @@ docker run -d \ ``` If you prefer to use Docker Compose, [here is an example](./docs/deployment.md#using-docker-compose). -You can also build the Docker container from source, by cloning the repo, cd'ing into it and running `docker build .` and `docker compose up`. > Once you've got Dashy running, you can take a look at [App Management Docs](./docs/management.md), for info on using health checks, provisioning assets, configuring web servers, securing your app, logs, performance and more. -#### Deploying from Source 🚀 +### Deploying from Source 🚀 -You will need both [git](https://git-scm.com/downloads) and the latest or LTS version of [Node.js](https://nodejs.org/) installed on your system +You will need [git](https://git-scm.com/downloads), the latest or LTS version of [Node.js](https://nodejs.org/) and (optionally) [Yarn](https://yarnpkg.com/) installed on your system. - Get Code: `git clone git@github.com:Lissy93/dashy.git` and `cd dashy` - Configuration: Fill in you're settings in `./public/conf.yml` @@ -138,7 +137,7 @@ You will need both [git](https://git-scm.com/downloads) and the latest or LTS ve > See docs [Full list of Dashy's commands](./docs/management.md#basic-commands) -#### Deploy to the Cloud ☁️ +### Deploy to the Cloud ☁️ Dashy supports 1-Click deployments on several popular cloud platforms. To spin up a new instance, just click a link below: - [ Deploy to Netlify](https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy) @@ -207,7 +206,8 @@ Both sections and items can have an icon associated with them, and defined under - **Generative**: Setting `icon: generative`, will generate a unique for a given service, based on it's URL or IP - **Emoji**: Use an emoji as a tile icon, by putting the emoji's code as the icon attribute. Emojis can be specified either as emojis (`🚀`), unicode (`'U+1F680'`) or shortcode (`':rocket:'`). - **URL**: You can also pass in a URL to an icon asset, hosted either locally or using any CDN service. E.g. `icon: https://i.ibb.co/710B3Yc/space-invader-x256.png`. -- **Local Image**: To use a local image, store it in `./public/item-icons/` (or create a volume in Docker: `-v /local/image/directory:/app/public/item-icons/`) , and reference it by name and extension - e.g. set `icon: image.png` to use `./public/item-icon/image.png`. You can also use sub-folders here if you have a lot of icons, to keep them organized. +- **Local Image**: To use a local image, store it in `./public/item-icons/` (or create a volume in Docker: `-v /local/image/directory:/app/public/item-icons/`) , and reference it by name and extension - e.g. set `icon: image.png` to use `./public/item-icon/image.png`. You can also use sub-folders here. +- **Material Design Icons**: You can also use any icon from [materialdesignicons.com](https://dev.materialdesignicons.com/icons) by setting the icon to `mdi-[icon-name]`. **[⬆️ Back to Top](#dashy)** diff --git a/docs/configuring.md b/docs/configuring.md index 291a5593..900184a5 100644 --- a/docs/configuring.md +++ b/docs/configuring.md @@ -153,7 +153,7 @@ To disallow any changes from being written to disk via the UI config editor, set **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- -**`icon`** | `string` | _Optional_ | The icon for a given item or section. Can be a font-awesome icon, favicon, remote URL or local URL. If set to `favicon`, the icon will be automatically fetched from the items website URL. To use font-awesome, specify the category, followed by the icon name, e.g. `fas fa-rocket`, `fab fa-monero` or `fal fa-duck` - note that to use pro icons, you mut specify `appConfig.fontAwesomeKey`. If set to `generative`, then a unique icon is generated from the apps URL or IP. You can also use hosted any by specifying it's URL, e.g. `https://i.ibb.co/710B3Yc/space-invader-x256.png`. To use a local image, first store it in `./public/item-icons/` (or `-v /app/public/item-icons/` in Docker) , and reference it by name and extension - e.g. set `image.png` to use `./public/item-icon/image.png`, you can also use sub-folders if you have a lot of icons, to keep them organised. +**`icon`** | `string` | _Optional_ | The icon for a given item or section. Can be a font-awesome icon, favicon, remote URL or local URL. If set to `favicon`, the icon will be automatically fetched from the items website URL. To use font-awesome, specify the category, followed by the icon name, e.g. `fas fa-rocket`, `fab fa-monero` or `fal fa-duck` - note that to use pro icons, you mut specify `appConfig.fontAwesomeKey`. Similarly, you can also use [simple-icons](https://simpleicons.org/) by setting icon to `si-[icon-name]` or [material-design-icons](https://dev.materialdesignicons.com/icons) by setting icon to `mdi-[icon-name]`. If set to `generative`, then a unique icon is generated from the apps URL or IP. You can also use hosted any by specifying it's URL, e.g. `https://i.ibb.co/710B3Yc/space-invader-x256.png`. To use a local image, first store it in `./public/item-icons/` (or `-v /app/public/item-icons/` in Docker) , and reference it by name and extension - e.g. set `image.png` to use `./public/item-icon/image.png`, you can also use sub-folders if you have a lot of icons, to keep them organised. **[⬆️ Back to Top](#configuring)** diff --git a/docs/icons.md b/docs/icons.md index 8cac264f..668233ed 100644 --- a/docs/icons.md +++ b/docs/icons.md @@ -14,6 +14,8 @@ Both sections and items can have an icon, which is specified using the `icon` at

+Note that, if you are using icons from an external source (like font-awesome or material-design-icons), then the relevant font file will be loaded in automatically if and when needed, but combining icons from multiple services may have a negative impact on performance. + ### Font Awesome You can use any [Font Awesome Icon](https://fontawesome.com/icons) simply by specifying it's identifier. This is in the format of `[category] [name]` and can be found on the page for any given icon on the Font Awesome site. For example: `fas fa-rocket`, `fab fa-monero` or `fas fa-unicorn`. @@ -54,7 +56,7 @@ You can use almost any emoji as an icon for items or sections. You can specify t

-The following example shows the unicode options available, all three will render the 🚀 emoji. +The following examples will all render the same rocket (🚀) emoji: ```yaml items: @@ -74,5 +76,25 @@ You may also want to store your icons locally, bundled within Dashy so that ther You can also use sub-folders within the `item-icons` directory to keep things organised. You would then specify an icon with it's folder name slash image name. For example: `networking/monit.png` +### Material Design Icons +Dashy also supports 5000+ [material-design-icons](https://github.com/Templarian/MaterialDesign). To use these, first find the name/ slug for your icon [here](https://dev.materialdesignicons.com/icons), and then prefix is with `mdi-`. + +For example: +```yaml +sections: +- name: Material Design Icons Example + items: + - title: Alien Icon + icon: mdi-alien + - title: Fire Icon + icon: mdi-fire + - title: Dino Icon + icon: mdi-google-downasaur + +``` + +### Simple Icons +To use glyphs from [SimpleIcons.org](https://simpleicons.org/), first find the icon slug, and then prefix it with `si-`. The image will be loaded directly from the Simple Icons + ### No Icon If you don't wish for a given item or section to have an icon, just leave out the `icon` attribute.