Advanced

Under the hood, Hydejack is a surprisingly (maybe shockingly) complex beast. Some of the more advanced concepts are explained here.

Table of Contents

  1. Adding a custom social media icon
    1. Creating the icon font
    2. Adding the platform’s metadata
  2. Building the JavaScript
  3. How CSS is organized in Hydejack

Adding a custom social media icon

Hydejack includes a number of social media icons by default (in fact, everything that is provided by IcoMoon), but since the landscape is always changing, it is likely that a platform that is important to you will be missing at some point.

NOTE: You can add any platform by simply providing a complete URL. However, a fallback icon will be used.

Creating the icon font

In order to add a custom social media icon you have to use the IcoMoon App (free) to create a custom icon webfont. However, it is important that the generated font include all icons already in use by Hydejack. For this purpose, find the selection.json in assets/icomoon/selection.json and upload it to the app via “Import Icons”. Then, use the app to add your icon(s). Consult the IcoMoon docs for additional help.

Once you’ve created and downloaded the icon font form IconMoon, replace the icomoon folder in assets in its entirety. Keep in mind that future updates of Hydejack will override this folder.

Adding the platform’s metadata

For the second step it is necessary to add the network’s metadata to _data/social.yml. An entry looks like:

deviantart:
  name: DeviantArt
  icon: icon-deviantart
  prepend: "https://"
  append: ".deviantart.com"
name
The name of the network. Used for for the title attribute and screen readers.
icon
The icon CSS class. Can be chosen during the IcoMoon creation process.
prepend
Optional. A string that is prepended to the username to form the link to the profile. If the final URL should be https://<username>.deviantart.com, this would be https://
append
Optional. A string that is appended to the username to form the link to the profile. If the final URL should be https://<username>.deviantart.com, this would be .deviantart.com.

Building the JavaScript

In order to build the JavaScript you need to have node.js installed. Specifically, the npm command needs to be available, which is part of node.js.

NOTE: Building the JavaScript is optional! Hydejack comes with a pre-built, minified hydejack.js file that you can find in part of the theme’s assets.

Before you start, make sure you’ve copied the following files:

  • _js/
  • package.json
  • package-lock.json
  • .babelrc
  • .eslintignore
  • .eslintrc

When building for the first time (and after each update of Hydejack) you have to run

$ npm install

to fetch all dependencies (and put them in a local folder node_modules), lint the code and write the bundled and minified script into assets/js/hydejack.js.

You can re-build it with

$ npm run build:js

If you want to actively develop the scripts, it is better to run

$ npm run watch:js

which will build a non-minified version of assets/js/hydejack.js after each filechange.

How CSS is organized in Hydejack

Hydejack takes a quite unique approach to CSS, which is motivated by the ability to inline essential CSS rules in a style tag in the <head/> of a page (to increase the loading speed), while serving the rest in a separate file.

The styles are written in SCSS and are located in the _sass folder, which looks like

├── hydejack
│   ├── __inline
│   ├── __link
│   ├── _base.pre.scss
│   ├── ...
│   └── _social.pre.scss
├── pooleparty
│   ├── __inline
│   ├── __link
│   ├── _base.pre.scss
│   ├── ...
│   └── _type.pre.scss
├── mixins.scss
├── my-inline.scss
├── my-style.scss
├── syntax.scss
└── variables.scss

The style rules are organized alongside components (or rather, topics) like “sidebar” and “footer”. Further, there are two separate frameworks, “pooleparty” and “hydejack”, which grew out of the original Poole and Hyde projects. Poole/party contains more general style rules, while Hyde/jack contains those that more are specific to the theme. However, this separation has become more blurry over time.

Inside those folders, you will notice the __inline and __link folders. The unfriendly names are intentional, because their contents are generated by a script and shouldn’t be modified directly. The source files are located in the same folder and end with .pre.scss. They are fully valid SCSS files, but contain comments that mark which lines should be inlined and which should be fetched asynchronously.

The rules are as follows:

  • Every line between // <<< inline and // >>> will be inlined
  • Every line between // <<< link and // >>> will be linked
  • Every line that isn’t contained in a block and ends with // inline will be inlined
  • Every line that isn’t contained in a block and ends with // link will be linked
  • Every line for which none of the above applies will be included in both.

The actual splitting happen with the _scripts/build-css.sh script (requires node.js 8+). You can run the script once by using

$ npm run build:css

or rebuild the CSS on every file change

$ npm run watch:css

Note that my-inline.scss and my-style.scss are not affected by this. Also, since all files are valid SCSS, the splitting part is entirely optional. If you would like to build just one regular CSS file, add

hydejack:
  no_inline_css: true

to your config file.


Actions Speak Louder Than Words!

Powered by Jekyll and Hydejack v7.3.0