How to start a blog using Hugo(flaviocopes.com) |
How to start a blog using Hugo(flaviocopes.com) |
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.
(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)
I certainly don't regret the move - much happier having a static site than WP in place - but some of this is much more complex than I had hoped it would be. Amongst other issues;
* error messages can be extremely opaque (although usually easy to google, at least) * upgrading to new versions is not always straightforward
I deploy my site via rsync, but got bitten immediately by a very odd bug with respect to file timestamps (#6161) where a bunch of my files were warped back to the 1750's.
I personally am happy with hugo. I probably wouldn't recommend it at this point though...
I am interested to hear the consensus from HN users as to which is better, and why.
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.
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.
This has been fairly well beaten into the ground at this point.
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.
This is why using a completely separate domain can be wise if you’re using a third party to host your blog. At Fastmail when we shifted our blog to Ghost(Pro), we moved the blog from blog.fastmail.com to fastmail.blog, so that they definitely can’t get any cookies we may happen to set on domain=fastmail.com (even though our login cookies are domain=www.fastmail.com and thus safe anyway; defence in depth, and all that; by contrast, our product Topicbox does store its cookies on domain=topicbox.com, so the protection of using topicbox.blog is real there).
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.
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.
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.
- 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).
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 do think a few features are missing that I find valuable:
* Search (you can add it as an external service I haven't found one I trust and like yet. * Comments, there are several third-party comment providers that I can use, I tried out Disqus for a while but I didnt like nor trust them. I look at using forum software for the comments but then I have to run that and I might as well stay in WP
Then there are a few plug-ins I use and like.
The worst part of using WP is of course security. I have switched to fully managed WP hosting so I dont have to worry too much about that. I do still worry about plugins but my provider does not allow a lot of plug-ins due to issues and I can totally appreciate that.
What I do lack is something interesting to write about, in a consistent manner. I have been writing code for a long time. I did build some interesting stuff. I'm currently working on a startup that does use some blog-worthy tech: any attempt ends up with very long essay-shaped posts, which are extremely time-consuming to write and frankly not so interesting.
Any suggestion on how to find a niche and consistently write about it?
https://gohugo.io - Hugo website
> My suggestion is to avoid subdomains completely.
https://themes.gohugo.io - Hugo themes
https://discourse.gohugo.io - Hugo forum
Hmm
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
>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.
This editor should be small, self-contained and secure and could be located in a separate access-restricted area of the site.
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.
[1]: https://tinacms.org/
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.
On the other hand, Go's lack of generics makes working with collections harder than it should be... and much of templating involves working with collections.
To give a concrete example, I wanted to create a page where I group categories by post count. Hugo has methods to group pages, but not categories, so I rolled my own imperative grouping code. It wasn't difficult, but it would have been simpler to do declaratively in many other ecosystems (say, .NET with LINQ).
[0] https://play.google.com/store/apps/details?id=com.EditorHyde...
https://templates.netlify.com/template/hugo-starter-blog-the...
I created a similar post a while ago, might be interesting for some who want to use GitLab instead of GitHub + Netlify:
https://tkainrad.dev/posts/using-hugo-gitlab-pages-and-cloud...
Where's the fun in that :)
I would not advise it to a non-programmer/tech savvy person though.
<form id="search" method="get" action="//duckduckgo.com/">
<input type="text" name="q"/>
<input type="hidden" name="sites" value="mywebsite.com">
</form>[1]: https://www.mkdocs.org/ [2]: https://squidfunk.github.io/mkdocs-material/
For a blog though, it would be a terrible format. They meet very different use cases.
I also put together a video tutorial of how I set up my CI/CD pipeline to deploy to AWS using Terraform.
https://devbrett.com/videos/2018-07-22-static-website-terraf...
The whole site costs me about 50c a month on S3 + Cloudfront.
Costs me around $0.01 per build which isn't bad. Just easier than writing my own script.
Is it practical to keep the rendered HTML as static pages, and just use hugo/markdown for new posts?
Migrating the markdown files to hugo looks like a pain. Header files need to be migrated. Also jekyll plugins will obviously not work.
Might be better to just leave the old stuff as-is...
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/
Just adding new posts, push the repo and let the build and deployment scripts do their thing.
And - don't forget - the less dynamic your site is the less attractive it becomes for the bad guys.
If anybody tries it out let me know!
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!
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.
Follow David Perell for writing inspiration. https://twitter.com/david_perell/status/1213894632943296516
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.
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
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.
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
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.
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.
It's not pretty to look at, but it can be read, understood, and maintained by one person.
I recently evaluated migrating to Hugo to ditch my hastily written script & use a 'robust, mature' tool. I wanted to add an RSS feed and figured "why work more on my one off script, I could use a pre-built solution!" But migrating was indeed a pain in the butt, and it quickly became clear that writing a function to output an RSS feed was much faster than doing everything I needed to migrate.
Static blogs are very simple, and performance doesn't matter that much for all but the most prolific authors, and you can improve performance if needed. Write your own script!
Basically a variant of how:
works. Or:
https://chrisdiana.dev/cms.js/
In a similar vein (but not solely client hosted and managed) there's:
https://vuelog.js.org/#/page/about
If all you need is a blog, it's really just a bit of navigation you need js/<some program> to help with. And you can of course add things like commenting as a SaaS that's essentially just an imported cross side scripting attack on yourself, much like with visitor tracking via Google analytics etc. See for example muut.com for comments.