Make working with archetypes on Hugo MUCH easier.
🚀 Disclaimer: I’m the author of the package Hugon being discussed in this post today. All relevant details, disclaimers, and instructions for my package are on: https://github.com/hithismani/hugon
Why I Created Hugon:
Hugo’s biggest (and possibly only) limitation is how it doesn’t let you choose a data source (like a database) for bulk markdown file creation.
About 60% of my time on projects that use Hugo, was spent in converting contenting content into .md files, pushing their assets into the specific static folder, and bug testing to check if things were working as intended.
Quite a monotonous process even when I have an archetype specified.
What Is Hugon?
Hugon is a simple python (3.x) command line script that I made to reduce the manual labour of creating and working with markdown files on Hugo. It’s incredibly simple to use, and communicates directly with your choice of CLI (Hugo CLI, NPM, etc) for file creation.
What Hugon Requires:
- Python 3.x
- Hugo CLI (Tested on 0.59.1)
- Archetype file within your project root/theme archetype folder.
How different is Hugon from just using Hugo CLI?
Hugon does not replace the Hugo CLI, it just adds an additional python layer of data processing before and after pushing the commands to the Hugo CLI.
Creating A Single File With Hugo CLI:
hugo new default/create-this-file.md
Creating A Single File With Hugon (Notice how you don’t have to ‘sluggify’ your file names):
hugon -name "Create this file!" -archetype "default"
Creating A Sequence Of Files With Hugo CLI:
hugo new faq/frequently-asked-questions-1.mdhugo new faq/frequently-asked-questions-2.mdhugo new faq/frequently-asked-questions-3.mdhugo new faq/frequently-asked-questions-4.mdhugo new faq/frequently-asked-questions-5.md
Creating A Sequence Of Files With Hugon (Easy!):
hugon -name "Frequently Asked Questions" -archetype "faq" -sequence "5"
Looking to create Markdown Files from a .CSV data source? No problemo.
This, is where Hugon really shines. I’ve worked really hard to bake in the functionality that lets you create multiple markdown files by just pointing at a CSV. Best part? It also fills up the front matter templates, if the keys and values are specified in your data file.
- Create a ‘data.csv’ file in the root of your hugo project.
- Ensure you’ve specified the required fields as per the syntax mentioned on my repo.
- Run the following command within the root of your project:
hugon -csv yes
- Your files should be created, and the front matter of each field (as long as you’ve specified the keys in the archetype) should be filled!
Need a head start? View this sample(tested) CSV File.
CSV Bonus: Download Files Directly From Your CSV!
If you’re looking to download an image/file into a project folder and assign the values to your markdown, I’ve added that functionality as well. It works 90% of the time, as long as the download link is a direct public link.
You’ve to mention 2 columns within your csv.
- Add a ‘da-’ prefix to the key within the front matter that contains a ‘download anchor link’. Eg: If you’re downloading files for the ‘image’ key, just save the key in your CSV as ‘da-image’.
- Add a ‘path’ column, to let the script know where would you like the above file to be downloaded into.
- Watch the download take place, and also see the values be assigned in your front matter fields!
Some known issues:
- CSV data source only works with YAML front matter.
- CSV fields require that your archetype contain the keys mention within your csv columns.
- As CSV functionality is recursive in nature, it’s recommended that you dry run the script first in another folder.
What do you think? Would you use Hugon within your Hugo workflow? What are your requests and reservations? Let me know!
🚀 Disclaimer: All relevant details, disclaimers, and instructions for my package are on: https://github.com/hithismani/hugon