Xaes - Ghost Docs

Customization - Heimdall

Customization - Heimdall

Set Dual logos

Heimdall supports logos. The recommended size is: 560 x 110px. You may need two different color version of your logo. Because Heimdall has 2 main colors (dark / light), your logo might not be visible in one of them (Ex.: If your logo is white and you have set the light version of the theme, it would be impossible to see your logo, since the main navbar and your logo are the same color). The theme can handle two logos at a time and switch them accordly.

To use the logo switcher, follow these steps:

  • Copy your two PNG logo files on your heimdall/assets/images directory.

  • Make sure to rename the dark version of your logo to logo-dark.png and the light one to logo-light.png.

  • Open the logo.hbs file located at the heimdall/partials/ directory.

  • Delete the entire line 2 and 5 of the doc. Then, comment the line 6:

heimdall/partials/logo.hbs
<a href="{{@site.url}}" class="h-full mr-8">
<!--
<img alt="{{@site.title}}" src="{{asset "images/logo-black.png"}}" class="h-full logo-black mx-auto lg:mx-0" style="max-height: 100%; width: auto; max-width: 200px;" />
<img alt="{{@site.title}}" src="{{asset "images/logo-white.png"}}" class="h-full logo-white mx-auto lg:mx-0" style="max-height: 100%; width: auto; max-width: 200px;" />
-->
<img alt="{{@site.title}}" class="mx-auto lg:mx-0" src="{{@site.logo}}" style="max-height: 100%; width: auto; max-width: 200px;" />
</a>
  • Save the file. This is how your code should look like after the proper changes:
heimdall/partials/logo.hbs
<a href="{{@site.url}}" class="h-full mr-8">
<img alt="{{@site.title}}" src="{{asset "images/logo-black.png"}}" class="h-full logo-black mx-auto lg:mx-0" style="max-height: 100%; width: auto; max-width: 200px;" />
<img alt="{{@site.title}}" src="{{asset "images/logo-white.png"}}" class="h-full logo-white mx-auto lg:mx-0" style="max-height: 100%; width: auto; max-width: 200px;" />
<!-- <img alt="{{@site.title}}" class="mx-auto lg:mx-0" src="{{@site.logo}}" style="max-height: 100%; width: auto; max-width: 200px;" /> -->
</a>
  • In order to activate the logo support, go to your Ghost Admin Dashboard and upload any version of your logo (Heimdall only needs to detect whether if you want to use a logo or not. So, it doesn't matters which one you upload from the dashboard, the theme will still use those images you copied and renamed on step 1 and 2).

  • Rezip the theme, and upload it again to your blog.

Add Disqus

If you want to display comments on your posts. Heimdall has a Disqus partial ready to be activated.

  • Login into your Disqus account. Navigate to your Disqus's Admin Panel and create a site if you don't have any.

  • Select your existant Disqus site, and click on Installing Disqus.

  • In the administration panel of your Disqus's site, click on Edit Settings.

  • Look up for the Disqus shortname and copy it. Note: The shortname won't be the same as shown in the screenshot.

  • Open the post.hbs file located at your heimdall/ directory. Paste the your Disqus site name in line 63 between the double quotes of shortname.

heimdall/partials/content-cta.hbs
<div class="grid grid-cols-2 gap-4 xl:gap-12 mt-16">
{{#next_post}}
<div class="col-span-2 md:col-span-1 xl:col-span-1 md:order-3 xl:order-1">
<div class="h-72 sm:h-96 xl:h-80">
{{> "post-card" next="true"}}
</div>
</div>
{{/next_post}}
{{#prev_post}}
<div class="col-span-2 md:col-span-1 xl:col-span-1">
<div class="h-72 sm:h-96 xl:h-80">
{{> "post-card" prev="true"}}
</div>
</div>
{{/prev_post}}
</div>
{{! Comments (Disqus) - Go to partials/comments.hbs to view this partial. Remove the "!" to activate this partial}}
{{> "comments" shortname="" }}
  • Rezip the theme, and upload it again to your blog.

Translations

Heimdall already brings 2 languages by default: English and Spanish. If you want to switch between those two, follow these steps:

  1. Go to your Ghost Admin Panel.

  2. Navigate to "General" in "Settings" section at the sidebar. Expand the Publication Language tab and write en for English and es for Spanish.

If you want to add another language, follow these steps:

  1. Create a JSON file in your heimdall/locales/ directory with the name of the language you want to use following the HTML ISO Language Code. (e.g.: es for Spanish, fr for French, zh for Chinese, ja for Japanese).

  2. Open the en.json file, copy the code and then, paste it on the new file you just created at step 1.

  3. On each line, replace the value after the colon with your translation, between the double quotes. Save the file.

  4. Go to your Ghost Admin Panel.

  5. Navigate to General in Settings section at the sidebar. Expand the Publication Language tab and write the name of the file you just wrote (HTML ISO Lang. Code).

Change Default Colors

In Heimdall, there is a list of CSS variables that you can override from the Ghost Dashboard in order to put the color values that you wish to use. You'll need to access the Ghost Injection Feature. On the header section, you can paste this snippet of code of the default values that Heimdall uses and then override them:

<style>
:root {
--primary-color: #fc4501;
--black-1: #111317;
--white-1: #f4f5f6;
--post-dark-overlay-up: rgba(17,19,23,0.65);
--post-dark-overlay-down: #111317;
--post-light-overlay-up: rgba(244,245,246,0.65);
--post-light-overlay-down: #f4f5f6;
--author-dark-overlay-up: rgba(17,19,23,0.55);
--author-dark-overlay-down: rgba(17,19,23,0.85);
--author-light-overlay-up: rgba(244,245,246,0.55);
--author-light-overlay-down: rgba(244,245,246,0.85);
--subscribe-dark-overlay-up: rgba(17,19,23,0.45);
--subscribe-dark-overlay-down: rgba(17,19,23,0.45);
--subscribe-light-overlay-up: rgba(244,245,246,0.45);
--subscribe-light-overlay-down: rgba(244,245,246,0.45);
}
</style>

Those variables accept any CSS color unit, such as: rgb, rgba, hex, hsl and more.

NodeJS Tasks

Note: This section is intended for people that want to further extend the theme and might require a little bit of development experience.

Heimdall as pre-defined NodeJS tasks to help you with the development / extension process. To make use of them, please make sure to have Yarn (v. 1.22.10) and NodeJS (v. 14.17) installed. I recommend using NVM (Node Version Manager to install NodeJS in your system).

Task NameDescription
devWatches for any file change and them generates a new version of CSS and JS. The output directory is located at assets/built.
zipDoes the same as dev, but also autoprefixes, uglifies and purges the CSS files. At the end, it creates a ZIP file located at dist/ folder and ignores non-essential files (node_modules, etc.).
formatFormats the CSS / JS code in your theme using Prettier.

To run any of the tasks you can run the following command in a terminal inside the Heimdall theme files: yarn <task name>. Ex: yarn dev.

Further Customization

Note: This section is intended for deep customization of Heimdall's styling and might require a little bit of development experience.

Heimdall uses TailwindCSS which it is itself easy to customize and to extend. The configuration of the TailwindCSS theme is located at the gulpfile.js file on your heimdall theme directory. In there, you will see all the extra configuration that the theme uses. You can also change the current configuration by overriding the pre-defined styles of the theme. For more information, please refer to the TailwindCSS Documentation. This is the default configuration for Tailwind in Heimdall:

heimdall/gulpfile.js
{
plugins: [tailwindTypo, tailwindLineClamp],
darkMode: "class",
theme: {
extend: {
colors: {
primary: "var(--primary-color)",
},
textColor: {
primary: "var(--primary-color)",
},
backgroundColor: grayPallette,
borderColor: {
primary: "var(--primary-color)",
},
flex: {
full: "1 0 100%",
},
height: {
100: "28.5rem",
102: "30rem",
"60vh": "60vh",
},
minHeight: {
75: "75vh",
},
boxShadow: {
"3xl": "0 35px 60px -15px rgba(0, 0, 0, 0.3)",
},
typography: (theme) => ({
DEFAULT: {
css: {
a: {
color: "var(--primary-color)",
textDecoration: "none",
"&:hover": {
color: theme("colors.black"),
},
"& strong": {
color: "var(--primary-color)",
},
"&:hover strong": {
color: theme("colors.black"),
},
},
blockquote: {
fontFamily: "font-serif",
borderLeftColor: "var(--primary-color)",
paddingLeft: "2rem",
fontSize: "1.6rem",
lineHeight: "1.5",
},
img: {
borderRadius: "0.375rem",
},
figure: {
"& figcaption": {
color: theme("colors.gray.500"),
fontWeight: "300",
},
"& pre": {
marginBottom: "0",
},
},
strong: {
"& a": {
color: "var(--primary-color)",
},
"&:hover a": {
color: theme("colors.black"),
},
},
},
},
xl: {
css: {
blockquote: {
paddingLeft: "2rem",
fontSize: "1.6rem",
lineHeight: "1.5",
},
figure: {
"& figcaption": {
fontSize: "1.2rem",
},
},
},
},
dark: {
css: {
color: theme("colors.gray.300"),
'[class~="lead"]': { color: theme("colors.gray.400") },
a: {
color: "var(--primary-color)",
textDecoration: "none",
"&:hover": {
color: theme("colors.white"),
},
"& strong": {
color: "var(--primary-color)",
},
"&:hover strong": {
color: theme("colors.white"),
},
},
strong: {
color: theme("colors.gray.100"),
"& a": {
color: "var(--primary-color)",
},
"&:hover a": {
color: theme("colors.white"),
},
},
"ul > li::before": {
backgroundColor: theme("colors.gray.700"),
},
hr: { borderColor: theme("colors.gray.800") },
blockquote: {
color: theme("colors.gray.100"),
borderLeftColor: "var(--primary-color)",
},
p: {
color: theme("colors.gray.300"),
},
h1: { color: theme("colors.gray.100") },
h2: { color: theme("colors.gray.100") },
h3: { color: theme("colors.gray.100") },
h4: { color: theme("colors.gray.100") },
h5: { color: theme("colors.gray.100") },
h6: { color: theme("colors.gray.100") },
code: { color: theme("colors.gray.100") },
"a code": { color: theme("colors.gray.100") },
pre: {
color: theme("colors.gray.200"),
backgroundColor: theme("colors.gray.800"),
},
thead: {
color: theme("colors.gray.100"),
borderBottomColor: theme("colors.gray.700"),
},
"tbody tr": {
borderBottomColor: theme("colors.gray.800"),
},
},
},
}),
},
fontFamily: {
serif: ['"Libre BaskerVille"', "ui-serif", "Georgia"],
sans: ["Nunito", "Helvetica", "Arial", "sans-serif"],
},
container: {
center: true,
},
},
variants: {
extend: {
display: ["dark"],
maxHeight: ["group-hover"],
translate: ["group-hover"],
borderColor: ["active", "focus"],
typography: ["dark"],
borderColor: ["active", "focus"],
pointerEvents: ["group-hover"],
},
},
}

Note: Take for account that Tailwind is configured using Gulp and other bundling tools. It is recommended that if you want to make changes to the configuration of Tailwind you also use the pre-defined development tasks that Heimdall has with Gulp. For example, if you find yourself making a lot of changes, you should be running the dev gulp task. After you are done, you can generate a production-ready version of the code by running the zip task.