Lumen Documentation

Compatible Ghost version: v5.54.1 or any newer version.

Install the theme

Follow the steps below to upload the theme:

1. Log in to your publication admin section at yoursite.com/ghost/
2. Go to Settings > Design ( yoursite.com/ghost/#/settings/design/ )
3. Click Change theme and then click Upload theme and select the lumen.zip file.
4. After the upload is complete, under Installed themes click Activate

Routes Setup

Follow the steps below to upload the routes.yaml file (The file is located inside the zip)

1. Log in to your publication admin section at yoursite.com/ghost/
2. Go to Settings > Labs.
3. Under Beta features click on Upload routes file button and select the file from the root directory of the theme.

The routing file defines the following custom collections:

• /jobs/ - by default, every post belongs to this collection
• /blog/ - posts tagged blog will belong to this collection

Custom Settings

The theme comes with custom design settings, which are accessible from the Ghost Admin panel. To view and edit these settings go to Settings > Design & Branding ( yoursite.com/ghost/#/settings/design/)

Custom settings are defined in the package.json file. These settings are placed under three categories:

1. Site-wide settings
2. Homepage settings

Site-wide settings

• Color scheme - set the default color scheme (system, light, dark)
• Font headings - select from a predefined list of font families for the headings or use system fonts
• Font body - select from a predefined list of font families for the body text or use system fonts
• Dark theme logo - upload the site logo for the dark version of the theme
• CTA text - set the text for the CTA button in the header & hero
• CTA link - set the link for the CTA button in the header & hero
• Header search - enable or disable the search icon in the header
• Header action - set the main action button(s) for the header (cta,signin-signup,subscribe)
• Newsletter headline - set the headline for the newsletter signup section, right above the footer

Homepage settings

• Hero headline - set the hero headline
• Hero subheading - set the hero subheading
• Hero cover image style - set the hero image style (right, background, background-full, bottom, hidden)
• Hero action - set the hero action button (cta,search,subscribe-form,tags)
• Featured job categories - set the list of tag slugs to be featured as job categories
• Featured job posts - set the number of featured job posts to be displayed on the homepage(3,6,9,12,none)
• Featured companies - set a list of tag slugs to be featured as companies
• Job feed layout - set the job feed layout for the /jobs/ page (list,grid)
• Job filter slugs source - set the source of your filters (pages or tags)
• Job filter slugs - set the tag or page slugs to be used for the job filter section on the /jobs/ page
• Job card tags limit - set the maximum number of tags to be rendered on job cards

Homepage

The homepage is defined in the index.hbs file and it can include several sections based on your theme settings:

• hero
• partners
• browse by category
• featured job posts
• browse by company
• faq section
• from the blog
• newsletter

Hero

The hero section is completely customizable from Settings > Design > Homepage, with the following options:

• Hero headline - the hero section title

  • Example from the demo (the <span> element can be used to highlight the text with the brand color):

  Explore and find <span>your</span> ideal job
  

• Hero subheading - the hero section description

  • here you can also use HTML elements like links, bold text, etc:

• Hero cover image style - the hero section image style, the image can be positioned in the following ways:

  • right - the default option
  • background - homepage 2 variant
  • background-full - homepage 3 variant
  • bottom - homepage 4 variant
  • hidden - homepage 5 variant

• Hero action - you can choose from the following actions for your hero section:

  • cta - this option is based on the Site-wide CTA text and link settings
  • search - this will display a button pointing to the native Ghost search function
  • subscribe-form - this option will render a subscribe form for capturing emails
  • tags - this will render a list of tags, based on the featured_job_categories custom setting

Partners

The partners section renders images/logos of companies you would like to feature under the hero section. To enable this section, follow the steps below:

1. Create a new page with page URL: partners.
2. In this page add images in the post content using the Image card
3. The page title is used as the headline for the partners section.
4. If you change the title, make sure that the page URL remains partners

Browse by category

To enable the browse by category section, you have to set the Featured categories from Settings > Design & Branding > Homepage.

Example from the demo:

ai,crypto,data,design,development,education,finance,marketing,product,sales,security,support

The ideal number of categories for desktop is a multiply of 5.

Featured job posts

To feature a job post, in Post settings toggle on the Feature this post field. To change how many featured posts are rendered, set the Featured job posts setting from Settings > Design & Branding > Homepage.

The possible values are:

• 3
• 6
• 9
• 12
• none - with this option the section won't be rendered at all

Browse by company

To enable the browse by company section, you have to set the Featured companies from Settings > Design & Branding > Homepage.

Example from the demo:

ghost-cms,openai,stripe,airbnb

The ideal number of categories for desktop is a multiply of 4.

FAQ section

To activate the FAQ section on the homepage the only requirement is to create a new page with the page URL faq.

This section will display the title and excerpt on the left side and the content of the page on the right side.

To create the faqs you can use the built-in toggle card in the Ghost editor.

Blog section

This section renders up to 3 of the most recent posts tagged blog. There is also a link to the /blog/ page, which will render all the blog posts.

Jobs page

To active this page do the following:

1. Upload the routes.yaml file (if you didn't already do that)
2. Create a new page in your admin with page URL jobs.

Job filter

There are two custom settings for configuring the filters:

1. Job filter slugs source - choose from pages or tags
2. Job filter slugs - provide the slugs based on the previous setting

Option A:

This is the simpler options, which would result in one group of filters.

If you chose tags as a source, then you have to provide the tag slugs, separated by commas and no spaces. The tags have to exist and be assigned to at least one post to show up.

Option B:

If you chose pages as a source, then you have to provide the page slugs, this allows to create more than one filter section and a more advanced filtering function based on more than one criteria.

The jobs page on the demo has pages set as the source, and the following slugs set

job-category,experience-level,job-location

Those slugs are pages, here's how such a page looks like:

With this option the pages are used to define the filter groups and the tags assigned to each page will be rendered as filter options within the group.

Job feed

The job feed displays the articles ordered by the published date, starting with the most recent posts.

The layout of the feed can be set from Settings > Design > Homepage > Job feed layout, the options being:

• list
• grid

Additionally, visitors can set their own layout with the list/grid buttons above the job feed.

Job card

The job card markup is defined in partials/job-card.hbs file. In the Settings > Design > Homepage > Job card tags limit you can set a limit for the tags displayed on the cards, the options being:

• 0
• 1
• 2
• 3
• 4
• 5
• all

The job post image has 1/1 format both in the job card and on the job post template.

Blog page

To active this page do the following:

1. Upload the routes.yaml file (if you didn't already do that)
2. Create a new page in your admin with page URL blog.

Categories template

The categories template can be used to create pages such as:

• Job categories
• Companies

To create such pages:

1. In your Admin, create a new Page
2. Open Page settings > Template and select Categories Page
3. Then in Page Settings > Tags set the tags to rendered as cards
4. Save and Publish the page

Post templates

The default post template is tailored for job posts (post.hbs) If you want to add a closing date for the job post you can add an internal tag to the job post in the following format #closes-{closing_date}. For example: #closes-2024-04-10.

The theme also includes a custom template, which is ideal for blog posts, and another one for job posts with a table of contents, these can be selected from the Post Settings menu:

• custom-blog-post.hbs - a template for blog posts
• custom-job-post-with-toc.hbs - a template for job posts with table of contents

Navigation dropdown

Lumen comes with a custom feature to create dropdown menus easily for your header navigation. All you have to do is add the minus sign (-) in front of the items in Settings > Navigation

Items having the - sign will be added as subitems to the previous navigation item. For example from the demo:

• - Job post and - Blog post will belong to the Post templates item

Newsletter section

To display the Newsletter section above the footer there are two conditions to be fulfilled:

1. Add the newsletter headline in your Design settings (newsletter_headline)
2. Enable the Ghost membership feature

Color customization

You can change the main accent color from Settings > Design > Brand. The most important CSS configurations of the theme are defined as custom CSS properties, so you can easily overwrite them from code injection to change background colors, text colors, and more.

The theme comes with several color schemes, the default one can be set in the admin using the Default color scheme in Settings > Design > Site-Wide.

The included color schemes:

• system
• light
• dark

The default option is system which will be either the dark or light theme, depending on the user's preference.

It's possible to change the color schemes by changing the properties. This can be done by adding the following in code injection and adjusting the values.

To change the light theme:

<style>
  :root {
    --color-typography: hsl(0 0% 15%);
    --color-typography-tone: hsl(0 0% 40%);
    --color-typography-content: hsl(0 0% 30%);
    --color-typography-reverse: hsl(0 0% 85%);
    --color-background: hsl(0 0% 100%);
    --color-background-tone: hsl(0 0% 98%);
    --color-background-reverse: hsl(0 0% 12%);
    --color-border: hsl(0 0% 90%);
    --color-border-reverse: hsl(0 0% 20%);
  }
</style>

To change the dark theme:

<style>
  html[data-color-scheme="dark"] {
    --color-typography: hsl(0 0% 85%);
    --color-typography-tone: hsl(0 0% 65%);
    --color-typography-content: hsl(0 0% 65%);
    --color-typography-reverse: hsl(0 0% 15%);
    --color-background: hsl(0 0% 12%);
    --color-background-tone: hsl(0 0% 15%);
    --color-background-reverse: hsl(0 0% 98%);
    --color-border: hsl(0 0% 20%);
    --color-border-reverse: hsl(0 0% 92%);
  }
</style>

Some useful tools for choosing colors and gradients:

• Fuel HSL color picker
• Gradients | Components AI
• CSS Gradient Generator

Ghost config

Some configurations in Ghost themes can be defined in the package.json file, including Posts per page, Image sizes, and Custom settings.

Posts per page

The posts_per_page defines the number of posts that appear in your collections until it's paginated. For example, the value of posts_per_page is used on the home page, tag, and author templates.

By default, this is set to 8, and you can change it in the package.json file:

"config": {
  "posts_per_page": 24
}

Image sizes

Ghost can handle responsive image sizes, and this is defined in the package.json file, under the image_sizes property. You can change the default configuration by editing this file before uploading the theme.

"image_sizes": {
  "xxs": {
    "width": 30
  },
  "xs": {
    "width": 100
  },
  "s": {
    "width": 320
  },
  "m": {
    "width": 640
  },
  "l": {
    "width": 960
  },
  "xl": {
    "width": 1280
  },
  "xxl": {
    "width": 2000
  }
}

The image sizes defined there will be used to generate copies of images at the specified sizes when uploading images in Ghost Admin.

Comments

Lumen comes with the native Ghost comment feature. The Native Comment System requires at least Ghost v5.9.0, you have to enable it from Settings > Membership > Access > Commenting.

Google Fonts

You can set the font family from the Admin section, going to Settings > Design > Site-wide. There are two options, one for the headings and another for the rest of the elements:

Heading font options:

• System - loads the system font (no requests to Google Fonts)
• DM Sans
• Lexend
• Hanken Grotesk
• Plus Jakarta Sans
• Domine
• Recursive
• Cairo
• Mulish
• Inter
• Space Mono
• Kalnia
• Source Serif 4

Body font options:

• System
• DM Sans
• Lexend
• Hanken Grotesk
• Plus Jakarta Sans
• Domine
• Recursive
• Cairo
• Mulish
• Inter
• Space Mono

If you still want to use Google fonts and want to self-host the font files check out this guide for self-hosting Google Fonts.

Icons

The icons used in the theme are from Tabler Icons, the library consists of 4000+ icons. Not all icons from the library are included to save on the file size, but the most common icons are included in the partials/icons directory.

Inside the partials/icons directory, you can find all included icons, in separate .hbs files.

Here are the steps to add new icons:

1. Go to Tabler Icons and click on the Icon you want to add, this will copy the code to your clipboard.
2. Go into the partials/icons directory and create a new file: your-icon.hbs
3. Open the new file and paste the copied code from the clipboard.
4. Save the file.

For using the icons inside the theme files, there is a special partial file partials/icon.hbs which accepts name and size as parameters.

Let's see an example and try to add a new icon. Assuming we want to add the icon camera and by clicking on the icon on the website, we get this code:

<svg xmlns="http://www.w3.org/2000/svg" class="icon icon-tabler icon-tabler-camera" width="24" height="24" viewBox="0 0 24 24" stroke-width="1.5" stroke="#2c3e50" fill="none" stroke-linecap="round" stroke-linejoin="round">
  <path stroke="none" d="M0 0h24v24H0z" fill="none"/>
  <path d="M5 7h1a2 2 0 0 0 2 -2a1 1 0 0 1 1 -1h6a1 1 0 0 1 1 1a2 2 0 0 0 2 2h1a2 2 0 0 1 2 2v9a2 2 0 0 1 -2 2h-14a2 2 0 0 1 -2 -2v-9a2 2 0 0 1 2 -2" />
  <circle cx="12" cy="13" r="3" />
</svg>

The next step is to create a new file: partials/icons/camera.hbs and paste the copied code in the file. The new file must be of .hbs type, so we can use it into the theme files:

{{>icon name="camera"}}

Social links

Social links are shown in the header and footer and by default. The basic social links that Ghost comes with can be edited from Settings > General settings > Social accounts:

• Facebook
• X(Twitter)

For adding other social links you have to edit the partials/social-links.hbs file. There are several other links in there already, you just have to uncomment (remove the {{!-- --}} characters around the <a> tag) the relevant parts and add your link in the href attribute.

Social sharing

Social sharing is part of the post layout and the following is included:

• X(Twitter)
• Facebook
• Linkedin
• Email
• Copy to clipboard

To add other social sharing options you need to edit the partials/social-share.hbs file.

Translations

By default, everything is in English (en.json), additionally, the theme comes with translations in:

• 🇩🇪 German (de.json)
• 🇪🇸 Spanish (es.json)
• 🇫🇷 French (fr.json)
• 🇮🇹 Italian (it.json)
• 🇳🇱 Dutch (nl.json)
• 🇵🇹 Portuguese (pt.json)

If you want to edit the translation in a specific language, you have to edit the corresponding translation file. The files are stored in the locales directory (inside the theme zip).

|__ locales
|   |__ de.json
|   |__ en.json
|   |__ es.json
|   |__ fr.json

If the language file for your language doesn't exist, you have to create it (make sure to use the correct language code) The best way is to copy the content en.json file in your new language file, then change the translations.

Change use case

In case you want to use the theme for a different use case than jobs, you can do that. You don't have to edit all the different theme files to achieve this, you should edit translation file and the routes.yaml instead.

In the routes file, you can change the /jobs/ route to anything else, just make sure to reference an existing template (jobs.hbs) and page. To keep it simple, can keep the template file name as is: jobs.hbs. This is how your rout

  /prompts/:              # the route
    permalink: /{slug}/
    template: jobs        # the template name
    data: page.prompts    # the page url 
    filter: tags:-[blog]  # exclude blog posts

If you are using the English version, you need to edit the locales/en.json file, and replace words like "job", and "position" on the right side. For example, in case you are planning to create a prompt library:

  "Featured job posts": "Featured prompts",
  ...
  "Search jobs": "Search prompts",

Check all the other strings and change them according to your needs. This way you can create any type of listing site.

Theme development

If you want to make more advanced changes to the theme, or you want to implement your own components, you can take advantage of the developer-friendly setup of the theme.

All the assets are combined and minified for better speed and performance. To customize the theme make sure you have Node.js installed.

The theme is built with TailwindCSS and Alpine.js. The development environment is based on Vite, the tasks can ran with npm scripts.

This guide is assuming that you have installed Ghost locally. Add the theme directory inside Ghost's content/themes/ directory then move to the theme directory in your command line. Run the npm install command to install all the dependencies.

After that is done, you have access to run the npm scripts:

1. npm run dev (vite build --watch & vite) The dev script will start the development process, watching for changes and building. The vite.config.js file contains the main configuration for Vite.

2. npm run build (vite build) The build script will start the build process.

3. npm run test (gscan . --verbose) The test will test the theme using gscan the official Ghost test tool.

4. npm run zip The zip script will create a zip file in the dist directory.

Support

Don't hesitate to reach out if you need help or have any suggestions.

Contact - Feedback