Unfortunately, the official documentation on theming lemmy is severely lacking. I made some progress on getting it figured out today, so I wanted to share that with you all.
This is by no means meant to be an exhaustive guide, but my hope is that it will at least get you going. I’m sure that I will say things that are incorrect, so please correct me if you know better!
Background
Lemmy uses Bootstrap-compatible theming. As far as I can tell, this means that it uses a pre-defined set of CSS classes. This is important because if you provide a CSS file that doesn’t have all of the correct classes defined, it will break the layout of your lemmy.
Your custom CSS needs to be saved in the bind mount for your lemmy-ui container. If you followed the install instructions on join-lemmy.org, the location will be /lemmy/volumes/lemmy-ui/extra_themes/.
Prerequisites
In order to generate the correct CSS, you need a couple of things:
- your customized Bootstrap variables, saved in an scss file
- the Bootstrap scss files
- the SASS compiler
Let’s go through each of these (last to first):
The SASS compiler
The SASS compiler needs to be installed on the machine you will use to generate your CSS files (it doesn’t NEED to be the computer that lemmy is installed on, but it can be). Follow the install instructions relevant to you. I used the “Install Anywhere (Standalone)” instructions and installed SASS on the Ubuntu machine that is running my lemmy instance.
The Bootstrap scss files
These files need to be saved on the same machine as the SASS compiler. The Bootstrap download page has a button to download the source files (“Download source”). This will give you a zip folder, so unzip it. Within the unzipped files, the only directory you need to keep is /bootstrap-5.3.0/scss. Save that folder in a place that makes sense for you. I put it in my home directory, so the path looks like ~/bootstrap-5.3.0/scss. You’ll need to reference this directory when you’re creating your custom scss file.
Your customized Bootstrap variables, saved in an scss file
This is the fun part… you define your Bootstrap variables. I’m still a little unclear on which version of Bootstrap lemmy is using (and therefore which variables are valid), so I chose to start with one of lemmy’s default themes as a starting point. I grabbed _variables.litely.scss and litely.scss from the lemmy-ui github repo as a starting point.
You’ll notice that litely.scss is just importing variables.litely as well as the Bootstrap scss files. You’ll need to change the path of the Bootstrap scss files to the path where you saved your copy of the files. However, leave bootstrap at the end of the file path, as this is actually referring to the bootstrap.scss file within the Bootstrap scss directory.
Generating the CSS file
Once you have all of the prerequisites satisfied, you can generate your CSS files using the SASS compiler. Go to the directory where your customized scss file(s) are saved, and run this command (you added the SASS install directory to your PATH, right??):
sass [inputfile.scss] [outputfile.css]
This will generate a CSS file. However, pay attention, as there might be errors. If so, fix the errors until you can run SASS without any errors.
Finally, drop the generated CSS file into your “extra_themes” directory. You’ll now see your theme show up in the list of themes on your profile (it’ll be the filename of your CSS file).
And that’s it! I hope somebody finds this helpful. Please let me know if there’s anything I can clarify!
Respectfully I don’t think what I’ve written here is appropriate for official documentation, mostly because I don’t know what I’m talking about. My hope is that somebody who DOES know what they are talking about could use this as a starting point for updating the documentation.
Something is better than nothing. Don’t let the perfect be the enemy of the good enough™. It can always be improved later, and nothing motivates contributions more than if someone writes something slightly wrong on the internet.