Skip to content

Commit d096e6e

Browse files
adamrehnadamrehn
committed
Initial public release
1 parent 05b1694 commit d096e6e

File tree

18 files changed

+896
-2
lines changed

18 files changed

+896
-2
lines changed

‎.github/workflows/workflow.yml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
name: build-gem
2+
on: [push]
3+
jobs:
4+
build:
5+
runs-on: ubuntu-latest
6+
7+
permissions:
8+
id-token: write
9+
contents: write
10+
11+
steps:
12+
13+
# Clone the source code on the runner
14+
- uses: actions/checkout@v3
15+
16+
# Perform setup for Ruby 2.7
17+
- uses: ruby/setup-ruby@v1
18+
with:
19+
ruby-version: '2.7'
20+
rubygems: latest
21+
bundler-cache: true
22+
23+
# Build the gem
24+
- run: gem build jekyll-theme-dashboard.gemspec
25+
26+
# Publish the gem to RubyGems when a new release is tagged
27+
- if: startsWith(github.ref, 'refs/tags')
28+
uses: rubygems/release-gem@v1
29+
with:
30+
attestations: false
31+
await-release: false

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
*.gem
2+
.bundle
3+
.jekyll-cache
4+
.sass-cache
5+
_site
6+
Gemfile.lock

‎Gemfile‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# frozen_string_literal: true
2+
3+
source "https://rubygems.org"
4+
gemspec
5+
6+
gem 'rake', '~> 13.2'

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 TensorWorks Pty Ltd
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 249 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,249 @@
1-
# jekyll-theme-dashboard
2-
Dashboard theme for Jekyll
1+
# Dashboard theme for Jekyll
2+
3+
This is a [Jekyll](https://jekyllrb.com/) theme designed primarily for creating dashboards that display large numbers of hyperlinks. It is used at TensorWorks for our internal dashboards.
4+
5+
This theme is designed to be highly configurable, whilst providing sensible defaults for most options in order to make it as easy as possible to get up and running quickly. The configuration mechanisms are largely derived from [jekyll-theme-gitbook](https://github.com/adamrehn/jekyll-theme-gitbook) and should feel familiar to users of that theme. See the [Configuration](#configuration) section for details of the available settings.
6+
7+
**You can view a [live demo of this theme here](https://tensorworks.github.io/jekyll-theme-dashboard-demo) and view the [source code for the demo site here](https://github.com/TensorWorks/jekyll-theme-dashboard-demo).**
8+
9+
10+
## Contents
11+
12+
- [Installation](#installation)
13+
- [Configuration](#configuration)
14+
- [Theme configuration](#theme-configuration)
15+
- [Dashboard contents](#dashboard-contents)
16+
- [Dashboard related links](#dashboard-related-links)
17+
- [Site structure](#site-structure)
18+
- [CSS styles](#css-styles)
19+
- [Hooks](#hooks)
20+
- [Legal](#legal)
21+
22+
23+
## Installation
24+
25+
Add the following line to your site's `Gemfile`:
26+
27+
```ruby
28+
gem "jekyll-theme-dashboard"
29+
```
30+
31+
Also add the following line to your site's `_config.yml` file:
32+
33+
```yaml
34+
theme: "jekyll-theme-dashboard"
35+
```
36+
37+
38+
## Configuration
39+
40+
### Theme configuration
41+
42+
All configuration data for this theme is stored under a top-level YAML key called `theme-settings`, which has the following structure:
43+
44+
```yaml
45+
theme-settings:
46+
47+
48+
# Logo settings (OPTIONAL, only needed if you want to override the defaults)
49+
logo:
50+
51+
# Override the path to the site's logo image (OPTIONAL, defaults to "/assets/images/logo.svg")
52+
default: "/assets/images/logo.svg"
53+
54+
# Specify an alternative version of the site's logo image to use in dark mode (OPTIONAL, defaults to the light mode logo)
55+
dark: "/assets/images/logo-dark.svg"
56+
57+
58+
# Favicon settings (OPTIONAL, only needed if you want to override the defaults)
59+
favicon:
60+
61+
# Override the PNG version of the favicon (OPTIONAL, defaults to "/assets/images/favicon.png")
62+
png: "/path/to/favicon.png"
63+
64+
# Override the SVG version of the favicon (OPTIONAL, defaults to "/assets/images/favicon.svg")
65+
svg: "/path/to/favicon.svg"
66+
67+
68+
# Font Awesome icon settings (OPTIONAL, only needed if you want to override the defaults)
69+
fontawesome:
70+
71+
# Specify that you are providing Font Awesome through your own CSS (OPTIONAL, defaults to false)
72+
local: true
73+
74+
# Specify a Font Awesome Kit URL to provide icons (OPTIONAL, defaults to none, takes precedence over "local" if both are specified)
75+
kit: "https://kit.fontawesome.com/xxxxxxxxxx.js"
76+
```
77+
78+
### Dashboard contents
79+
80+
The theme displays information as a series of grouped cards, which must be specified in `_data/cards.yml` with the following structure:
81+
82+
```yaml
83+
# The top-level element is a list of groups
84+
-
85+
86+
# (OPTIONAL: the title for the box that displays the group of cards, defaults to no title)
87+
group: "Group Title"
88+
89+
# (OPTIONAL: an icon to display next to the group title, defaults to no icon)
90+
icon: group.svg
91+
92+
# (OPTIONAL: a dark mode icon to display next to the group title, defaults to the light mode icon)
93+
icon-dark: group-dark.svg
94+
95+
# (OPTIONAL: the background colour of the box that displays the group of cards, defaults to transparent)
96+
background: "#ddd"
97+
98+
# (OPTIONAL: the dark mode background colour of the box that displays the group of cards, defaults to transparent)
99+
background-dark: "#777"
100+
101+
# (OPTIONAL: the text colour of the group title, defaults to "#000")
102+
text: "#000"
103+
104+
# (OPTIONAL: the dark mode text colour of the group title, defaults to "#fff")
105+
text-dark: "#fff"
106+
107+
# The list of cards in the group
108+
cards:
109+
110+
-
111+
112+
# The card title
113+
name: My Card
114+
115+
# The card type (one of "link-list", "icon-grid" or "custom")
116+
type: link-list
117+
118+
119+
# (ONLY USED WHEN TYPE IS "link-list": the list of links to display on the card)
120+
links:
121+
122+
-
123+
124+
# The text to display for the link
125+
name: "Very Helpful Link"
126+
127+
# The URL for the link
128+
url: "https://some.helpful/website"
129+
130+
# The description for the link
131+
description: "This is a very helpful link."
132+
133+
# (OPTIONAL: an icon to display for the link, defaults to no icon)
134+
icon: helpful.svg
135+
136+
# (OPTIONAL: a dark mode icon to display for the link, defaults to the light mode icon)
137+
icon-dark: helpful-dark.svg
138+
139+
# (OPTIONAL: whether to display the link description by default, defaults to false)
140+
expanded: false
141+
142+
143+
# (ONLY USED WHEN TYPE IS "icon-grid": the list of icons to display on the card)
144+
icons:
145+
146+
-
147+
# The name of the link, which is used as the alternate text for the image
148+
name: "Another Helpful Link"
149+
150+
# The icon to display for the link
151+
icon: another-helpful.svg
152+
153+
# (OPTIONAL: a dark mode icon to display for the link, defaults to the light mode icon)
154+
icon-dark: another-helpful-dark.svg
155+
156+
# The URL for the link
157+
url: "https://another.helpful/website"
158+
159+
160+
# (ONLY USED WHEN TYPE IS "custom": the HTML file from the `_include` directory that provides the card body contents)
161+
include: custom-card-body.html
162+
163+
# (OPTIONAL, AND ONLY USED WHEN TYPE IS "custom": a custom CSS class to add to the card body, defaults to no class)
164+
body-class: my-custom-class
165+
```
166+
167+
### Dashboard related links
168+
169+
The theme optionally supports displaying a set of related links at the top of the page, which is useful when you have multiple related dashboard sites and want to quickly jump between them. These related links are specified in the optional file `_data/related.yml` with the following structure:
170+
171+
```yaml
172+
# (OPTIONAL: the title for the box that displays the related links, defaults to "Related Dashboards")
173+
title: "Related Dashboards"
174+
175+
# (OPTIONAL: the background colour of the box that displays the related links, defaults to transparent)
176+
background: "#f0f0f0"
177+
178+
# (OPTIONAL: the dark mode background colour of the box that displays the related links, defaults to transparent)
179+
background-dark: "#323232"
180+
181+
# (OPTIONAL: the text colour of the related links, defaults to "#000")
182+
text: "#000"
183+
184+
# (OPTIONAL: the dark mode text colour of the related links, defaults to "#fff")
185+
text-dark: "#fff"
186+
187+
# The list of related links
188+
links:
189+
190+
-
191+
# The text to display for the link
192+
name: "Some Other Dashboard"
193+
194+
# The URL for the link
195+
url: "https://some.other/dashboard"
196+
197+
# (OPTIONAL: an icon to display for the link, defaults to no icon)
198+
icon: other-dashboard.svg
199+
200+
# (OPTIONAL: a dark mode icon to display for the link, defaults to the light mode icon)
201+
icon-dark: other-dashboard-dark.svg
202+
```
203+
204+
### Site structure
205+
206+
The intended use case for the theme is a single index page that uses the default layout. The simplest way to implement this is to create a file called `index.html` in the root of your site's filesystem directory with the following contents:
207+
208+
```
209+
---
210+
layout: default
211+
---
212+
```
213+
214+
The theme assumes that all images are stored in `/assets/images/`, and in particular assumes that all icons referenced in `cards.yml` and `related.yml` are stored in `/assets/images/icons/`.
215+
216+
### CSS styles
217+
218+
If you use the theme's default settings then your site is expected to have an `assets/css/style.scss` file with the following contents as a minimum:
219+
220+
```scss
221+
---
222+
---
223+
@import '{{ site.theme }}';
224+
```
225+
226+
You can change the list of CSS files that get included in the site's `<head>` tag by providing your own `_includes/hooks/head-posthook.html` file, as described in the [Hooks](#hooks) section below. Irrespective of whether you use the default CSS filesystem path or a custom list of paths, at least one CSS file will need to include the theme's CSS styles using the code above. You can then add your own CSS rules to augment or override the default theme styles.
227+
228+
### Hooks
229+
230+
In addition to the configuration options discussed in the sections above, you can control the HTML output of your site by using a set of supported include files that the theme refers to as "hooks". The default contents of these hooks are located in the theme's [`_includes/hooks`](https://github.com/TensorWorks/jekyll-theme-dashboard/tree/main/_includes/hooks) subdirectory, and are used throughout the theme's default layout. To replace the contents of a given hook, simply create a file in your site's filesystem directory with the same filename (e.g. `_includes/hooks/head-posthook.html`) and Jekyll will automatically use your version of the file instead of the default version from the theme.
231+
232+
The following hooks are currently supported:
233+
234+
- `head-posthook.html`: included at the end of the site's `<head>` tag. This hook is typically used for providing additional `<meta>` tags, CSS files or Javascript files. The default version of this hook simply includes the CSS file `/assets/css/style.css`.
235+
236+
- `body-prehook.html`: included at the start of the site's `<body>` tag. The default version of this hook is empty.
237+
238+
- `body-posthook.html`: included at the end of the site's `<body>` tag. This hook is typically used for providing additional Javascript files or code. The default version of this hook is empty.
239+
240+
241+
## Legal
242+
243+
Copyright &copy; 2025, TensorWorks Pty Ltd. Licensed under the MIT License, see the file [LICENSE](./LICENSE) for details.
244+
245+
The following third-party libraries are bundled in the theme's source tree and are covered by their respective licenses:
246+
247+
- [Bootstrap](https://getbootstrap.com/) ([MIT License](https://github.com/twbs/bootstrap/blob/main/LICENSE))
248+
- [jQuery](https://jquery.com/) ([MIT License](https://github.com/jquery/jquery/blob/master/LICENSE.txt))
249+
- [Popper](https://popper.js.org/) ([MIT License](https://github.com/floating-ui/floating-ui/blob/v2.x/LICENSE.md))

‎Rakefile‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# frozen_string_literal: true
2+
3+
require "bundler/gem_tasks"

‎_includes/hooks/body-posthook.html‎

Whitespace-only changes.

‎_includes/hooks/body-prehook.html‎

Whitespace-only changes.

‎_includes/hooks/head-posthook.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
<link href="{{ "/" | relative_url }}assets/css/style.css" rel="stylesheet" type="text/css">

0 commit comments

Comments
 (0)