Working with Hugo and your MicroBlog Locally with Claude Code for Testing and Learning

There was some discussion about learning Hugo and making your own Theme for your Micro.blog. I’d love to do this as well and thought I would dive in and share the progress I’ve made so far.

I will strive to update this post with my learning Hugo journey. If it turns into something more, I may make it a dedicated Page on my blog instead of a Post.

Note: I’m a hobbyist programmer with 2 years of college programming in C++ and many online classes with Python, HTML, CSS, and JavaScript. I’ve produced one fully functioning Python web app where pilots could drop their logbook of flying for the year, and it would generate a map of all their travels. I’ll note that was before any A.I., so it was hard-won with lots of research and studying!

I’ve taken long breaks from my programming hobby, which means I forget a lot of what I’ve learned and have to start over.

All that to say, I don’t know much, just enough to be dangerous. Use anything I say with caution. My technical terms will probably be wrong, and my approach will probably be the hardest or the worst, or both!

This will not be an exact step-by-step guide, but it will be enough to get you going with one way to do things. As you will see, Claude will give you the step-by-step.

Why?

I love tweaking my two blogs, mostly with custom CSS, but I have expanded into the guts of Hugo (the blogging engine) to alter posts with additional data. I love learning, and I love understanding how things work and why.

I’ve done extensive custom CSS with Cliff538, all within MicroBlogs' online interface, and it is very dangerous to do it this way. It may be a function of using Safari with so many tabs open, but typing, cutting, pasting, and making a page active, my cursor can lag and jump around. I’ve had some terrible incidents where I’ve deleted stuff I didn’t mean to or copied/pasted that didn’t work right. All this to say it’s better to do your work in an IDE with a Hugo Server running, so you can see your changes. No weirdness, no risk of messing with your actual blog until you know everything works. Plus, working locally lets you use version control—big win.

Now, with ChatGPT or Claude, you can have assistance and a teacher with precisely what you want to do and learn. This is what A.I. is for, in my opinion. If you can understand Hugo from reading the docs, I’m jealous. I’m a reader, but I need to see it in action and have someone explain the why to me. This is where Claude and Claude Code come in.

How?

Things you need

  • Homebrew or other package manager.
  • An Anthropic account and sign up for their Pro Plan, it’s $17/month, and notably includes usage of Claude Code
  • Download and open the Claude App
  • VS Code or other IDE. VS Code is ideal because Claude Code integrates with it.
  • Download your MicroBlog blog’s data

The Process

Open the Claude App, make a new Project so you can reference it later, and I believe this helps with memory also, and type in a prompt, something like what I did.

My blogs are at Micro.blog service. I use their online code interface 
to work on my code, but I don't want to do this anymore. 
How can I connect my current blog code to a GitHub repository 
to experiment with changes, or start a blank Hugo blog and learn 
to customize my own theme? I want to use Claude Code with VS Code. 
I want to use Git and GitHub for local and cloud version control. 
I want step-by-step instructions and explanations for why we are doing each step. 
My blog, Cliff538, currently uses Tiny Theme.

Now, you can stop reading here and follow what Claude says. It brought me to the point of having my exact current blog running locally on my Mac. I make HTML/CSS changes and watch them live. When I’m happy with the changes, I save them locally with Git, and at the end of the day, I upload changes to GitHub for safekeeping in a private repository. Then, as of now, I copy and paste my changes into my actual blog. I haven’t researched whether you can connect a GitHub account to your active blog and how quickly it syncs. That may be the next step in the process.

Anytime you don’t understand something or why, stop and ask Claude. It explains everything to you (hopefully correctly). This is not an exercise in Claude just doing all these things, unless you want that. Use Claude as a teacher.

Tips and Suggestions Working With Claude and Claude Code

  • Claude App is totally separate from Claude Code. You can use both at the same time. Claude Code lives in your Terminal App or within VS Code and is activated and shut down separately from the Claude App. There are more limitations on usage with Claude Code, so use the Claude App for general questions.
  • Use lots of screenshots. I probably sent Claude 30 different screenshots so it could see what the problem was, it’s easier than explaining it. It works very well.
  • You can permit Claude Code to modify files within a folder. This worked very well for me when fixing errors. I would let CC fix them, then explain to me why. You can look at the code being altered and ask questions. Git is very handy here; you can open a split screen and see the changes being made.
  • Anthropic has a page where you can see your Current Session and Weekly Limits. Watch this to learn how many tokens you are using. You can always upgrade your plan or allow Extra Usage. So far, I haven’t bumped up against any limits yet.
  • Be as detailed as you can with questions, send screenshots, and if you don’t understand something, ask, then continue. Use the teacher that you are paying for.
  • If Claude gives you instructions to work on the command line and you are not comfortable doing that, ask for an alternative way. It’s just an LLM; you tell it what you want.
  • I haven’t had to tell Claude to slow down and think longer yet, but working with ChatGPT, I’d get clearly wrong answers, and it would be off track from the question asked. I would have to say, “Stop, look at the question, slow down, and think longer on the problem”. It would help. But so far, Claude has been outstanding.

Continuing with my process, this will be a lot of pasted instructions from Claude. To give you an idea of the workflow. This is not a linear how-to, just an example. Scroll to the very bottom for a summary of this first step of learning.

Exporting Your Current Micro.blog Sites

In Micro.blog, go to ‘Design’, click on the 3 dots next to your domain name, then click “Export” and download your “Theme and Markdown” as a “.zip”. This gives you both your content and your current theme.

Important note about photos: If you have posts with photos, you’ll need to replace the URLs as they don’t work correctly and won’t have been downloaded - you can go through each post and add your domain to the front of each URL.

GitHub Experimental Repository__ (Recommended for learning)

This approach lets you experiment safely while keeping your live sites on Micro.blog:

Set up a local Hugo site on your Mac:

brew install hugo
   hugo new site cliff538-Local
   cd my-blog-experiments

About here, Claude went off in a different direction and I had to steer it back on track with this:

I have downloaded both of my blogs from Micro.blog. I would like to 
set up a local working HUGO environment that exactly matches my 
current live blog. I can experiment with changes on my local blog 
then see about making changes to it later. Right now it will mostly 
be custom CSS changes. I would like to use Claude Code so I can 
learn how to use it. Please guide me through the process please.

Perfect! Let’s get you set up with a local Hugo environment that matches your live blogs, and we’ll use Claude Code to help manage everything. I’ll walk you through this step-by-step.

Step 1: Install Required Software

First, let’s make sure you have everything installed on your Mac:

# Install Hugo if you haven't already
brew install hugo

# Install Claude Code
brew install --cask claude-code

# Verify installations
hugo version
claude --version

Step 2: Choose Which Blog to Set Up First

Since you have two blogs (365pixels.xyz for photos and cliff538.com for general posts), let’s start with one. Which would you like to work on first? I’d suggest starting with whichever one you want to customize the CSS for most urgently.

For this guide, I’ll use 365pixels.xyz as the example, but the process is identical for cliff538.com.

Step 3: Create Your Local Hugo Site

# Create a directory for your blog projects
mkdir ~/hugo-blogs
cd ~/hugo-blogs

# Create a new Hugo site
hugo new site 365pixels-local
cd 365pixels-local

Step 4: Extract and Copy Your Micro.blog Export

  1. Find your downloaded .zip file from Micro.blog (probably in your Downloads folder)
  2. Extract it
  3. Now let’s copy the files into your Hugo site:
# Navigate to where you extracted the Micro.blog files
# Then copy them to your Hugo site
# (Replace the path below with your actual extracted folder location)

# Copy content
cp -r /path/to/extracted/microblog/content ~/hugo-blogs/365pixels-local/

# Copy data folder if it exists
cp -r /path/to/extracted/microblog/data ~/hugo-blogs/365pixels-local/

# Copy static files (images, CSS, etc.)
cp -r /path/to/extracted/microblog/static ~/hugo-blogs/365pixels-local/

# Copy the theme
cp -r /path/to/extracted/microblog/themes/* ~/hugo-blogs/365pixels-local/themes/

Step 5: Convert and Copy Configuration

Your Micro.blog export includes a config.json file, but Hugo typically uses config.toml or hugo.toml. Let’s handle this:

cd ~/hugo-blogs/365pixels-local

Now, open the config.json from your export and we’ll need to convert it. Can you paste the contents of your config.json file here? I’ll help you convert it to the proper format.

Step 6: Initialize Git and Start Claude Code

Once we have the config sorted:

# Initialize git repository
git init

# Create a .gitignore file
cat > .gitignore << EOF
# Hugo default output directory
/public/
/resources/

# Mac files
.DS_Store

# Hugo cache
.hugo_build.lock
EOF

# Make initial commit
git add .
git commit -m "Initial commit: Imported from Micro.blog"

# Now start Claude Code
claude

Step 7: Working with Claude Code

When Claude Code starts, you’ll see a command prompt. Here’s how to use it effectively:

First, give Claude Code context:

This is my 365pixels.xyz photo blog imported from Micro.blog. It uses Hugo and I want to:
1. Make sure it runs locally and matches my live site
2. Experiment with custom CSS changes
3. Learn how Hugo themes work

Can you first analyze the structure and tell me what theme I'm using and where the CSS files are located?

Claude Code will explore your files and report back. It can:

  • Read your config file
  • Check which theme you’re using
  • Locate CSS files
  • Identify any issues

Then ask it to test the site:

Can you help me start the Hugo server and check if there are any errors?

Claude Code will run hugo server for you and diagnose any problems.

Step 8: Fixing Photo URLs (Important!)

Remember, Micro.blog exports don’t include the full photo URLs. You’ll need to fix these. With Claude Code, you can ask:

My posts have photo URLs that are incomplete. They need my domain prepended. 
Can you find all image references in my markdown files and update them 
to include https://365pixels.xyz at the beginning?

What to Do Next

Before I continue with more detailed CSS customization guidance, let’s make sure you get through these initial steps.

Can you:

  1. Run through Steps 1-4 above
  2. Share your config.json contents so I can help convert it
  3. Let me know which blog you want to start with
  4. Tell me if you encounter any issues during installation

Once we have your local site running and matching your live site, we’ll use Claude Code to help you experiment with CSS changes in a really efficient way!

Does this plan work for you? Any questions before you get started?

Excellent! Tiny Theme is developed by Matt Langford and is designed to be as fast as possible while supporting all features of Micro.blog and popular plugins, and is the easiest theme to customize on the platform Anthropic. Let’s get it installed!

Complete Setup Process for Tiny Theme

Here’s your step-by-step guide:

Step 1: Set Up Your Hugo Site with Tiny Theme

# Navigate to your projects directory
cd ~/hugo-blogs

# Create your site if you haven't already
hugo new site cliff538-local
cd cliff538-local

# Download Tiny Theme from GitHub
cd themes
git clone https://github.com/MattSLangford/Tiny-Theme-for-Micro.blog.git tiny
cd ..

Step 2: Add the Hugo Config

Save the hugo.toml file I created earlier (from the artifact above) as hugo.toml in your cliff538-local directory. Then add this line to it:

# Open the file in your text editor and add this line near the top:
theme = "tiny"

OK, you get the idea here. You’ll get your information from MicroBlog and insert it into the proper directories, then start the Hugo Server. If you’re like me, you’ll have 3 or 4 errors, and your site won’t load. Screenshot your errors and give them to Claude. You’ll get detailed instructions on how to fix them.

Once I had my site up and running locally, I opened VS Code and activated Claude Code. This way, you can look directly at your files and Claude Code on one screen. It’s invaluable. I haven’t used VS Code very much at all. Claude will tell you how to set it up, which packages to download, and how to configure the perfect Hugo development environment. If you don’t understand something, ask.

I asked a ton of questions about how Git and GitHub worked within VS Code and what all the red and green bars meant. It was all new to me. If I were working with somebody, they would have fired me and walked out of the room in disgust with all the questions! LOL.

When things are set up, you have a basic understanding of working with VS Code and Claude Code, you can get down to the business of tweaking, learning, and experimenting. You can ask Claude Code what problems do you see with my current custom.css file? It unloaded on me about how inefficient my CSS was and how and why to use variables. I asked a ton more questions, let it give me an example, and then got to work. My CSS is a lean, mean machine now, with a Table of Contents and proper variables, so I can make global changes without searching all over the place.

I WILL UPDATE AS I LEARN MORE