What's the process for adding additional tailwind utility expressions?

[rshmhrj]

Hi @jpanther -- this seems very similar to #77...
Maybe the answer is this:

./themes/congo/node_modules/tailwindcss/lib/cli.js -c ./themes/congo/tailwind.config.js -i ./themes/congo/assets/css/main.css -o ./assets/css/compiled/main.css --jit

I'm trying to create a shortcode for an amazon affiliate link and am trying to use something like my-0 to remove the vertical margin. The line in question is number 5 with the image in the amzn-affiilate.html file below.

shortcode usage

{{< amzn-affiliate link="https://www.amazon.com/gp/product/..." 
img="cover.jpg" title="Idea to Invention" 
subtitle="What You Need to Know ..." 
author="Patricia Nolan-Brown" author-pic="author.jpg" >}}

amzn-affiliate.html

<div class="w-full my-0 place-self-center">
    <div class="flex my-0 items-center place-self-center">
        <div class="flex my-0 m-2">
          {{ with .Get "link"}}<a href="{{.}}">{{ end }}
          <img src="{{ .Get "img" }}" class="flex rounded" width="200">
          {{ if .Get "link"}}</a>{{ end }}
        </div>
        {{ if .Get "title" }}
        <div class="ml-3 flex-row">
            <div class="m-0 pb-0">
              <a href="{{ .Get "link" }}">{{ .Get "title" }}
              {{ if .Get "subtitle" }}: {{ .Get "subtitle" }}{{ end }}
              </a>
              </div>
            <div class="flex items-center m-2 h-24">
              {{ if .Get "author-pic" }}<img src="{{ .Get "author-pic" }}" width="50" class="rounded-full">
              {{ else }}<img src="{{ "img/noun-person-1995015-22D3EE.svg" | relURL }}" width="50" class="rounded-full">
              {{ end }}
                <p class="text-sm leading-none ml-3">{{ .Get "author" }}</p>
            </div>
        </div>
        {{ end }}
    </div>
</div>

When it renders the img tag, it adds 2em on either side, so mouseover looks odd

My hack solution is adding a style <img src="{{ .Get "img" }}" class="flex rounded" width="200" style="margin-top: 0px; margin-bottom: 0px;"> but I would rather try to use tailwind (and learn it better).

When I look at the compiled/main.css there is no my-0 class available. What are the steps to take in order to get additional css either in core congo, or in the generated sites? Also, what about adding additional m-# p-# w-# etc.?

[jpanther]

This is something that I think I should write some proper documentation for but I'll try to explain by using the process for my own website which also relies on additional Tailwind classes that aren't part of the core theme CSS. I'll expand the scope of my response to be broader than your specific example in the hope this answer helps others so I apologise if some of this comes across as rudimentary.

The problem

I want to use standard Tailwind CSS classes to add additional functionality to my website but when I add these classes to my layout files or Markdown content, they are not being applied.

Why this happens

Although it may seem counterintuitive this is the expected behaviour. Tailwind CSS includes thousands of possible style combinations and to include them all in the theme would be a monumental waste of resources and result in massive CSS files full of unused style declarations. In order to avoid this situation, traditionally you would configure Tailwind to only include a subset of styles or colours, and this is how a lot of Tailwind websites are built.

Congo is different. One of the more recent features included in Tailwind v2.1 is the concept of "just-in-time" CSS compilation, or JIT. The JIT compiler essentially generates CSS on demand by analysing your website content and including only those styles that are required to display your website. This obviously has huge performance benefits as it keeps the CSS file size small, but has the caveat that if you want to be able to add new styles to your website, you need to recompile the Tailwind CSS file.

The solution

There are a few possible solutions to this, many are quite hacky, and so I'm only going to focus on what I think is the cleanest, most correct way of doing it - that is, to compile your own CSS so that you get a proper minimised file with only the styles you need.

Tailwind configuration

So the question now is, how do I recompile the Tailwind CSS file? In order to generate a CSS file that only contains the Tailwind classes that are actually being used the JIT compiler needs to scan through all the HTML templates and Markdown content files to check which styles are present in the markup. The compiler does this by looking at the tailwind.config.js file which is included in the root of the theme directory:

// themes/congo/tailwind.config.js

module.exports = {
  content: [
    "./layouts/**/*.html",
    "./content/**/*.{html,md}",
    "./themes/congo/layouts/**/*.html",
    "./themes/congo/content/**/*.{html,md}",
  ],

  // and more...
}

This default configuration has been included with these content paths so that you can easily generate your own CSS file without needing to modify it, provided you follow a particular project structure. Namely, you have to include Congo in your project as a subdirectory at themes/congo/. This means you cannot easily use Hugo Modules to install the theme and you must go down either the git submodule (recommended) or manual install routes. The Congo docs explain how to install the theme using either of these methods.

Sidenote: Given building the CSS manually like this is considered an advanced customisation I think that this is an okay trade-off but if you really want Hugo Modules, you'll need to look at making a custom build script for your website that can locate the Hugo Module in Hugo's cache directory and that's beyond the scope of this answer.

Project structure

Now that we understand how all this works, essentially, your project should look something like this...

.
├── assets
│   └── css
│       └── compiled
│           └── main.css  # this is the file we will generate
├── config  # site config
│   └── _default
├── content  # site content
│   ├── _index.md
│   ├── projects
│   │   └── _index.md
│   └── blog
│       └── _index.md
├── layouts  # custom layouts for your site
│   ├── partials  
│   │   └── extend-article-link.html
│   ├── projects
│   │   └── list.html
│   └── shortcodes
│       └── disclaimer.html
└── themes
    └── congo  # git submodule or manual theme install

This structure adds a new projects content type with its own custom layout along with a custom shortcode and extended partial. Provided the project follows this structure, all that's required is to recompile the main.css file.

Install dependencies

In order for this to work you'll need to change into the themes/congo/ directory and install the project dependencies. You'll need Node and npm on your local machine for this step.

cd themes/congo
npm install

Run the JIT compiler

With the dependencies installed all that's left is to use Tailwind CLI to invoke the JIT compiler. Navigate back to the root of your Hugo project and issue the following command:

cd ../..
./themes/congo/node_modules/tailwindcss/lib/cli.js -c ./themes/congo/tailwind.config.js -i ./themes/congo/assets/css/main.css -o ./assets/css/compiled/main.css --jit

It's a bit of an ugly command due to the paths involved but essentially you're calling Tailwind CLI and passing it the location of the Tailwind config file (the one we looked at above), where to find the theme's main.css file and then where you want the compiled CSS file to be placed (it's going into the assets/css/compiled/ folder of your Hugo project).

The config file will automatically inspect all the content and layouts in your project as well as all those in the theme and build a new CSS file that contains all the CSS required for your website. Due to the way Hugo handles file hierarchy, this file in your project will now automatically override the one that comes with the theme.

Each time you make a change to your layouts and need new Tailwind CSS styles, you can simply re-run the command and generate the new CSS file. You can also add -w to the end of the command to run the JIT compiler in watch mode.

Make a build script

To fully complete this solution, you can simplify this whole process by adding aliases for these commands, or do what I do and add a package.json to the root of your project which contains the necessary scripts...

// package.json

{
  "name": "my-website",
  "version": "1.0.0",
  "description": "",
  "scripts": {
    "server": "hugo server -b http://localhost -p 8000",
    "dev": "NODE_ENV=development ./themes/congo/node_modules/tailwindcss/lib/cli.js -c ./themes/congo/tailwind.config.js -i ./themes/congo/assets/css/main.css -o ./assets/css/compiled/main.css --jit -w",
    "build": "NODE_ENV=production ./themes/congo/node_modules/tailwindcss/lib/cli.js -c ./themes/congo/tailwind.config.js -i ./themes/congo/assets/css/main.css -o ./assets/css/compiled/main.css --jit"
  },
  // and more...
}

Now when you want to work on designing your site, you can invoke npm run dev and the compiler will run in watch mode. When you're ready to deploy, run npm run build and you'll get a clean Tailwind CSS build. I'll often run npm run dev and npm run server alongside each other to build my custom templates.

And that's it! Sorry for the really, really long answer, but I hope this helps explain the process in full. Let me know if you have any questions!

[rshmhrj]

Absolutely amazing answer -- thanks so much for the details, for sharing your wisdom, and for all the time and energy you spend on this project for us!

[jpanther]

A similar version of this information is now also included in the project docs - see Building the theme CSS from source.

[rshmhrj]

Thanks @jpanther --- in order to better practice Tailwind, do you know how I can get ALL of the utility classes compiled into the blog's main.css (just for local dev)?

[jpanther]

I don't believe it's possible to do this easily in Tailwind v3, however there is a Play CDN that you can use to achieve a similar result. You can read more about it in the Tailwind docs. If you do use the Play CDN be sure to include the typography plugin.