Theming with Github - confused on files

OK - so im familiar with Hugo. Get it -mostly

  • Is there a way for me to work on my theme for my micro blog locally?
  • I really don’t get some aspects like - what files is and isn’t reading… and where its dumping some changes…

In short - I’m trying this: GitHub - willwade/hugo-PaperMod: A fast, clean, responsive Hugo theme.

But my homepage is empty - - and I dare say that’s because I haven’t configured it (at all). But in the theme editing bit I see “Custom Templates” then “Templates for Paper theme” then “Default Templates” - what’s the override policy? Like what takes precedent? Should I just edit my files as best as I can in my GitHub repo OR rely on doing it in…

And I see likes json. Can I just dumbly convert toml or yaml to json?

For starters, someone has already converted that theme for and it’s installable from the plug-in gallery:

But second, yes, you’ll want to go to Design, click on the ... next to your blog name and select Export. One of the options is to Export Theme and Markdown which is pretty dang close to something you can use running Hugo locally.

Yes, themes are just Hugo themes so you can develop them locally. provides some extra stuff so you might have to add things to your local configuration file to simulate the build environment. This config.json file is a good starting point.

Also, make sure your local Hugo version is the same as your blog’s. Take a look at the Design page to see which one you’re running.

How does even work? and Plug-in editing changes are good reads.

See the links above.

That’s up to you, both approaches work. When I develop plug-ins I do most work on my local machine (and push to GitHub) in combination with minor changes and experiments directly on (Often on my test blog to spare my main blog.)

Updated answer based on feedback from Manton below: yes! And that’s a great idea because won’t merge YAML and TOML files.

Aha. I thought there was a plug-in for paper not papermod which has messed more with a few things. Maybe it’s the same thing though. Thanks for the tip.

Perfect. Thanks for the links. I could t find anything when I was looking. Prolly my “man looking” skills… as my wife would say.

Thanks all

Just one clarification on the JSON vs. TOML: We do just use standard Hugo (if an older version) so anything Hugo supports will work, but does some work behind the scenes to “merge” multiple config files together, for example from multiple plug-ins. That only works with JSON, so I recommend always using JSON for config files.

1 Like

So how do people develop their theme with all the files from micro blog? I was guessing GitHub archive tool might be it - but it’s not archiving for me yet ( i imagine it’s on a delay?!). Is there another way people are downloading the files so you can get it in a state for micro blog?

The GitHub archiving only runs once a week, and it doesn’t include all the theme files you need. What you want instead is Posts → “…” → Export, then choose the “Export theme and Markdown”.

That export includes all the files for running Hugo locally. It’s more than you actually need in a theme, though. For a theme, you usually just need the “layouts” folder for the files that are custom for your theme.

Great. Slight criticism - but please don’t take badly! It can be super confusing where all these settings are - that … took me AGES to find - and I kind of stumbled on it when first finding it… and again - I don’t think I would have ever found that :slight_smile:

But thanks! What’s great is that most things are there!