Chapters
  1. Overview
  2. Installation
  3. Presets
  4. Post types, series and code
  5. Custom settings
  6. Members and comments
  7. Navigation
  8. Translations
  9. Demo content
  10. Customising
  11. Self-hosting
  12. Troubleshooting
  13. Changelog

Customising

What you can change without a rebuild, what the code highlighting loads, and how to rebuild the theme's CSS when you need to.

Most changes need only Ghost Admin. You only rebuild the theme's stylesheet when you add a CSS class the theme didn't use before or edit its CSS files, and the steps below work even if you've never opened a terminal.

Without a rebuild

  • The theme's settings in Settings → Site → Design & branding → Customize → Theme: preset, colours, fonts, the home page layout, the wordmark, the header, and for code the ligatures, the line numbers, the table of contents and the note on old posts (see Custom settings).
  • Code blocks in the editor: the language, a file name, tabs, diffs, collapsed and wrapped blocks are all typed into the code card's language field, such as ts file=src/router.ts collapse (see Post types).
  • Code injection for the whole site in Settings → Advanced → Code injection → Open, on the tabs Site header and Site footer, or for one post in the post settings under Code injection. CSS you put there in a <style> element applies on top of the theme, for example an extra rule. It survives every theme update, because it isn't part of the theme.
  • Portal and the accent colour, under Settings → Membership → Signup portal and Brand → Accent color.
  • Templates: you can rearrange or edit the .hbs files in the theme, as long as you only use CSS classes the theme already uses somewhere. Then zip the theme and upload it.
  • Texts and translations in the folder locales (see Translations).

Code highlighting

The highlighting is part of the theme and comes from your own site, like everything else Logbuch loads. A page without a code block loads none of it. A page with code loads the highlighter, about 54 KB compressed, and one small file for each language that page shows, so a post with only TypeScript and a terminal session fetches those two grammars and nothing else.

Logbuch highlights 29 languages. Type the name or one of its short forms as the first word of the code card's language field:

LanguageType
Bash and shellbash, sh, shell, shellscript, zsh
Terminal sessionconsole, terminal
Cc
C#csharp, cs
CSScss
Diffdiff, or diff- before another language, such as diff-ts
Dockerdocker, dockerfile
Gogo
GraphQLgraphql
HTMLhtml
INIini
Javajava
JavaScriptjavascript, js
JSONjson
JSXjsx
Kotlinkotlin
Lualua
Makemake, makefile
PHPphp
PowerShellpowershell, ps1
Pythonpython, py
Rustrust, rs
SCSSscss
SQLsql
Swiftswift
TOMLtoml
TSXtsx
TypeScripttypescript, ts
XMLxml
YAMLyaml, yml

Any other language, such as Ruby, C++ or Markdown, shows as plain code in the same band, with its file name and the copy button. The colours come from the colour scheme of your preset, light and dark.

You can't add a language or change how the highlighting works, because the download doesn't include the source of the theme's scripts. The same goes for the rest of its JavaScript. Add your own scripts through Code injection instead.

With a rebuild

Logbuch's stylesheet is built with Tailwind CSS. Tailwind looks at the theme's templates and only writes the CSS classes it finds there into the finished file, assets/built/screen.css. So if you add a class to a template that the theme didn't use before, for example uppercase on a heading, nothing happens until you build the stylesheet again. The same applies when you edit the CSS files in assets/css.

Install Node.js once

  1. Download the LTS version of Node.js from nodejs.org and install it. It comes with npm, and you need no other package manager.
  2. Open a terminal: on macOS the app Terminal, on Windows PowerShell from the Start menu, on Linux your usual terminal.
  3. Type node --version to check that it worked. You should see a version number.

Build and pack the theme

  1. Unpack logbuch.zip on your desktop. It contains one folder, logbuch. Make your changes there.
  2. In the terminal, go into that folder. On macOS and Linux:
cd ~/Desktop/logbuch

On Windows:

cd $HOME\Desktop\logbuch
  1. Install the build tools. This creates a folder node_modules and takes a minute the first time:
npm install
  1. Build the stylesheet:
npm run build
  1. Pack the folder into a new logbuch.zip, without node_modules. On macOS and Linux:
cd ..
zip -r logbuch.zip logbuch -x "logbuch/node_modules/*"

On Windows, delete the folder node_modules inside logbuch first, then:

cd ..
Compress-Archive -Path logbuch -DestinationPath logbuch.zip -Force
  1. Upload the new logbuch.zip as described under Update to a new version.

Keep your changed folder. When a new version of Logbuch comes out, unpack it, carry your changes over, build and upload again.