Building a custom theme with Tailwind CSS locally?

I’m working on my own custom theme: GitHub - Nezteb/theme-nezteb: A micro.blog theme I'll be building out to support my personal website: nezteb.net

I’m trying to set up Tailwind CSS via their CDN. Has anyone done this before? I’m new to both micro.blog and Hugo. I’m reading through the Hugo docs, but having some troubles finding a good workflow.

Is there an easy way to test a theme locally using either data from micro.blog or stub data? I’d like to be able to run hugo server (or some other command) and then see my theme with content. Is anyone aware of such a flow?

I’d appreciate any and all ideas folks might have! :smile:

You can look at a version of my theme GitHub - jsonbecker/theme-dailylog. I use the exampleSite folder, like a lot of hugo themes, so that I can see roughly what will happen by just using hugo server locally. I adjust that content if I want to see different features.

If you want to get the Markdown files from your Micro.blog blog, you can click Posts → “…” → Export → “Export theme and Markdown”. Then you can copy the files over from the “content” folder.

After testing locally, you can also create a test blog on Micro.blog (under Design → Edit Custom Themes → New Test Blog). Then pull in the theme from GitHub and test it without messing with your real microblog.

Local development is easier than it first appears.

Hugo

The first step is to decide on and download one of the two Hugo versions that Micro.blog supports: version 0.54 or version 0.91
(I chose 0.91 and had no issues.) Follow Hugo’s documentation to install it on your operating system.

Content to Style

After Hugo is installed on your system, I highly suggest populating it with your own blog’s data. Things make more sense when you are working with familiar data.
Screenshot 2023-01-12 at 2.25.13 PM

  1. While logged into Micro.blog, visit your Posts page
  2. At the top of the page, to the right of your blog’s URL, is an icon of ellipsis within a circle “…”
  3. Click the icon and, in the popup menu that appears, click Export. You will be taken to an export page where you can download Export theme and Markdown together.
  4. Copy those downloaded files into the content folder of the local site Hugo created.

Tailwind

Tailwind requires its own setup for local editing. Because Tailwind uses custom CSS that can cause many editors to return false errors, it is apparently not as simple as including a CDN link in your project. (They devote an entire page to editor setup.)

With those three things completed you’re ready to run the Hugo server function, fire up your editor, and start designing your custom theme. :smiley: Happy coding!

Don’t forget:

  • Your custom theme requires a free Github account and Git installed on your system. (I personally like using the GitHub Desktop app.)
  • You don’t need to upload your entire local Hugo structure to GitHub, just the theme itself.
  • This help site has a lot of good answers. The introductory Custom Theme article is a good place to start.

@Nezteb I realize you probably know all or most of the above but I thought I’d add it here in case somebody else has the same questions.

3 Likes

If I’m storing my theme files in a GitHub repo, how should I be editing/updating the theme?

  1. Use the built-in micro.blog theme file editor, after which micro.blog automatically adds/pushes a new commit to the repo?
  2. Manually add/push a new commit to the repo itself, after which micro.blog pull the new commits and updates my theme accordingly?

Neither works. If you’re using Github, you can, once you’re done, do a one time sync of that repo to Micro.blog. To pull it back, I think you have to delete and re-add the theme.

What I end up doing is working locally by exporting my theme from Micro.blog, when I’m done, I push to Github, and then I manually paste in the changed files in Micro.blog.

The other option is to publish your theme as a plug-in, in which case incrementing the version number on Github will give you the option to update the plug-in and pull the changes. That requires that your theme is publicly available.

1 Like