cross-posted from: https://tkohhh.social/post/4829

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.

It wasn't obvious to me initially, but you can also add your own CSS styles at the bottom of your scss file. These will be merged with the styles defined in the Bootstrap files. For instance, I wanted my navbar to have a different font from the body, so I added this:

#navbar {
  font-family: sans-serif;
}

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!

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.

It wasn't obvious to me initially, but you can also add your own CSS styles at the bottom of your scss file. These will be merged with the styles defined in the Bootstrap files. For instance, I wanted my navbar to have a different font from the body, so I added this:

#navbar {
  font-family: sans-serif;
}

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!

I'm hoping one of the developers can help point me in the right direction.

I'm trying to create a theme, and I started by downloading the litely.scss and _variables.litely.scss files from the github repo. I renamed the files and made some changes, and then used https://bootstrap.build to generate a css file. I dropped that file (along with my scss files) into the extra_themes directory on my server.

Sure enough, my new theme was available in the list of available themes. However, when I applied the theme, I found that the layout was broken (see screenshot).

So, my question is: how can I generate the css file in the proper manner so as not to break the layout? Is there a specific Bootstrap tool that we should be using to generate the css? Are there additional input files that need to be included in order to generate the correct css?

Thanks for any help you can provide!

The server has been updated to version 0.18.2

See the release notes here: https://join-lemmy.org/news/2023-07-11_-_Lemmy_Release_v0.18.2

In response to the XSS exploit (described here), I have updated the server UI to version 0.18.2-rc.2, which fixes the vulnerability.