How to start a blog using Hugo (opens in new tab)

Similar issues from my side. Cryptic documentation, bad dissorganized forum and configuration,... I love the hugo idea but to find one detail you will get into chaos of strange wording and noise. I am using it but I try to configure as small amount as possible as I always get into some undesired behaviour. It seems like it was from begining build with idea and then continued by patch over patch over patch. Cant recomend it either.

My main issue was how hard it was to do some simple things (or I didn't understand the documentation). I use Lektor for my site and it's been very easy to set up and use, I recommend it.

I like to blog to provide an online presence, but blogging for me is not that important. I cannot justify spending time in configuring and troubleshooting static site generators. I like WordPress because you can get it to work within minutes and all I have to worry about is writing content and coming up with ideas. I have a self-hosted WP instance, which conducts regular backups, and uses Let's Encrypt and auto renews monthly which I check on every 2 or 3 months to ensure everything is running correctly.

From a cloud perspective, it's easier (by a tiny bit of work) to point a subdomain to a service over pointing a folder.

E.g. blog.example.com pointing to a static website while project.example.com points to a server.

If you want both to be under the same domain and use a CDN for only one of them, you still have to configure the pass through of all others... But if it's only one subdomain, CloudFront no longer needs to know about non-Cloudfront endpoints.

I run my Hugo site on S3+CloudFront for a be penny a month (if that), despite also having a $5/month server... It protects my site from going down if one if the 5 WP sites I lazily host for friends gets directly attacked and someone pops a shell + container break out.

It's not a matter of one being objectively better than the other but which suits your needs.

The basic distinction, from a purely SEO perspective, is that blog.domain.com will be treated as its own entity whereas domain.com/blog will be treated as part of the main domain.com entity.

The question you have to ask yourself is whether you want to bolster the "value" of your main domain or if you want your blog to be an asset in its own right.

There is no right or wrong answer — there is simply what's best for your situation.

As he said, a sub domain is often considered a separate domain when it comes to SEO. His other arguments about naming seems rather hand-wavy, though.

Security-wise, a subdomain can also be a different origin. Which is often positive, so a flaw in your blogging software doesn't allow someone to extract cookies or so from the main site.

I feel like x.example.com is preferred over example.com/x because it is simpler to move the files around (when you want the same app/bundle of static files to be y.example.com). Browsers by default will make <a href="/foo/bar.html"> into x.example.com/foo/bar.html when served from x.example.com, but it won't make it into example.com/x/foo/bar.html when served from example.com/x/; something else has to make sure the URLs are correct. The options available to make links work are to generate correct links in the first place (CGI back in the day provided enough information to make this possible, but modern reverse proxies have no way to convey this), never use absolute paths in links (restrictive), or to have some machinery intercept the document, parse the HTML, and rewrite links (super flaky). If you are always going to be at exmaple.com/x/ and never need to change the base URL, you can make it work. If you are making something reusable that people download and self-host, you will pull all your hair out making the /x/ case work well. Therefore, people tend to prefer the subdomain approach. It's just easier, because of an implicit base URL assumed by browsers (and even things like grpc clients). When you try to override defaults, it's like rolling a stone up an infinitely long hill. This is that, I think.

For your blog, it doesn't matter. You can hard-code the entire URL in every link and it will probably never go wrong. Applications are harder. Applications that various people are going to self-host are hardest.

What is the business justification for creating a blog on your website?

In general I would think that it is to create contents and SEO, in which case I believe that it is better to host it under the website's domain. On the other hand you may be targeting a different audience from your main site/product. For example Uber, Netflix at al have "engineering blogs" these days, which clearly have no relation to their product but perhaps rather aimed at being a recruitment tool. In such case you might want to use different domains (which incidentally is what both Uber and Netflix do).

I see people commenting on the technical aspects but the differences are minor and the business goals should be driving the decision.

If you host PHP software like phpBB on a VPS on forum.example.com and have your static website hosted on Netlify under blog.example.com, it's easier to do this with subdomains.

Of course, you can have a load balancer under example.com that acts as a reverse proxy for your forum unter example.com/forum, but the easier setup with different languages/software/servers is to use subdomains imho.

I have some reasons to prefer domain.com/thing now :

- You don't have to add and manage subdomain

- You don't have to stop and restart the reverse-proxy of your VPS

- Only one cert to deal with (I use traefik w/ automatic LE renewal but that implied more things to set up on the chain)

But I still use blog.domain.com because I find it prettier. And when I need to type it in the URL bar it's just $service<tab>.domain<tab><enter>.

Now the SEO crowd has other requirements that make their choice more valid than my own (one user, one set of idiosyncrasies).

blog.domain.com is much better from a security perspective since logged-in session cookies from your main domain won't be sent in blog requests (different origin).

That provides protection for if someone manages to get a malicious script into your blog, they can't start making authenticated requests (since it isn't the same origin).

I'm running my blog (https://muffinman.io) on Jekyll and GitHub pages, and I've run into the same issues.

For search I generate a JSON array, with the name and the url to each post. Then I just client side javascript to search them. It adds a small traffic overhead, but users said they really like the search - it is instant and uses fuzzy matching algorithm.

Here is the code I use to generate the array: https://github.com/Stanko/Stanko.github.io/blob/master/_incl...

For comments I use staticman (https://staticman.net/), and it is brilliant. Instead of having a 3rd party comment system, it will issue a pull request to your repo. You can set it to automatically merge PRs or to merge them manually (and moderate them).

The only problem is that because of changes to the GitHub API quotas, their public instance gets overloaded. But you can easily setup your own instance. I use heroku, and their free tier is more than enough for my usecase (I get more than 100k users a year).

I even wrote a short post how to set it up on heroku: https://muffinman.io/running-staticman-on-heroku/

Hope that helps, happy hacking!

I use commento[1] on my site, running on my own server so no third party has access. I do not get many comments though so I don't know how it handles higher load.

[1] https://gitlab.com/commento/commento

Well, as long as Hugo remains a static site generator, it won't be able to support these features "out of the box". E.g. comments are simply not possible just with HTML + JS, so you'll either have to integrate a third-party service (Disqus, Staticman etc.), or move away from the "static site" concept.

Google custom search?

I typically write about things I want to tell people about. Maybe we had an interesting lunchtime conversation, something unusual came up, I'll read about it more and write a post.

Or maybe there's a decision I'm making: I'll write up how I'm thinking about it, where I am so far, and publish that. Often I get good feedback on these posts that makes me think about the problem differently.

I try to notice when I get ideas that would make good posts and write them down. Then, in the evening, I'll sit down, look over the ideas, and see if there's anything I feel like writing about.

This might be helpful. https://www.perell.com/blog/my-writing-syllabus

Follow David Perell for writing inspiration. https://twitter.com/david_perell/status/1213894632943296516

Start journaling. Just keep a daily log of stuff you do, that you either think is interesting or that you want to reference later. Focus on getting the key points out succintly, writing as you go and then (quickly) editing once you have the problem all worked out. If you do this regularly, you'll get better at producing short and interesting summaries which are great blog topics.

[in my opinion] Don't write to be read. Write for you, write because you enjoy the process and the exposition helps you process and crystallise a concept. Write because you are interested and engaged.

My most popular blog post was 'deWiTTERS game loop', which ended up with plenty of links referring to it, including the "game programming patterns" book.

I wrote it because there was nothing else like it.

So if you're researching something, but have to combine various sources and figuring out stuff, because there is no easy blog post, write that easy blog post yourself.

Write about yourself and what you know, its probably the most interesting thing you could write about anyway.

I've been preparing articles for my future blog about my interests and struggles (security, beer, books, mental health). Weird mix but theres no doubt that its more interesting than me trying to force myself to write on one of them consistently

I used to feel such pressure as well because mostly of the current zeigeist that your blog is your platform to market yourself. This adds an enormous pressure for doing quality and interesting post as if you're attempting to publish a paper into a prestigious journal. I'm done with that. These days the main audience for my blog is myself. I like writing and I'm equally prone to write about the coffee I just had and about some clever coding thing.

We all have stories to tell. Treat your blog as a public journal. A place to organize thoughts, share ideas, it doesn't need to be longform in deep stuff. And if you end up doing longform in deep articles, just break them into a series.

What is the purpose of your blog? It heavy depends on this and your target audience.

If you do want to share things that usually end up a long essay, try to make it shorter and easy to understand. It means cut off ideas. Select only general knowledge, so that everyone can understand.

If you follow Medium.com, that’s what happens. Most of popular posts share basic knowledge. And posts with more technical details (some of them are great), often don’t get popular since less people want and understand it.

Also you can start writing random things and share it to learn what interest the audience

I disagree. I think you have something to write about. Your comment shows this perfectly. And I mean that in all seriousness.

Just remember that when you write something, you're making an implicit promise to the reader: I will learn something new by reading your blog.

Keep them bite-sized. If it's more than 1-2 pages, probably worth turning into a series.

I'm no expert, my recently minted blog has one post (book review). I came to the conclusion writing is more of an exercise for myself than a venture to produce content for others. Maybe you should first think about why you feel the need to write and who your writing is for?

I'm not one to give advice, since I don't have a blog of my own. But I'd assume you want to look for an area where (a) you have a natural interest, and (b) for which there aren't a lot of existing resources online.

What's worked for me:

Find an interesting question.

Investigate it.

See where that leads.

In particular:

- What are the foundations of that question?

- What are the implicit assumptions or beliefs? Are those valid?

- What references or sources are frequently cited or quoted? Are those valid?

- What questions, concepts, or sources are studiously ignored or deprecated? Why? Are those valid or invalid?

- What are the dimensions / what is the internal structure of the question? What are its elements, dynamics, and/or relationships? Where do those lead?

- What are the issues encountered in trying to realise solutions, mitigations, or models of the problem? Working in idea-space is one thing, working in instance-space quite another. ("In theory, the same, in practice, different.")

- What new questions emerge? Rinse, wash, repeat.

My problem isn't that I don't have enough to write about, it's that I've far too much I'd like to address, and am looking for a structure and system that fits this.

If you're not at this stage, simply writing, regularly, is good practice. Things you have to say may not seem to be meaningful, and perhaps never will be. More likely though you'll discover a through-thread in the problems and approaches to those problems you're drawn to, though it may take years or decades to discover this.

Writing is a great way of documenting your sources, discoveries, thought process, and evolution of understanding or approaches. It took me several decades before I'd read my past writing without constantly crigning. I still frequently revise or correct older essays (even years old), and HN's very limited edit window is a constant frustration (as are Mastodon and Diaspora's complete lack of re-editability). Your own git-managed blog provides both for editability and a history of those edits.

I've found the process of exploring writing and research methods (tending strongly toward cross-referenced systems: index cards, Zettelkasten, POIC, Wikis) to be fascinating in its own right. Often to the exclusion of writing itself ;-)

Capabilities of a particular platform also matter. If you're writing-as-marketing (a frequent mode), there's one set of tools which may matter, generally fairly well addressed. If you're writing-as-dialectic, exploring ideas or seeking a better understanding of truth, there are others, less-well supported. I find that comprehensive search, thematic organisation (a very good tagging system), and, if feedback is supported (comments, etc.), an exceptionally effective, efficient, and low-cognitive-overhead moderation system matters a lot, as well as the ability to structure posts sufficiently to the needs of expression. A reasonably robust semantic structure (emphasis, lists, sections, tables, figure/images, footnotes, possibly equations) can really matter, and many solutions support this poorly (or require much wrestling).

Content-appropriate themes and styling also matter, with a narrow band between "not enough" and "too much". Again, many solutions support this poorly.

Finally, there's the ability to move your content elsewhere, when (not if) your current platform becomes inadequate or inappropriate, for whatever reason. Something I've come to discover is inevitable.

Another interesting discovery has been writing on microblogging sites. My preference is Mastodon, though Twitter is similar. I'd realised that Mastodon's default 500 character toot length is roughly the same as an index card, which means I can post in threads of roughly index-card-sized chunks. I know this is somewhat annoying for readers, but as a writer, the immediacy of feedback, at roughly paragraph-level granularity, to elements of a longer essay, is invaluable. There's also the notion of publishing in chunks, and committing yourself to a direction publicly, whilst still composing. Several of my longer "tootstorms" really just started as an aside or observation and grew on me.

A key distinction between writing and conversation is that in a conversation, you get immediate feedback. In writing, you commit yourself to a much longer exposition without having a good idea how your audience will respond. (Even speechwriting or presentations are like this, though in delivery you can adapt to audience response.) Microblogging has at least the possibility of bringing writing closer to the conversational mode, which is interesting.

I am also on the same boat. I am on my 3rd blog and after writing about 10 or so posts I am not finding anything to write about.

It really depends if you want them connected or not.

In the Hugo example, completely agree. But sometimes it can make sense:

Example.com vs members.example.com vs login.example.com

Example.com can be a static website, while login attempts go to the login domain (which also helps for auth/postback config), and members might be the dynamic content that is viewable once logged in. separates infrastructure in an easy way that has no real impact on SEO

the reasoning is the following:

>Note on subdomains: every subdomain, to Google, is a different website. So if your domain is flaviocopes.com, and you create your blog in blog.flaviocopes.com, then that’s a completely new website to Google, and it will have its own ranking separate from the main domain.

So from a SEO perspective it might make sense, if you're running a small blog and traffic is one of your main goals.

It’s a shame there we are so whipped to .com

I think this is just what I was looking for, thanks!

I set up a small charity's site I maintain to use GitHub pages and Jekyll. The in-browser editor for markdown is good enough for the non-technical users, and GitHub pages takes care of rebuilding the site. The revision history is handy in case someone does something weird and we need to undo it.

I believe that GitLab pages offers something similar that also supports Hugo, but I opted to use GitHub+Jekyll as I personally find it significantly easier to custom-build a website than with Hugo (I really struggled with on some basic stuff, e.g. I had a lot of blank pages at dir roots (e.g. /something/goes/here would have blank pages at something/ and something/goes/ etc)). Hugo feels over-complicated to me.

Tina CMS [1] is something I bumped into (haven't tried since I'm not enamored by React, or rather, JavaScript based sites for blogs). It provides an editor right on your site, and works with static site generators like Gatsby and NextJS.

[1]: https://tinacms.org/

Not really in a separate access-restricted area of the site, but I use https://forestry.io/ to update my (netlify-hosted, github-backed) blog when I don't have access to my own machine (or correct a typo from my phone).

Netlify CMS has been impressive for me set and customize.

I just wish these static sites has a smooth way to do image layouts (crop, resize, layout and picset generation). I'd give up MD for that, html+emmet is basically just as simple as markdown.

* edit as for access, I gitlab pages host the static site and leave gitlab to handle the netlify cms auth part.

You could use the built-in editing suite at Github, or use something like codestar or equivalents on other platforms.

What other options?

I found an app called Teddy Hyde[0] which is designed to make this workflow easier. It's focused around Jekyll but perhaps it's flexible enough for Huge also? Ultimately I couldn't get myself to write anything regularly so I gave up with the whole idea, but the app seemed decent.

[0] https://play.google.com/store/apps/details?id=com.EditorHyde...

Yes this is where I got blocked on this too. I like using the WP Android app to upload photos when travelling. Obviously a static site by its very nature cannot interact with a phone app, so this seems like a difficult/intractable problem.

Outsourcing it to a search engine is pretty easy. I do something like the following for DuckDuckGo:

  <form id="search" method="get" action="//duckduckgo.com/">
    <input type="text" name="q"/>
    <input type="hidden" name="sites" value="mywebsite.com">
  </form>

Google Search, JS solutions like lunr.js, paid options like Algolia...

Check my comment on this thread: https://news.ycombinator.com/item?id=21978989

MkDocs is great for what it was built for, documentation. I also use the Material theme myself.

For a blog though, it would be a terrible format. They meet very different use cases.

We did that on our project were using markdown in jekyll and kept it in hugo. Hugo has its own plugins, not that hard really.

EDIT: Hugo has a plugin to import a jekyll project, you can check maybe it will do most of the work for you. Link https://gohugo.io/commands/hugo_import_jekyll/

FYI, I ca'n't reach your site! If it works will check out!

Yes, it is, specifically in ease of use of the static site generator itself, especially compared with a Python or Ruby one. (Node things tend to be more amenable to easily reproducible builds.)

From experience, I say that installing Python or Ruby static site generators (Hyde and Jekyll specifically I have in mind) starts out markedly harder, and tends to get steadily harder over time, particularly if you don’t ride the upgrade treadmill¹, whereas the likes of Hugo (Go) and Zola (Rust) are a single binary that you just download and run, and it’ll continue to work forever, and when you switch computers you can just copy or download the binary again and it’ll still work.

This difference concretely saved substantial quantities of time for redoing Fastmail’s website last year in Zola: once it genuinely was just “download Zola 0.8 from such-and-such a location and run `zola serve`”, a few people that would have given up on setting up a Jekyll or Pelican or similar environment, and instead gone with a longer “try modifying it, deploy it and see what happens” or “ask someone else to do it” approach, instead did just download the single binary and use it, because it genuinely did Just Work™.

If it’s hard (here probably meaning “takes longer than five minutes of effort”) to get an editing environment going for your blog or website or whatever, you will abandon your website sooner or later, for a cause that you wouldn’t if you were using one where it was easy.

So I say: prefer a single-binary for your occasionally-updated website, so that it’s your fault when you abandon it, rather than the SSG’s!

___

¹ For example: I used Hyde for the previous iteration of my personal website, and last time I tried to spin up a fresh build environment for it, I genuinely failed—I knew what I was doing, but a couple of packages in there would no longer build. Admittedly Hyde is abandoned and you’re not likely to have quite such trouble on an actively-maintained project, but still: treadmills, and processes that you can’t be confident in.

not really. although hugo is pretty established, too. for a personal blog, i'd just pick one and run with it. getting stuff out is more important than the "right" generator.

(that said, personally, i prefer the runtime hackability of pelican, and i don't find the speed of generation to matter much under 200 posts)

Great to hear! I'd say the biggest difference with WP is that you don't worry about plugins, updates, server, etc. Maybe 50% of the posts I write are included in an ebook, I try to write them as a series, so they have a double purpose. One to help if you're searching specific information, the other more organized in an ebook where I explain something from the beginning with a clear structure. Making a series that ends up in an ebook also helps with ideas of what to write about, because I define all the topics beforehand. The other 50% of the posts are individual pieces, maybe an explanation of a problem or task solved while coding, or just a description of something new I'm learning :)