Publishing a blog on Github with Org and Hugo

2020-08-16 / geek / blogging / org / emacs / howto

If you ever thought to yourself, “Gee, Emacs Org mode is a great outlining and authoring tool, and I wish there were a powerful and simple way use it to publish static websites on github or in S3 buckets, I wish my blog could look as slick ast http://curious.galthub.com/” your’re in luck, All but the simple part. Here are some of the references I used.

Post 19 of #100DaysToOffload https://100daystooffload.com/

1 Potential ox-hugo sites to copy

1.1 The Art Of Not Asking Why

I started by looking for sample web sites to copy by perusing the sites on this list https://ox-hugo.scripter.co/doc/examples/

I found the following

Site: https://joshrollinswrites.com/
Source: https://github.com/jarss/TAONAW/tree/master

Josh has been great in answering the odd question. His blog is interesting too !!! He accepts paypal…

2 General Info on Hugo, Ox-Hugo and github pages

Then I did some reading (this is where the not simple part comes in) on the following sites

hugo getting started

https://gohugo.io/getting-started/quick-start/

hosting a blog on github pages

https://gohugo.io/hosting-and-deployment/hosting-on-github/

github pages

https://pages.github.com/

HOWTO with Hugo and github pages

https://medium.com/swlh/hosting-a-hugo-blog-on-github-pages-with-travis-ci-e74a1d686f10

Org mode hugo exporter

https://ox-hugo.scripter.co/

I’ll probably go here, but it seems like a bit much to start…
Maybe learn the un-automated way first?

About Hugo

https://people.umass.edu/weikaichen/post/emacs-ox-hugo/

About blogging with Hugo

https://www.shanesveller.com/blog/2018/02/13/blogging-with-org-mode-and-ox-hugo/

3 The results

You’re looking at the results: http://curious.galthub.com/, this and other posts. It took a couple deep dives to understand it, but I think I more-or-less have it, and it is a very seamless integration wtih Org-Mode, which for some of us closes the deal even if there is pain involved

4 Bonus: Twitter cards

And for bonus points I did reading on how to add twitter card support to ox-hugo bog posts, e.g., so you can write your post and have twitter or other sites (such as Mastadon) that understand the format pull the title, intro and possibly an image to post in the web sit.

4.1 Twitter Cards: HOWTO, the short story

Short version: if you drop twitter_cards.html in layouts/partials/ of your blog, you then just write your blog, publish it, and past the URL into the https://cards-dev.twitter.com/validator to make sure it’s going to work when posted

4.2 Twitter Cards: More than you ever wanted to know, the long story.

Twitter Cards: https://sproutsocial.com/insights/twitter-cards/
Twitter cards in ox-hugo: https://ox-hugo.scripter.co/doc/org-toc/
Twitter cards in Hugo: https://gohugo.io/templates/internal/
Twitter cards partials for Hugo: https://gohugohq.com/partials/twitter-cards-partials-for-hugo/
Ttitter card, ox-hugo discussion: https://discourse.gohugo.io/t/solved-help-with-twitter-card-image/14067
about hugo partials: https://gohugo.io/templates/partials/

5 How to publish: files, settings, process

And, finally the gory details of actually publishing.

These are raw/WIP notes, but mostly right. They actually publish this blog.

5.1 Important Files and Directories

/home/gmj/public/github/ox-hugo-blogs/blog/curious.org: The one file to rule them all o This is the blog. All articles live in this one file as separate org trees. This is the “source”.
HUGO_BASE_DIR=/home/gmj/public/github/ox-hugo-blogs/blog: The root of my blog o This is the root/source for the blog. It gets pushed to git@github.com:eludom/blog.git (fetch)
${HUGO_BASE_DIR}/content/: Where local content (markdown) goes, e.g. content/posts/steve.md
${HUGO_BASE_DIR}/docs/: Where the content to publish (html) goes,

5.2 Settings and Organization

5.2.1 Set EXPORT_HUGO_SECTION

In the .org file that is the blog, set EXPORT_HUGO_SECTION to be “Blog” (or in whichever section you want posts to land, default is “posts”)

This is inherited lower level headers in org so

** Blog
   :PROPERTIES:
   :EXPORT_HUGO_SECTION: Blog
   :EXPORT_FILE_NAME:
   :EXPORT_HUGO_PUBLISHDATE:
   :END:

covers things in

* Content
** Blog
*** Work Stuff
*** PUBLISHED Choosy Programmers Choose GIF :Wilhite:CompuServe:GIF:History:Computers:Emacs:Programming:

5.3 Processes

5.3.1 Drafting

TODO start hugo in root directory

hugo server -D

TODO Edit curious.org

Add an entry like this
```
*** WIP Walled Gardens
    :PROPERTIES:
    :EXPORT_HUGO_SECTION: Blog
    :EXPORT_FILE_NAME: walled-gardens
    :EXPORT_HUGO_PUBLISHDATE: 2020-08-11
    :END:

    This is a brain dump on something like 40 years experience with
    "social media" of various forms.
```
EXPORT_HUGO_SECTION : probably not needed if inherited from higher level headline

EXPORT_FILE_NAME : The file name for this post. Could be date.

EXPORT_HUGO_PUBLISHDATE : Set to the date this post should be “live”. Can be used to schedule “future” posts.

IMPORTANT : Posts with a status of TODO are drafts. WIP or PUBLISHED are “live”

EVEN MORE IMPORTANT : A valid Hugo post subtree is an Org subtree that has the EXPORT_FILE_NAME property set. ox-hugo only exports valid subtrees to markdown. You can draft to your hearts content in subtrees that do not have EXPORT_FILE_NAME set (and maybe export the subtree to text or html to view)

TODO Save

With point in the newly created or updated subtree, save the file.

TODO view at http://localhost:1313/

view the drafts http://localhost:1313/ View the result in your browser

5.3.2 Publishing

run hugo

In the HUGO_BASE_DIR run hugo. The results will be written to “doc/”.

push to github

I host on github.io.

      cd doc
      git add -A
      git commit -m"name of new post"
      git push

5.3.3 make sure post is live, looks right

Go to site: http://curious.galthub.com/
It often takes a minute or so after push for things to show up on the web site. You might have to refresh

5.3.4 Add and push the source

        cd ..
        git status .
        git add [new files]
        git commit -m"name of new post"

be sure not to add docs/, as that is pushed a a subtree.
possibly move the docs/ tree so that is not subsidiary to the root

6 Conclusion

“I mean, why not just use blogger.com or Wordpress”? Been there done that.

Companies come and go. I ought to know. I started my career working at CompuServe. The forums where apparently finally deleted on 2017. History was lost.

There are issues of control. There are the issues of using tools I like, not the GUI or “download my app” du jour with tracking, ads, monetization, bloat and more.