home.public.blog/home/public/blog/content/Blog/hugo-org-github.md

+++ title = "Publishing a blog on Github with Org and Hugo" author = ["George M Jones"] publishDate = 2020-08-16 lastmod = 2023-12-06T05:45:25-05:00 tags = ["geek", "blogging", "org", "emacs", "HOWTO"] categories = ["blog"] draft = false +++

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 https://eludom.github.io/" 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 {#potential-ox-hugo-sites-to-copy}

1.1 The Art Of Not Asking Why {#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 {#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 {#the-results}

You're looking at the results: https://eludom.github.io/, 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 {#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 {#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-more-than-you-ever-wanted-to-know-the-long-story-dot}

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 {#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 {#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 {#settings-and-organization}

5.2.1 Set EXPORT_HUGO_SECTION {#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 {#processes}

5.3.1 Drafting {#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 {#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 {#make-sure-post-is-live-looks-right}

• Go to site: https://eludom.github.io/
• 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 {#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 {#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.