This theme is open source and you are welcome to adapt it to your own needs, or to contribute changes to the main project. See the github project for details:

GitHub - nickabs/transmission: transmission Ghost theme
transmission Ghost theme. Contribute to nickabs/transmission development by creating an account on GitHub.

Making changes to the theme

The following guide is aimed at Mac users and takes you through how to set up the theme development environment so that you can customise the theme and release the changes to your web site. Note that you will need to amend the file paths to reflect the locations on your machine.

The first thing to do is to install the version of Node that is recommeded by Ghost.

The easiest way to install Node is to use nvm (the node version manager). Once installed nvm makes it very easy to install and switch between different versions of npm:

 
nvm use 16
>Now using node v16.9.1 (npm v7.21.1)
node -v
>v16.9.1
nvm use 14
>Now using node v14.18.0 (npm v6.14.15)
node -v
>v14.18.0
nvm install 12
>Now using node v12.22.6 (npm v6.14.5)
node -v
>v12.22.6

If you don't already have a local Ghost development environment, see the official documentation for instructions.

When you are ready to start working on the theme, begin by downloading the latest release of the theme and unzip it on your local machine or - if you have forked the repository - you can clone your new repository instead.

You then need to install the node modules that are required by the theme. The theme uses the npm package manager, which is installed automatically with Node:

cd ~/dev/themes/transmission

# Install
npm install

... which will install the development and production dependencies listed in package.json into transmission/node_modules.

Next, create a symbolic link to the themes directory of your local Ghost development installation (this will allow you to select the theme via the Ghost admin interface):

ln -s ~/dev/themes/transmission ~/dev/www/ghost/content/themes

Before making any changes, cd to the theme root directory and run the following command in a terminal window

# Run build & watch for changes
npm run dev

The npm run dev command starts up a file watcher that will rebuild the theme assets whenever you make a change to the source code (see scripts/theme-build for details). The command also starts a live reload service.

Live reload is an approach to development where you have your browser open and visible at the same time as your code editor. The browser automatically reloads when you save changes to the source code. This means you don't have to manually switch to your browser, reload, and then switch back to your code editor after every change. If you would rather not use live reload, use npm run watch rather than npm run dev.

You can use any code editor you choose. I use Visual Studio Code which can be used with the handy Ghost VS Code extension.

building the js and css files

When npm run dev is running the javascript and css files are automatically bundled and minimised after every saved change (the bundled files are placed in a director called assets/built). This process is managed by a build tool called esbuild.

Creating an installable zip file

To create an installable zip file that contains all the built assets needed to run the theme on a external web site, use the npm run zip task. The built files, including your latest changes, plus all the other files needed by the theme will be added a single zip file located at dist/transmission.zip. This zip file can be installed on your site.

You can read about automating the release process in the next section.

Release utility

If you have forked the theme to make your own changes, you can automate the deployment of new versions using a combination of the theme-release utility that is included as part of the theme and Github workflows.

The theme-release utility is used to create new GitHub releases from the command line. The release note will contain a list of all the changes you have committed since the previous release and a zipped archive of the latest version of the theme assets will be included along with the note as part of the release. This zip file can be used by others to install the newly released version of the theme.

Before using the theme-release utility you need to do the following:

  1. create a subdirectory in your local theme repo directory called changelogs
  2. Create a personal access token in your github account: Developer settings> Personal Access Tokens > Tokens (classic). The token needs 'repo' permissions.
  3. Assign the token to a local environment variable called GITHUB_TOKEN (this can be set in your ~/.bashrc file by adding a line that says export GITHUB_TOKEN="your-github-token")
  4. install gscan using npm install -g gscan

The script will create releases in the repository identified in the project's package.json file, so make sure you have the correct GitHub repo listed and that the token created above has the necessary 'repo' permissions:

"repository": {
        "type": "git",
        "url": "https://github.com/your-github-account/transmission.git"
},

Usage

To create a release of all the changes pushed to GitHub since the previous release:

npm run bump-patch # bump the (patch/minor/major) version and commit changes.
npm run full-release

The npm run full-release command does the following:

  1. gscans the theme to check it is valid
  2. creates a changelog based on GitHub commits since the previous release
  3. creates an updated dist/transmission.zip file
  4. creates a github release with a tag based on the version in package.json
  5. uploads the transmission.zip file to the release

alternative you can use npm run draft-full-release to create a draft release (this will allow you to review the release in github before making it public)

if you prefer you can run each of these stages separately using the appropriate npm run scripts:

use npm run to get a full list of all the npm scripts available in the theme.

Use GitHub Actions to deploy your theme

You can automatically deploy your theme to your site using GitHub Actions, as explained below

The transmission theme uses the Ghost GitHub deploy integration to automatically deploy changes.

I use two workflows: the demo workflow deploys the theme to this website whenever a new release is created. The second workflow deploys the modified theme to my personal web site (smallworkshop.co.uk) whenever changes are pushed to the main branch. See the files in .github/workflows for details.

If you want to use similar automation for your sites, you'll need to create a new Ghost integration and load the credentials to github, as explained in the article below. Note the credentials are stored in the repository’s secrets (go to your theme repository on GitHub > settings> Secrets and variables > actions)

Official Ghost + GitHub Integration
Set up simple continuous integration of your Ghost theme to deploy directly to your Ghost website with GitHub Actions. Share code snippets with GitHub Gists 👨‍💻

Contributing to the project

The main branch always contains the latest changes. Released versions are tagged using semantic versioning.

You should submit your pull requests to main.

Submitting Pull Requests: please provide plenty of context and reasoning around your changes.

Demo mode

The demo mode used on this site - which allows users to experiment with custom settings without having to login and use the admin tool - is built into the theme. You can enable this functionality on your own demo site by using code injection to add this script:

<script>
  /* demo mode not visible when in an iframe (e.g Ghost's marketplace)*/
  if (window.self == window.top) {
    document.documentElement.setAttribute('data-demo-site', 'true');
  }
</script>