[HN Gopher] Minimum Viable Hugo
___________________________________________________________________
Minimum Viable Hugo
Author : hiAndrewQuinn
Score : 126 points
Date : 2023-02-27 16:36 UTC (6 hours ago)
(HTM) web link (github.com)
(TXT) w3m dump (github.com)
| obituary_latte wrote:
| Is it just me or is the repo empty (besides readme and license)
| for anyone else?
| sphars wrote:
| I believe it's intentional. The README has all the instructions
| and commands for Hugo to generate the HTML, so you don't need
| anything else.
| college_physics wrote:
| I am using hugo for several years now, so quite thankful for what
| it offers but I am slowly coming to the conclusion that i) you
| need to learn go to get the most out of it and ii) a "semi-
| dynamic" site that uses a simple sqlite backend might be a
| sweeter spot (for my needs) in terms of balancing simplicity,
| features and practicality.
|
| I did't not find yet a replacement though. One reason is that I
| would love to continue having markdown as the main format for
| creating content but somehow that is orthogonal to having that
| markup stored in a db backend instead of the filesystem.
| schemescape wrote:
| Out of curiosity, what do you need a database for? Could you
| just regenerate your static site when the database updates,
| thus allowing you to keep serving static HTML?
| college_physics wrote:
| its various little annoyances: rebuilding a site can be
| tricky when you are on the move (say with a mobile device)
| and just want to add/edit a bit of content. or to give
| editing access to non-technical people. or the search
| capabilities that are more powerful with a db etc.
|
| it feels that between the spartan austerity of an SSG and an
| overengineered full-blown database-backed CMS there might be
| some intermediate option. or maybe not :-)
| hiAndrewQuinn wrote:
| Oh, those are interesting issues. I've had a similar
| hankering but for me it's 99% just because I want a nice
| comments system. I've toyed with the idea of taking a
| project like Issi and rolling up a SaaS based on it which
| basically provides an SQLite comments system. Paste one
| line of JavaScript into the page, and boom.
| _def wrote:
| I recently started a blog again with Hugo and I like how you can
| easily use a github workflow to build and deploy it. This way you
| can even just use github in your browser to publish.
| andrenotgiant wrote:
| This is great, but for different reasons than the README implies.
|
| > "Hugo sounds great! Let me try it out!" > "Okay, I made a new
| theme and a page in content/!!" > "Running hugo server -D now!!!
| ... Where is it!!!!"
|
| It's not Hugo itself that is complicated, it's all the other JS
| and CSS dependencies that other getting started repos tend to
| layer in.
| Arch-TK wrote:
| It took me an afternoon to glue together my own DIY SSG with all
| the features I wanted. I did that after a previous SSG didn't do
| what I wanted and I didn't know how to fix it since I don't know
| ruby.
|
| An SSG especially is such a low-risk project.
|
| Probably the most carefree code you could possibly write.
| thenoblesunfish wrote:
| I tried to make a minimal Hugo site just a few days ago. There is
| a quickstart on their website, which I followed, and it seemed to
| work as expected. Did I get lucky? Am I in for a world of pain as
| I try to go beyond the extremely minimal site I have now?
| RazorX wrote:
| Since we're sharing, here is my personal site in Hugo without
| using any starter templates or themes.
|
| https://github.com/evansosenko/evansosenko.com
|
| Going back to basics and having zero external dependencies is
| quite enjoyable. Understanding how Hugo templates, themes, and
| content all work together was more complicated than I originally
| expected, but they have build a good system. Hopefully this helps
| anyone looking to get started.
| hiAndrewQuinn wrote:
| This is an excellent little website, I'm I work with a few guys
| who have been playing CS for ages and I bet they'll get a real
| kick out of Pure skill next time I see them at the office.
| BeetleB wrote:
| Or just use Pelican.
| marcosdumay wrote:
| I started using Zola (Hugo's clone in Rust) when Pelican
| stopped being something I was able to use.
|
| Is it still maintained? Because all I got were
| incompatibilities with the newer Python versions.
| BeetleB wrote:
| I never had issues with Python versions - I occasionally had
| issues with newer _Pelican_ versions (backward
| incompatibilities). It continues to work for me - been using
| it for over a decade.
| kissgyorgy wrote:
| This is exactly why I gave up on Hugo and LOVE mkdocs-material.
| It has such a simple setup and such a good out of the box
| experience that you can start with it literally in minutes. I was
| so surprised that the second command is serve and you actually
| get a working site, which you can iterate and fine-tune later.
| pydry wrote:
| I had the exact same experience. Everything that sucked about
| hugo that I discovered only after a week of trying to do
| something simple with it was fixed with mkdocs.
|
| It made me appreciate that static site generators look easy up
| front but are actually a huge amount of work to do right.
| IshKebab wrote:
| I tried all these static site generators for a blog, but they're
| all too complicated and too much faff for that.
|
| In the end I went with Markdown, Pandoc and a Makefile. Works
| well & I completely understand it.
| Daegalus wrote:
| Ive used mkdocs at work, and Hugo for my personal blogs and sites
| (I recently created https://cyphersrd.quest using Hugo).
|
| I will say at first its always takes a second to remember how all
| the folders nad files interplay, especially the `_index.md` file,
| but after that its super clean.
|
| I tend to find a theme that I like that is MIT or ISC licensed,
| and then modify it from there to my liking. Like for the site I
| linked, I started with `hugo-book` but didn't like some of the
| coloring, so I transplanted a good chunk of Water.css into it and
| it looks good now.
| baby wrote:
| Every time I use hugo I feel like it's way too complicated for
| what it offers
| Daegalus wrote:
| I think thats mostly because the default setup and
| boilerplate make it seem that way.
|
| You only really need a `config.{toml,yaml,json}` a `content`
| folder and a 1 file theme like the one in the article of this
| thread.
|
| Everything else is just extras.
|
| I will admit I am currently for fun working on my own static
| site generator, and its slowly getting pretty complex just
| implementing the basics. Which gives me a new appreciation
| for what Hugo is doing, and many other site generators.
|
| The more generic and multi-featured you make it, the
| complexity just increases.
| baby wrote:
| I think my gripes are mostly in how the folder is
| organized. It's just confusing.
| umvi wrote:
| If all you care about is maintaining a simple blog or personal
| site I recommend just writing your own static site generator.
| Seriously, it takes probably an hour of work and ~100 lines of
| code or less and you can customize it however you want.
|
| Here's the static site generator I wrote for my site
| (https://bryanpg.com):
| https://gist.github.com/RPGillespie6/b133854b8ebf5a983cf32c2...
|
| I might tweak it to auto-generate the RSS xml as well at some
| point, that'll be another 10-20 lines tops.
| asb wrote:
| I've also found that a custom-written generator is surprisingly
| productive. My own attempt is at
| https://github.com/muxup/muxup-site/blob/main/build.py and I
| wrote up a few notes on it here https://muxup.com/2022q3/muxup-
| implementation-notes#site-gen....
| yboris wrote:
| I've been _loving_ Hugo. I built https://utilitarianism.net/ with
| it https://github.com/whyboris/utilitarianism.net
|
| For my personal and dev sites I used to use Gatsby, but migrated
| to _Hugo_ just this month: https://github.com/whyboris/homepage &
| https://github.com/whyboris/homepage-dev
|
| I'm pleased with how little boilerplate Hugo actually needs. My
| personal websites have so few files to maintain / worry over :)
| garyrob wrote:
| I really like the look of this. I don't see a license statement
| on your github; I'd be tempted to use it if you want people to
| be able to!
| yboris wrote:
| I'm a little unsure what license I can slap on the
| repository, since even though I've written all the code, the
| content (text) was written by 3 philosophy professors & the
| guest essays were by other authors.
|
| While they are currently working on making this an _Open
| Access Textbook_ I 'm unsure what license I am allowed to
| attach to it. Perhaps when they coordinate with their
| publisher they will know better - I've been meaning to ask.
|
| Happy to hear suggestions :)
| rsolva wrote:
| License the code to AGPL and the articles to Creative
| Commons?
| hiAndrewQuinn wrote:
| Classy and direct, I like it. Serifed fonts always bring me
| back to the days where I would sit in the old mahogany chairs
| of my university library and just read whatever came to mind.
|
| If I had more free time I would love to build a similar website
| for Nicholas Rescher's approach to process philosophy, that's
| my particular hobby horse, Rescher and maybe a little Charles
| Hartshorne for flavor.
| simplyinfinity wrote:
| I just started using Hugo, but boy, are the docs bad... and I
| mean REAL BAD. It took me an HOUR to setup a theme. Then another
| 30 mins to realize I've set up the theme the wrong way, using a
| git submodule, instead of a go module. Then installation of the
| go module itself took another 30 mins of debugging, because
| nothing was working out of the box. And nowhere in the
| documentations are things explained for novices. The docs are
| written in a way that assumes you already know Hugo's ins and
| outs. uh... At this point, I would've been better off with a
| WordPress install that takes 5 minutes to do manually.
| crecker wrote:
| Bep is rewriting the docs because are really incomprehensible.
| I do agree with you.
| mhb wrote:
| Is there a good alternative? Would be nice if it is in Python.
| Maybe Pelican, Nikola, Hyde?
| thunky wrote:
| Cobalt is nice if you want simple: https://cobalt-
| org.github.io/
|
| It's not python, but it is a single binary to be off and
| running.
| huimang wrote:
| Hugo is really nice once you spend some time learning the
| templating system and how the variables get set up. It does
| have a learning curve at first, but I don't find any of the
| alternatives to be as compelling as hugo once you're up and
| running.
| simplyinfinity wrote:
| WordPress. I hate its guts, but my god does it just work. Or
| I'm just going to give up and use squarespace or webflow, or
| something like that. I've got a full time job, managing this
| is not worth the mental energy it takes to learn all it's
| quirks.
| richardw wrote:
| Hugo is great but the learning curve is madness. I've used it
| twice with a couple years in-between, and succeeded, but it's
| very annoying to have 1-3 hours of failure before you see
| anything useful.
|
| Add theme, follow tutorial, somehow blows up, need to figure
| out exactly where to put what, round and round then find a
| tiny wedge that works and just expand that until I have
| something that does what I need. But once it's set up it's
| really fast and you can iterate on your pages very nicely. No
| "tons of imports" that I needed with Jekyll.
| antihero wrote:
| Astro is pretty awesome if you're ok with TS/JS.
| deepspace wrote:
| Lektor is Python based and Just Works, but it is far off the
| beaten track... https://www.getlektor.com/
| superkuh wrote:
| You can just write HTML too. It is much simpler, easier to
| maintain, and more secure (using a real webserver). Make .html
| files, open them in a text editor, type in the HTML. Here, I'll
| make an example like the minimum viable hugo.
|
| $ sudo apt get install nginx
|
| <html><head><title>Lorem ipsum dolor sit
| amet</title></head><body><h1>Lorem ipsum dolor sit
| amet</h1></body></html>
|
| And now save it as index.html in the www directory that
| installing nginx creates. Check it out at http://127.0.0.1/ . Go
| to your router and forward port 80 to the IP address of the
| computer running nginx to make it public.
| ajorgensen wrote:
| I think the intent of OP was to help people get setup with Hugo
| so your comment is pretty off topic. Yes you _could_ set up
| php, elm, a full lamp stack, rails, heck you dont even need
| nginx to serve a static .html file but none of that will help
| someone get setup with Hugo if that 's what they want to use
| for static site generation.
| hk1337 wrote:
| Blasphemy! I must overcomplicate it so the build takes a
| significant amount of time in the CI workflow. /s
| doodlesdev wrote:
| Hugo builds and Jekyll builds are basically instantaneous
| even for really large websites. I mean less than one second.
| Like 30ms. You don't even see it happen. Migrating your
| manually crafted HTML pages to something other than NGINX or
| changing the theme or website is going to be such a pain in
| the ass you're going to wish you never thought of this
| "minimalist" way of doing it. If you look at the website of
| the guy above at superkuh.com it looks like shit (subjective,
| of course), doesn't even have a TLS certificate and above all
| would be an extreme pain to change the layout, design,
| deployment, etc. I don't even know what to say about this
| chart in his last post at
| http://erewhon.superkuh.com/pictures/blog-posts-vs-blog-
| post... although I must admit it's really funny.
| nicoburns wrote:
| Hugo also typically uses a real webserver like nginx... it just
| gives you some niceties like templating and SASS on top of
| that.
| FredPret wrote:
| nginx is magic
| yamtaddle wrote:
| Use SSI for header/footer/menu segments and write about 5 lines
| of bash and you've got all the site generator you need, too,
| and you can run your "generator" on basically any unixy machine
| without installing anything.
|
| I find writing raw HTML for basic documents to be very fast and
| easy with a modern editor with hinting/autocomplete. Not any
| slower than Markdown, really.
| projektfu wrote:
| Doesn't SSI kind of make the site not static anymore?
| ufo wrote:
| What is SSI?
| yamtaddle wrote:
| Ancient, arcane technology:
|
| https://en.wikipedia.org/wiki/Server_Side_Includes
| mxuribe wrote:
| As an oldie on the web, i would state that while it might
| be "ancient, arcane", but it was amazingly awesome at the
| time....and some still leverage this neat technology to
| great benefit. ;-)
| lelanthran wrote:
| I wrote a bash script (https://gist.github.com/lelanthran/263
| 4fc2508c93a437ba5ca511...) that lets me very simply add new
| posts to my blog.
|
| For my actual blog I reversed the order that the first are
| processed. Looks okay, I think, just short on functionality
| (no I Tractivity).
|
| https://www.lelanthran.com ... feedback welcome.
| ajkjk wrote:
| Ignoring your sarcasm: nobody wants that, for good reason.
| elliotec wrote:
| What do you think is the good reason?
| marcosdumay wrote:
| HTML files can't reuse anything, HTML is a pretty bad
| verbose language, it is hard to keep indexes and links up
| to date when you change your site, and well, a lot of other
| reasons that I didn't think about because I gave-up on that
| in the 90's.
| ajkjk wrote:
| because writing HTML manually is fucking terrible compared
| to authoring markdown. We (i.e. everybody) are trying to
| improve things because they are bad.
| superkuh wrote:
| I'm not being sarcastic. It is what I've done for 20+ years
| (although I only switched from thttpd to nginx in ~2010). The
| linked article does not really teach you how to use hugo. It
| just shows how to generate a single page, and there are far
| better ways to do that.
|
| And like others have said, nginx comes with server side
| includes built in. It's the perfect amount of dynamic
| templating power with the minimal attack surface. Before
| anyone jumps in with, "but I can deploy (or other cargo cult
| terms) my website to a CDN if I use Hugo for templating." I
| question the utility and complexity of bringing in a CDN in
| this, minimum viable context or any personal website context.
| count wrote:
| I can deploy [sic] my website to a static file serving
| service for virtually free (e.g. S3, GitHub Pages, Azure
| Static Sites, etc.) without having a CDN and without having
| to worry about renewing SSL certs, managing a full linux
| instance or container, patching the web server when stuff
| gets hacked, doing maintenance, etc.
|
| There's a ton of value in 'just static pages', and if you
| do more than 1, not writing your own HTML is pretty great.
| hiAndrewQuinn wrote:
| Moi, OP here. Thanks for stopping by this post and sharing your
| thoughts.
|
| I have nothing to sell, but I am looking for mentors. Let me know
| if you have knowledge worth passing down.
| dfindley wrote:
| I also experienced this when trying out Hugo. I think the issue
| is when you go into it with the expectation of building a simple
| website that you build from scratch, rather than a pre-built
| theme. Personally, I found that Zola was much simpler for
| starting from scratch.
| mmsimanga wrote:
| I tried both and ended up with WordPress of all things. I
| really don't blog and after a year without making a post I
| couldn't figure out my own Hugo site. I had also changed
| computers and my site wouldn't build anymore. I think Hugo is
| fantastic but probably best for regularly bloggers.
| hiAndrewQuinn wrote:
| WP gets a bad rap honestly. I like what the folks over at
| WPEngine are doing a lot.
| amai wrote:
| Hugo is not made for minimum viable blogs. Its advantage in
| performance only becomes important for bigger websites or blogs
| with thousands of articles. But especially for bigger websites it
| should be possible to auto-generate a good archive. However the
| developers of Hugo stubbornly refuse to fix this very important 8
| year old issue: https://github.com/gohugoio/hugo/issues/448 That
| is quite unfortunate, because it makes Hugo "the worlds fastest
| framework for building huge websites without a useful archive".
| _benj wrote:
| Thanks for this! One of my frustration with tools nowadays is
| that they aim to be so "user friendly" that actually make things
| complicated and thus understanding how something works, which
| allows one to be more productive with a tool, is hidden under
| tons of layers of complexity and simplistic "getting started"
| that can indeed make an amazing looking website with 1 command,
| but from there on, trying to figure out _how_ that amazing
| website works and how can I adapt it for my need is a rough
| journey!
| svat wrote:
| Exactly. I ran into this when trying to set up Hugo, and wrote
| for myself a notes page with the following:
|
| # What is Hugo?
|
| `hugo` is a program that takes some .md files (ideally,
| conforming to a certain directory structure) and creates some
| .html and .xml files (conforming to another directory
| structure).
|
| This is the minimal command: # Create input
| directory structure to silence warnings mkdir content
| layouts{,/tags,/categories} touch layouts/home.html
| layouts/{categories,tags}/list.html # Run hugo: creates
| public/ and resources/ hugo
|
| ...and building from there.
|
| If you read the Hugo documentation, it talks about all kinds of
| stuff but doesn't explain anything from the bottom up:
| apparently the usual way is to start with a pre-existing theme
| or site as template and edit it, but that's not explained
| anywhere either. After you eventually learn exactly what Hugo
| is, it becomes ok to use.
| BossingAround wrote:
| That's not Hugo's problem, that's a problem with Hugo's docs.
| Something that pretty much all projects, and most big
| companies, struggle with.
|
| There's very few documentation experts out there. Those who
| write the docs are either devs who write broken English, or
| English majors who don't understand a lot of the tech stack.
| In either case, they usually miss the target persona, and
| what are the reader's needs.
|
| Writing docs is hard :/.
| jerf wrote:
| I'm not a hugo expert, but the two main things that I
| needed were:
|
| 1. An understanding of what variables are available, and
| where. Hugo nicely collects a lot of useful info but it is
| difficult to know what it all is and where it is.
| https://gohugo.io/variables/page/ is a good start but it is
| difficult to know how these are populated.
|
| 2. Hugo is implemented in Go, so under the hood everything
| is strongly typed. But the Hugo documentation throws that
| all away and presents the dynamically-typed interface that
| Go's html templates provides. The problem is, figuring out
| what anything can do is made very difficult by that. So,
| ok, I have a .Content or a .Data for this page... but what
| _is_ that? Is it a string? Is it an object? If so, what can
| I do with it? I have to experiment to find out, or grep
| over a couple of templates to figure it out.
|
| Honestly if I had to make just one suggestion to the Hugo
| docs team, it would be, strongly type your entire
| documentation suite. Tell me what the type of everything
| is, and the resulting methods/functions I can use it with.
| (If it's an interface, fine, I don't mean all the maximally
| static types necessarily.) That wouldn't fix everything,
| but it would fix the frustration I experience of visiting
| https://gohugo.io/variables/page/ and still wondering what
| any of that stuff actually _is_.
| MengerSponge wrote:
| Hot take: The docs are an important part of the product. If
| you notice that the docs are bad, the product is bad.
|
| Docs are hard and thankless, but -\\_(tsu)_/- them's the
| breaks.
| twodave wrote:
| I'd even take this hot take up a few more degrees and say
| the docs quality not only represents the product quality,
| but also validates it. In other words, you can't know
| whether your product has a chance of being good unless
| you're _able_ to write good docs for it.
| mxuribe wrote:
| > ...If you notice that the docs are bad, the product is
| bad...
|
| This right here is so correct! Given the option of 2 (or
| more) products/services, in my mind, the one with the
| best documentaiton wins...because it usually means it is
| the option that is more easy to implement...or at least i
| can research how to make it the esier option to
| implement, etc. Good docs for the win!
| speed_spread wrote:
| Even hotter take, you can have a well documented shit
| product and it'll be better in a lot of cases than a
| quality product with no docs.
| twodave wrote:
| And if your project is open source and the docs are clear
| and show good vision, you might even attract folks to
| come fix your broke-ass code :D
| WesternWind wrote:
| This is true. Docs, re not necessarily considered
| important features of the product itself but they make a
| huge difference.
|
| Other things that I pay attention to are built-in
| integrations with other tools, the ability to import and
| export data, familiarity to users, similarity to existing
| tools, tutorials that leave users confident, and
| documentation with examples of use cases are all similar
| factors.
| leetrout wrote:
| I plan to record a small (4?) series of videos about starting
| with Hugo from scratch. Would love to hear any pain points
| you specifically think need to be addressed.
| projektfu wrote:
| Being a video is a pain point for me. I much prefer a
| useful text tutorial with code I can copy, etc. But I don't
| want to be a choosy beggar so you do you :)
| schemescape wrote:
| Yes, I also found it difficult to understand how Hugo worked
| internally.
|
| If you're ok with NPM, Metalsmith is a trivially simple static
| site generator, where you just write JavaScript code to
| customize it (and of course you can plug in templating tools).
| If you don't like NPM, but like JS/TS, I started a port/rewrite
| of Metalsmith for Deno, I can share if anyone's interested.
| roblh wrote:
| Metalsmith is cool! I hadn't heard of it til now but it looks
| sweet.
|
| I actually made something similar except mine isn't designed
| for static sites specifically. It just takes markdown, parses
| it into HTML (with code highlighting of course) and stores
| the html and frontmatter in an in memory sqlite database that
| gets rebuilt each time you save. Not the most efficient
| choice, but it makes plugging it into any front end framework
| like nuxt or next or svelte really easy, particularly if they
| have server side rendering. I guess it's almost halfway
| between this and PicoCMS. And you get full text search.
| cxr wrote:
| It's md2blog for anyone who is interested
| <https://jaredkrinke.github.io/md2blog/>
|
| The Show HN discussion from 2021:
| <https://news.ycombinator.com/item?id=29382091>
| IceHegel wrote:
| Unless a tool is so ubiquitous and widely used that it becomes
| a new standard (like JavaScript), over abstraction is a very
| real problem.
| spaniard89277 wrote:
| PicoCMS is the real friendly CMS for serving static files.
|
| 1. Upload PicoCMS to the least expensive LAMP shared hosting,
| by FTP.
|
| 2. Upload markdown files to /content.
|
| Viola.
|
| You may also want to download themes or make your own with Twig
| templating system.
|
| IMO if you're a software developer and you can't figure it out
| in 10 minutes, it isn't really that friendly.
| IanCal wrote:
| Hmm, that sounds good but when I go to the homepage it gives
| me buttons for learn more and download, neither of which work
| and the focus is all messed up. I know it's _probably_ not
| the CMS part that 's broken but if the website for a website
| builder doesn't work it doesn't inspire confidence.
| spookie wrote:
| Lovely. Gotta say, it's great that Hugo makes it easy for non
| devs to get going. But, if you wanna hack something together, the
| clay becomes too difficult to mold.
|
| Glad this sorted that out.
| qudat wrote:
| Yep, it's one reason why I wrote https://prose.sh -- a
| middleground between self-hosting a hugo site and copying
| markdown files to a managed blog site.
| freeplay wrote:
| That actually looks really cool. I particularly like your
| signup process.
| powersnail wrote:
| Love Hugo. Been using Hugo for quite some time. But I agree with
| the author that there is a "Running hugo server -D now!!! ...
| Where is it!!!!" problem when following the tutorial.
|
| Hugo has many "magic" based on names, "index.md" vs "_index.md",
| template look up hierarchy, global variables and functions
| (sometimes capitalized, sometimes not; some are behind a context,
| some are not), etc. It's hard to tell what name is required, what
| is configurable, and what is just accident, until you've delved
| into the detailed documentation. And to make the matter more
| complicated, themes sometimes use name magics, too.
|
| I also hope that Hugo can just allow piping stuff through
| external programs in its templates. Right now, Hugo provides a
| pretty large number of APIs on resource transformation, regexes,
| string manipulation, and hell, you can even download stuff in
| templates. But to be honest, it's way easier to just write a
| shell script.
|
| If I were to make my own static site generator, I think I'd
| probably opt for less flexibility, and simpler logic, especially
| with regard to what file ends up where. Let the generator handle
| the basic MD->HTML transformation, the skeleton of the site,
| producing feeds and metadata. And let external programs handle
| everything else.
___________________________________________________________________
(page generated 2023-02-27 23:01 UTC)