Requirements:
- Write software engineering blogs with markdown
- Open IDE, write some thoughts, push new version of the blog from my terminal
- Be able to host on github for free
- Be able to display code with syntax (I guess if it supports markdown it will support that too?)
- Maintain structure e.g. post dates, navigation, post tags
- Ability to have a page about me<p>Bonus points
- be able to personalise a little bit the look and feel if I wanted to e.g. font<p>No need for:
- comments on blog posts<p>What are my options?
As per many other comments, it sounds like a static site generator like Hugo (<a href="https://gohugo.io/" rel="nofollow">https://gohugo.io/</a>) or Jekyll (<a href="https://jekyllrb.com/" rel="nofollow">https://jekyllrb.com/</a>), hosted on GitHub Pages (<a href="https://pages.github.com/" rel="nofollow">https://pages.github.com/</a>) or GitLab Pages (<a href="https://about.gitlab.com/stages-devops-lifecycle/pages/" rel="nofollow">https://about.gitlab.com/stages-devops-lifecycle/pages/</a>), would be a good match. If you set up GitHub Actions or GitLab CI/CD to do the build and deploy (see e.g. <a href="https://gohugo.io/hosting-and-deployment/hosting-on-github/" rel="nofollow">https://gohugo.io/hosting-and-deployment/hosting-on-github/</a>), your normal workflow will simply be to edit your markdown and do a git add/commit/push to make your changes live. There are a number of pre-built themes (e.g. <a href="https://themes.gohugo.io/" rel="nofollow">https://themes.gohugo.io/</a>) you can use, and these are relatively straightforward to tweak to your requirements. In theory, since the content (markdown) is separate from the presentation (theme), you can change design relatively easily (although in practice there's often theme specific config).
Many of the recommendations in this thread are great. Go with a SSG; almost all of the bigger players will be able to do everything you list and (a lot) more. Personally a big fan of Astro[1] but Hugo, Jekyll, 11ty, etc. will do the job just fine and there's imo no reason to pick one over the other in your case apart from working with a framework in a language you're comfortable with.<p>If you're looking to get started right away and don't care about having it hosted by someone else there's also bearblog[2] which I can recommend btw.<p>[1] <a href="https://astro.build/" rel="nofollow">https://astro.build/</a>
[2] <a href="https://bearblog.dev/" rel="nofollow">https://bearblog.dev/</a>
If you don't need tagging (as <a href="http://danluu.com/" rel="nofollow">http://danluu.com/</a> doesn't, for example), you can use my "no workflow" solution:<p>* draft in markdown<p>* render in HTML (using any Markdown to HTML tool, e.g. pandoc)<p>* link your CSS in the HTML file.<p>* push to your preferred serving platform<p>This has the advantage of getting you started as quick as you can open an editor.<p>If after 5 posts you are wanting a tool, pick whichever (Hugo).
Sounds like any static site generator supporting Markdown will do.<p>- Jekyll: the OG, but requires a ruby toolchain.<p>- Hugo: compiles to a single static binary, but you may have to get used to its (Go text/html) templating.<p>- Zola: also compiles to a single static binary, but uses Jinja-like templating.<p>- Gozer [^1]: my own, like Hugo, but 1000x simpler. I rolled my own because I wanted something that didn't move under me in the next 10 years and just because it was fun and easy enough to build.<p>[1]: <a href="https://github.com/dannyvankooten/gozer">https://github.com/dannyvankooten/gozer</a>
No love for Astro[1]? I've been using it and like its easy setup and extensibility.<p>(I host it on Netlify with a custom domain for free and Netlify builds a new release every time I push to main).<p><a href="https://astro.build/" rel="nofollow">https://astro.build/</a>
I like Hugo a lot, personally.<p>If you want to go as minimal as possible, my <a href="https://github.com/Siilikuin/minimum-viable-hugo">https://github.com/Siilikuin/minimum-viable-hugo</a> gets you set up with a single no-CSS, no-JS HTML page. I found this pretty ideal for staying to learn the platform.<p>If you really, really like minimalism, you could also try pandoc-server to dynamically serve HTML files from your Markdown as people visit the page, just like PHP does: <a href="https://pandoc.org/pandoc-server.html" rel="nofollow">https://pandoc.org/pandoc-server.html</a>
I have been using Pelican with a modified new.css theme. Recently migrated from hosting on a DO instance with Nginx to Github Pages.<p>What I'd love to do is totally remove the SSG from this pipeline and replace it with a WYSIWYG editor (blasphemy, I know). Or at least something that I could just drag and drop images to so I don't have to manually link them in the .md files.<p>I'd also like to totally remove the CSS from my site and just link to an existing theme served by a CDN somewhere, like if there was a "standard" simple theme with same defaults and platform-specific font choices etc. (ie. how it was supposed to be near the beginning where users would get served markup (via HTML) and then be able to theme it as they desire (obviously still possible but very few people do this).<p>Micro.blog looks interesting but the themes aren't quite as minimal as what I prefer.
I think this is what your looking for:
<a href="https://jamstack.org/" rel="nofollow">https://jamstack.org/</a><p>I use Hugo with a theme called Congo.
<a href="https://gohugo.io/" rel="nofollow">https://gohugo.io/</a>
<a href="https://github.com/jpanther/congo">https://github.com/jpanther/congo</a>
Most SSGs, or if you want to have it easy: <a href="https://getpublii.com/" rel="nofollow">https://getpublii.com/</a> - generates static sites, can publish to github pages (among others), has themes.
I have used Jekyll forever. Now with Netlify.<p>I have no reason to recommend this other than its worked for me for 10+ years. It's perfectly fine. I am not even much of a Rubyist, it's 100% an accident of history.<p>I create/edit posts on Github directly, in master. They publish when they get a timestamp attached to the markdown file. Even when published, I only share around to a few friends for feedback and typos before sharing more widely.<p>As someone who used to tweak his Jekyll installation endlessly, I find obsession with tweaking/exploring/creating blogging platforms a sort of procrastination to avoid the actual blogging part ;)
Here's my personal blog, set up in 2019 on github pages (free hosting), built with Jekyll [1] which supports markdown, code snippets, tags, sections and more.<p>For a technical person, it does the job pretty well and almost without any maintenance effort:<p>- Github: <a href="https://github.com/TCGV/Blog">https://github.com/TCGV/Blog</a><p>- Live: <a href="https://thomasvilhena.com/" rel="nofollow">https://thomasvilhena.com/</a><p>[1] <a href="https://github.com/jekyll/jekyll">https://github.com/jekyll/jekyll</a>
Build your own setup with Soupault! It has the Unix philosophy of piping output to CLI tools that do one thing well rather than locking you into a specific system. It helps glue together many other tools like a lightweight syntax renderer, modified date adding, aggregating the posts to create feeds, make some markup modifications, etc.<p>Additional suggestions outside a specific tool:<p>* Inevitably you will need more than base Markdown supports features, so you’ll either need to buy into a specific Markdown fork (some of which aren’t open) that won’t port to other platforms if you need to migrate, script the hell out Pandoc or some other tool creating your own fork, or you could start with a lightweight syntax like <i>reStructuredText</i> or <i>AsciiDoc</i> that have a more comprehensive base supporting 98% of your needs including proper metadata in the file, image sizes, figures, callouts/admonitions, spans with class names, definition lists, details/summary, footnotes, citing blockquotes; building these ad-hoc will suck to maintain & could output bad semantic markup making it difficult for screen readers, TUI browsers, web crawlers to parse & understand<p>* Don’t do syntax highlighting on the client side for a static site (e.g. no highlight.js or similar)<p>* Don’t touch the base user font size for a blog as users should be able to override font size for their accessibility (e.g. no body { font-size: 14px })<p>* Add an Atom and/or RSS feed
If I were to start again from scratch, I'd likely use Zola as SSG (<a href="https://www.getzola.org/" rel="nofollow">https://www.getzola.org/</a>)
A lot of great suggestions here and some stuff I’ve never heard of before!<p>Throwing my own suggestion into the ring, as I was just looking into this last week.<p>I started setting up a blog using Hexo. It’s another Node based SSG that uses markdown and supports tags. It has a lot of neat plugins that people have developed, too.<p>I like it so far!<p><a href="https://github.com/hexojs/hexo">https://github.com/hexojs/hexo</a>
Here's a walkthrough of how I set up Hugo with free hosting on Cloudflare - <a href="https://smaller.fish/posts/hugo" rel="nofollow">https://smaller.fish/posts/hugo</a>
I've played around with several platforms in the last year or so. I've landed on the following setup that works very well for me and ticks all your boxes:<p>A SvelteKit[0] app hosted on Cloudflare pages. The repo is hosted on GitHub and hooked up to the Cloudflare Pages app [1]. On PRs, I get preview environments. On merge, the changes get deployed to my "production" website. I write blog posts and other content in markdown, which is then processed by mdsvex[2] with very minimal setup.<p>Mostly, my requirements were more focused around getting the actual framework, hosting, etc. out of my way so that I could focus on writing. Gatsby and Next.js were too configuration heavy and turned me off once I scratched beyond the surface.<p>[0] <a href="https://kit.svelte.dev/" rel="nofollow">https://kit.svelte.dev/</a>
[1] <a href="https://developers.cloudflare.com/pages/configuration/git-integration/" rel="nofollow">https://developers.cloudflare.com/pages/configuration/git-in...</a>
[2] <a href="https://github.com/pngwn/MDsveX">https://github.com/pngwn/MDsveX</a>
Others have mentioned static site generators. I like Hakyll [1] because it can tightly integrate with Pandoc [2] and allows you to develop custom solutions (such as `.pdf` downloads) if your needs ever grow.<p>[1]: <a href="https://jaspervdj.be/hakyll/" rel="nofollow">https://jaspervdj.be/hakyll/</a><p>[2]: <a href="https://pandoc.org/" rel="nofollow">https://pandoc.org/</a>
My blog works like many of those described in others comments, it's:<p>- Jekyll(any static site generator would do, I'd probably pick Zola or Hugo if I was starting from scratch. See list[0])<p>- GitHub to host source code<p>- GitHub actions to push resulting assets to S3(Would try R2 over S3 if starting from scratch I think)<p>- Cloudflare for TLS, edge caching(including HTML[1] which is nice)<p>The source for my blog is: <a href="https://github.com/k0nserv/hugotunius.se">https://github.com/k0nserv/hugotunius.se</a>. I also made a starter template[2] at some point, but it's quite out of date now.<p>0: <a href="https://github.com/myles/awesome-static-generators">https://github.com/myles/awesome-static-generators</a><p>1: <a href="https://hugotunius.se/2020/01/01/edge-cached-static-sites-on-cloudflare.html" rel="nofollow">https://hugotunius.se/2020/01/01/edge-cached-static-sites-on...</a><p>2: <a href="https://github.com/k0nserv/one-cent-blog">https://github.com/k0nserv/one-cent-blog</a>
I made Svekyll for exactly the simplicity you want.<p><a href="https://svekyll.com" rel="nofollow">https://svekyll.com</a><p>Svekyll is the simple conventions of Jekyll but the dynamic power of Svelte. It's nothing more than a package.json file and a posts directory with Markdown files.<p>Svekyll gets all 100s on lighthouse. Mostly because each generated blog post is a single HTML file with all the JS inlined. But, you still can do anything you want as it is a Svelte app. Because it is a bunch of html files, it is easy to host on any web server, no backend customization required.<p>Someone else mentioned publishing via email. I do that too using my hosting service extrastatic. You can email a draft and it gets converted to markdown and then placed into the git repository for the blog.<p>Svekyll is open source: <a href="https://extrastatic.dev/svekyll/svekyll-cli" rel="nofollow">https://extrastatic.dev/svekyll/svekyll-cli</a>. You could definitely host on GitHub using a GitHub action to build and publish it.<p>Let me know if you want assistance: chris@extrastatic.com
How much code do you want to write for it? Do you just want to push to a repo and it happens automatically? What does the structure of your "navigation" "post dates" look like? Browsable?<p>The most simple thing I could think of would be asciidoc + github pages. Write stuff, generate output HTML, push all to repo, wait for sync. Done.
I built my blog to publish via email.<p>It’s got everything you need except it’s not possible to edit posts. You just have to email yourself a new, updated version and make that version public.<p>Taught me a lot about serverless, SES, css, and htmx. 10/10 would recommend trying this route if you don’t want to use the standard toolsets.
I created the BlogInABox[1] devcontainer to help people get started with Jekyll + GitHub pages. It's a repo that you can fork that has a site ready to go, and a devcontainer that has nice utilities like spellcheck & markdown linting/fixing. This way, you can use it locally in a devcontainer or with github codespaces and a simplified process.<p>It comes with a companion site [2] that shows how to get scheduled posts, comments, etc. working nicely.<p>[1] <a href="https://github.com/SeanKilleen/blog-in-a-box-container/">https://github.com/SeanKilleen/blog-in-a-box-container/</a>
[2] <a href="https://bloginaboxdemo.com/" rel="nofollow">https://bloginaboxdemo.com/</a><p>Hope this is helpful!
I looked for something similar and ended up coding my own. It was a lot of fun and even did not took too much time. Of course, I had one advantage – being an Emacs user I could leverage Emacs & Org mode. And one nice thing about my one is that the whole blog (content, templates, styles, JS) is contained in one source file. (Of course, binary assets are kept separately, though technically they could be embedded in an org file, too.) And btw, I don't even need to leave Emacs and go to the terminal to push he new version. :-)<p>If not for Emacs, I'd probably glue together a few tools like Pandoc, sedm scp and the like.
I use <a href="https://mataroa.blog/" rel="nofollow">https://mataroa.blog/</a> after it was posted on HN by one of it's creators. Been happy with it for the past 2 years so far
A variation of this post pops up here a lot. Reminds me of writers on writing forums looking for the perfect "light weight" word processor.<p>Problem being, everyone has one "must have" feature that they want along with the light-weight solution. And for every writer that "must have" feature is different.<p>When you join all the single, one-off "must haves" together you end up with Microsoft Word.<p>As for blogging platforms, I use wordpress.com. Paid, not free. No work at all on my end apart from writing. Haven't thought about the platform in a long while now.
Hugo and papermod as the theme<p><a href="https://github.com/adityatelange/hugo-PaperMod">https://github.com/adityatelange/hugo-PaperMod</a>
I love Mataroa: <a href="https://mataroa.blog" rel="nofollow">https://mataroa.blog</a><p>I jumped from WordPress to Mataroa and I'm also using Jekyll, Hugo, Zola, and Obsidian to blog.<p>There are a lot of great things about Mataroa that I love. I've blogged about Mataroa: <a href="https://pivic.blog/blog/mataroa/" rel="nofollow">https://pivic.blog/blog/mataroa/</a>
Hugo is getting a lot of love in here (with good reason). If you do end up trying Hugo and feel it's like 90% what you want but never quite perfect, do check out Zola (<a href="https://www.getzola.org/" rel="nofollow">https://www.getzola.org/</a>). It feels the most like Hugo of anything I've tried but I found the docs and the template system better.
Astro Js or similar hosted on Netlify, Cloudflare, etc.<p>Please review the link for further details on Jamstack
and/or SSG.
<a href="https://nishad.link/posts/getting-started-with-jamstack/" rel="nofollow">https://nishad.link/posts/getting-started-with-jamstack/</a><p>Consider exploring Htmx if you don't want markdown or don't want to deal with npm..
I can't recommend Eleventy enough!<p><a href="https://www.11ty.dev" rel="nofollow">https://www.11ty.dev</a><p>I converted my WordPress blog to Eleventy 4 years ago and never looked back, it's been delightful!<p><a href="https://www.joshcanhelp.com/taking-wordpress-to-eleventy/" rel="nofollow">https://www.joshcanhelp.com/taking-wordpress-to-eleventy/</a>
Lately I've been using Fruition - which is just a way to attach a custom domain name to your published Notion directory. The script is no longer maintained but it keeps working using some Cloudflare agent scripting mechanisms.<p>URL: <a href="https://github.com/stephenou/fruitionsite">https://github.com/stephenou/fruitionsite</a>
Quartz! <a href="https://quartz.jzhao.xyz/" rel="nofollow">https://quartz.jzhao.xyz/</a><p>Beautiful, performant, native support for editing via Obsidian. I use it for my personal side, <a href="https://thestu.art" rel="nofollow">https://thestu.art</a>
MkDocs with the Material for MkDocs theme has reasonable blogging support, and a dockerized image for building. It also has some other features like footnotes, mermaid diagrams, and "code annotations" for code blocks.<p>Type markdown, build in docker, publish assets to GitHub Pages :tada:
I used eleventy recently to build my website. What I liked:<p>- npm / js-based tooling, no fooling around with ruby
- plenty of great docs
- enough public adoption to find good answers to common things you’d like set up<p>Not sure why I hadn’t tried it before - I know it’s been around for a while.
You do need a server for this (with PHP), but you can probably compile it to a static website too: <a href="https://github.com/Cristy94/markdown-blog">https://github.com/Cristy94/markdown-blog</a>
Quarto - <a href="https://quarto.org" rel="nofollow">https://quarto.org</a><p>I've been searching for some time also, more or less the same requirements, and I settled on quarto. Give it a try, you won't be disappointed!
Interesting how no one suggested prose yet: <a href="https://prose.sh/" rel="nofollow">https://prose.sh/</a><p>I use it for my personal blog, it supports custom domains and it's uses public key authentication.
check out bearclaw <a href="https://github.com/donuts-are-good/bearclaw">https://github.com/donuts-are-good/bearclaw</a><p>write it in markdown and host it anywhere, no fancy shenanigans
I'll definitely go with Astro if you don't need any CMS stuff. They already have a blog template. It's super fast to deploy to vercel as well.
So you can just focus write your content.
May I recommend my personal creation <a href="https://mkws.sh/" rel="nofollow">https://mkws.sh/</a>? Simple, sh based, very customizable, very lightweight.
I really like <a href="https://bearblog.dev" rel="nofollow">https://bearblog.dev</a><p>It helps you get focused on just writing while removing all the unnecessary stuff.
blot (<a href="https://blot.im/about" rel="nofollow">https://blot.im/about</a>) is a contender. plain text files stored in git are converted into a website; usable for blogs and other types of sites (e.g. your use case, a blog + an about me page). the source code to blot is in the public domain.<p>$5/month, I am a customer and have liked the experience. also self-hostable for free.
omg.lol (<a href="https://home.omg.lol/" rel="nofollow">https://home.omg.lol/</a>) has not been mentioned. You get quite a few nice bonuses from it (like community!) for a very reasonable, imo, $20USD a year. At least give it a look my friend!
Distill for R Markdown is a great alternative too. I really like the layout and the flexibility you get with the plots.<p>The site can be hosted directly on github pages and you can configure the custom domain on github. Fairly easy to setup and use.<p>Comes out of the box with GDPR compliance, google analytics and cookie consent<p><a href="https://rstudio.github.io/distill/website.html" rel="nofollow">https://rstudio.github.io/distill/website.html</a>
<a href="https://www.flatpress.org/" rel="nofollow">https://www.flatpress.org/</a><p>just php. nothing else is needed. flatfile database. you can personalize it easily. it exists since 2006 and it still maintained. boring, it just works.
Like many others here I'm going to recommend Jekyll too, and I recently started blogging with it [1]. Although the primary reason to suggest Jekyll would be that its non-nonsense and has been around a while (which is what the other comments mention), I would also like to add that when I needed customizations it was easy to Google for them because of the large community. Going in I believed that no platform will match all my needs, so I needed something where minor customizations wouldn't demand a steep learning curve. Some specific examples that I was able to solve with some basic searching:<p>[1] On the homepage [a] I needed some excerpts from the post to appear underneath the title. I also wanted this excerpt to show up in the RSS feed.<p>[2] Since I think of my posts as live documents - if I remember a new detail, I add it to my posts, because more than anything else my blog is notes for me -I also wanted to add a "Last major update" date to my posts - you can see this appear over the titles (the date after '||') and at the top of individual articles. I wanted this to be manual because I didn't want this date to change because I fixed a typo etc.<p>[3] Since I'm interested in technical articles, I wanted a good way to cite papers. I use jekyll scholar [b] for the purpose, and if you look at the last 2 articles on my blog you'll see the outcomes it produces.<p>[4] I also wanted my article URLs to be concise instead of the jekyll default which has year, month, day as part of it - this was a fairly easy change to make as well.<p>[5] Linking to a different section in an article or a section in another article without using the public URL (because this might change if for some reason I end up with a different namespace tomorrow) - this is also possible using variables, whose values get (re-)generated every time you change the document markdown.<p>[6] Before I push the article to github I usually have it served for a while (typically a few days) on a local server on my laptop (you don't have to install a separate server - the jekyll build system bundles one, this is how you locally see what the article would look like) which I proof-check from different devices while in the house, e.g., from my mobile when I'm not at my desk. Its convenient.<p>[7] Of course, support for MathJax.<p>[8] Lot's of themes to pick from. For ex. Al-Folio [c] is a minimalist theme that seems to be becoming popular for academic writing.<p>I'm sure some of the other solutions do most of these, but I wanted to draw your attention to the ease of customizability.<p>[a] <a href="https://blog.quipu-strands.com/" rel="nofollow">https://blog.quipu-strands.com/</a><p>[b] <a href="https://github.com/inukshuk/jekyll-scholar">https://github.com/inukshuk/jekyll-scholar</a><p>[c] <a href="https://github.com/alshedivat/al-folio?tab=readme-ov-file">https://github.com/alshedivat/al-folio?tab=readme-ov-file</a>
For a static blog written in Markdown, Github has all of that built-in.<p>When you’re on Github, use its IDE by pressing the <i>.</i> key. You can, of course, use Git and edit the files locally.<p>Own and maintain these two folders <i>_posts</i> and <i>_assets</i>. If you are going to write regularly, I suggest creating sub-folders inside <i>_posts</i> but name your Markdown files by date such as <i>2024-02-5-foo-bar-is-my-file.md</i>.<p>On Github, use Github Pages (officially powered by Jekyll) and deploy using one of the pre-defined Jekyll Themes[1]. That’s it, your blog is at <i>reponame.github.io</i> which you can CNAME it from a domain you own just like I did mine at <i>my-domain.com</i>.<p>Comments: You can either use Github Discussion as your blog’s commenting system or embed a third party service which you can export and carry around when you change such services. Honestly, and personally, I don’t want to deal with comments these days.<p>Now, for the customization, the themes are in simple Jekyll[2] which you can play around with.
In future, if you want to move from Jekyll to something else, you just have to worry about that <i>_posts</i> and <i>_assets</i> folder. They may have different naming convention but you can just config-managed it or change it to your choice. This is why I suggested owning that two yourself.<p>You also may not worry about FrontMatter[3] (meta in the header) and its accompanying jazz by asking Jekyll to use the plugins <i>jekyll-optional-front-matter</i> and <i>jekyll-titles-from-headings</i>. These comes as part of the officially supported Jekyll plugins[4] by Github. That way, you are just writing a human-readable plain-text spiced up with Markdown and readable by almost every other Static Site Generator. You can use your favorite IDE or another Markdown editor such as Obsidian to edit your files without ever running Jekyll locally.<p>Now, play with the <i>_config.yml</i> that Jekyll generates for you from the theme above to define your post dates, navigation, and others. Jekyll is one of the OGs — the Gandalf of Static Site Generators. If you have a problem, someone somewhere has solved that.<p>If you really think of it, “there is no spoon”, eer, I mean “Jekyll.”<p>Did I missed something? I was supposed to write a blog article for my website on this one and this comment will serve as my starting bullet points.<p>1. <a href="https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/adding-a-theme-to-your-github-pages-site-using-jekyll" rel="nofollow">https://docs.github.com/en/pages/setting-up-a-github-pages-s...</a><p>2. <a href="https://jekyllrb.com" rel="nofollow">https://jekyllrb.com</a><p>3. <a href="https://frontmatter.codes/docs/markdown" rel="nofollow">https://frontmatter.codes/docs/markdown</a><p>4. <a href="https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll#plugins" rel="nofollow">https://docs.github.com/en/pages/setting-up-a-github-pages-s...</a>