|
| 1 | ++++ |
| 2 | +title = "Blog using org-mode in Doomemacs with Hugo" |
| 3 | +author = ["tcluri"] |
| 4 | +date = 2024-03-23T14:00:00+05:30 |
| 5 | +tags = ["blog", "org", "doomemacs", "hugo"] |
| 6 | +draft = false |
| 7 | ++++ |
| 8 | + |
| 9 | +Hello! This is a post describing how anyone who uses Doomemacs can setup a blog and get writing. |
| 10 | +To get started, familiarize yourself with what I'm assuming you know to do. If you don't, read on - there will be links you might find helpful. We are here to learn 😃 |
| 11 | + |
| 12 | +- Know how doomemacs works to the extent that you can find where your init.el is and upgrade/sync from the commandline. |
| 13 | +- Know how to install the Go programming language on your linux machine and can install a go package(😉 Hugo) |
| 14 | +- Know how to use git well enough to commit/push your changes to a repository online - we'll be using Github |
| 15 | +- Know how to do a backflip once we are done, in your head is fine too |
| 16 | + |
| 17 | + |
| 18 | +## Doomemacs {#doomemacs} |
| 19 | + |
| 20 | +Doomemacs is a configuration framework for Emacs. You get many things out of the box - a starter pack of which you can disable/enable away options at your will. |
| 21 | +Try to use the latest doom configuration, I tend to upgrade doomemacs once in 3 months or whenever it is necessary which usually means that a package got an upgrade or a bug that got fixed. |
| 22 | +Once you try it, there is no going back to other configs/setups unless you are the person who loves your current Emacs config 🫡 |
| 23 | + |
| 24 | +Quick refresher of doomemacs commands, from the commandline: |
| 25 | + |
| 26 | +- `doom upgrade` - upgrades doom itself, fetching latest packages and their configuration. |
| 27 | +- `doom sync` - installs/removes packages and loads the packages by reading your doom config. |
| 28 | + |
| 29 | + |
| 30 | +### Enable org-mode and +hugo it {#enable-org-mode-and-plus-hugo-it} |
| 31 | + |
| 32 | +To install org-mode, go to your `init.el` file in your doom config folder. You can use `SPC f p` and then select by filename. |
| 33 | + |
| 34 | +In it, enable org-mode and hugo under the `:lang` heading. |
| 35 | + |
| 36 | +```emacs-lisp |
| 37 | + :lang |
| 38 | + ;; ... OTHER packages |
| 39 | + ;;nix ; I hereby declare "nix geht mehr!" |
| 40 | + ;;ocaml ; an objective camel |
| 41 | + (org +hugo) ; organize your plain life in plain text |
| 42 | + ;;php ; perl's insecure younger brother |
| 43 | + ;;plantuml ; diagrams for confusing people more |
| 44 | +``` |
| 45 | + |
| 46 | +This enables [ox-hugo](https://ox-hugo.scripter.co/) package which exports your posts in your `.org` file to markdown that is readable by Hugo(which we will install now). |
| 47 | + |
| 48 | +If you are using standard Emacs config, this does quite a lot on the org side of things and you can see exactly what it is [here](https://github.com/doomemacs/doomemacs/tree/master/modules/lang/org). |
| 49 | + |
| 50 | + |
| 51 | +## Hugo {#hugo} |
| 52 | + |
| 53 | +Hugo is a static site generator written in Go. Hugo is great and everyone should use it. Let's get it installed on our machine using commandline, |
| 54 | +this way we get to use the latest version and upgrade later on if needed. Before we do that we need to have the Go programming language installed. |
| 55 | +Go to the install [page](https://go.dev/doc/install) and follow the instructions, they are clear and you can confirm it is installed using `go version` in your terminal, the |
| 56 | +version should be `1.20` or greater since Hugo requires this. |
| 57 | + |
| 58 | +To install Hugo after you have installed the Go language run the following command, |
| 59 | + |
| 60 | +```nil |
| 61 | +go install github.com/gohugoio/hugo@latest |
| 62 | +``` |
| 63 | + |
| 64 | +This is the standard version of Hugo and not the extended edition, if you need that refer [here](https://github.com/gohugoio/hugo?tab=readme-ov-file#build-from-source) |
| 65 | + |
| 66 | +You can check that hugo is installed using `hugo version` at the commandline. |
| 67 | + |
| 68 | + |
| 69 | +## Setting things up {#setting-things-up} |
| 70 | + |
| 71 | +Create an empty git repository on Github, the name of your repository should be `<username>.github.io` |
| 72 | +and clone it on your machine to a folder named `blog` or something else. |
| 73 | + |
| 74 | +Now intialize hugo in the blog folder, use `--force` since it is a non-empty directory since it contains `.git` folder |
| 75 | + |
| 76 | +```nil |
| 77 | +hugo new site --force blog |
| 78 | +``` |
| 79 | + |
| 80 | +From inside the blog folder, `cd` into it, make hugo blog as a hugo module. This enables the blog's theme to be used as a module. |
| 81 | + |
| 82 | +```nil |
| 83 | +hugo mod init github.com/username/username.github.io |
| 84 | +``` |
| 85 | + |
| 86 | +Add the following lines to your `hugo.toml` (previously it was `config.toml`) to add a theme. Select any you like, there are [lots](https://themes.gohugo.io/). |
| 87 | + |
| 88 | +```config |
| 89 | +[module] |
| 90 | + [[module.imports]] |
| 91 | + path = "github.com/athul/archie" |
| 92 | +``` |
| 93 | + |
| 94 | +On the command line, run the following |
| 95 | + |
| 96 | +```nil |
| 97 | +hugo mod get -u |
| 98 | +``` |
| 99 | + |
| 100 | +From here on, you can follow from the step #5 from ox-hugo's quickstart i.e "Appending lines to the site config": <https://ox-hugo.scripter.co/doc/quick-start/> |
| 101 | + |
| 102 | + |
| 103 | +### Github actions {#github-actions} |
| 104 | + |
| 105 | +To setup github actions to start deploying once you commit a post to your repository on Github i.e after writing your post in `content-org` directory and exporting it via `ox-hugo` using |
| 106 | +`C-c C-e H H`, see [here](https://gohugo.io/hosting-and-deployment/hosting-on-github/#step-by-step-instructions). |
| 107 | + |
| 108 | + |
| 109 | +## References {#references} |
| 110 | + |
| 111 | +For references (or) further reading: |
| 112 | + |
| 113 | +- <https://ox-hugo.scripter.co/doc/quick-start/> |
| 114 | +- <https://ridaayed.com/posts/howto-ox-hugo-github-pages/> |
0 commit comments