Skip to content

Latest commit

 

History

History
135 lines (91 loc) · 4.07 KB

README.md

File metadata and controls

135 lines (91 loc) · 4.07 KB
Raw

Felix

The Ghost theme for Felix, the student newspaper of Imperial College London since 1949.

Felix website on 2024-11-02

This is a fork of the official Ghost theme Source, styled in line with Felix brand guidelines.

Development

Project setup

Install Node.js, for example, using nvm, like so

# installs Node.js v20.11.1
nvm install 20.11.1

To check that Node is installed correctly, try running node --version. It should output the version number.

Next, enable the yarn package manager by running

# install yarn package manager
corepack enable

Check out the project code using git or an IDE. Open a terminal in the theme root directory. Run the command below to install project dependencies.

# install dependencies
yarn install

Make sure Docker Desktop is installed. Start a local Ghost web server and database with the command below.

# starts Ghost CMS in a Docker container
docker compose up

Use CTRL+C to stop the Ghost server once you are done.

The first run can take a while to initialise. Once Ghost is ready, the site should be ready at http://localhost:8080.

If you encounter permission issues with the .git folder, you may need to reset its permissions with

chmod -R 777 .git

Go to the Ghost admin panel http://localhost:8080/ghost/ and create your local administrator account.

Testing locally

The build process uses Gulp and PostCSS to compile the source styles into minified, optimised, and future-proof CSS.

When working locally, the development server can handle theme compilation automatically. As soon as it detects changes, it recompiles the necessary theme files. To start the development server, run the command below.

# run development server
yarn dev

Deploying to production

From the root folder of the project, run the command below to package the theme for deployment.

# create .zip file
yarn zip

The compiler saves the zip archive into dist/felix.zip. You can upload this zip file to the official Felix website.

Theme project layout

Ghost uses a simple templating language called Handlebars for its themes. Take a look at the Ghost theme API documentation, which explains every possible Handlebars helper and template.

The main files are:

  • default.hbs - The parent template file, which includes the global header/footer
  • home.hbs - The homepage
  • index.hbs - The main template to generate a list of posts
  • post.hbs - The template used to render individual posts
  • page.hbs - Used for individual pages
  • tag.hbs - Used for tag archives, e.g. “all posts tagged with news”
  • author.hbs - Used for author archives, e.g. “all posts written by Jamie”

Adding the slug of a page to a template file creates a custom one-off template. For example:

  • page-about.hbs - Custom template for an /about/ page
  • tag-news.hbs - Custom template for /tag/news/ archive
  • author-ali.hbs - Custom template for /author/ali/ archive

Code standards

CSS auto-prefixing

Do not worry about writing browser prefixes of any kind, it is all done automatically with support for the latest two major versions of every browser.

SVG Icons

This theme uses inline SVG icons, included via Handlebars partials. You can find all icons inside /partials/icons. To use an icon, include the name of the relevant file. For example, to include the SVG icon in /partials/icons/rss.hbs use {{> "icons/rss"}}.

You can add your own SVG icons in the same manner.

Copyright & Licence

Released under the MIT licence.

  • Copyright © 2013–2023 Ghost Foundation
  • Copyright © 2024 Felix