Skip to content

Commit

Permalink
update: change content from feedback
Browse files Browse the repository at this point in the history
  • Loading branch information
@tcluri
tcluri committed Mar 24, 2024
1 parent f39e187 commit 556d3dc
Show file tree
Hide file tree
Showing 2 changed files with 111 additions and 35 deletions.
67 changes: 49 additions & 18 deletions content-org/all-posts.org
View file
Original file line number Diff line number Diff line change
Expand Up @@ -150,40 +150,53 @@ Quick refresher of doomemacs commands, from the commandline:


*** Enable org-mode and +hugo it
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.
In doomemacs org-mode should be enabled by default. To add ~ox-hugo~, go to your ~init.el~ file in your doom config folder. You can use ~SPC f p~ and then select by filename.

In it, enable org-mode and hugo under the ~:lang~ heading.
Under the ~:lang~ heading, look for the line with ~org~ and add ~+hugo~ like below
#+begin_src emacs-lisp
:lang
;; ... OTHER packages
;;nix ; I hereby declare "nix geht mehr!"
;;ocaml ; an objective camel
(org +hugo) ; organize your plain life in plain text
;;php ; perl's insecure younger brother
;;plantuml ; diagrams for confusing people more
:lang
;; ... OTHER packages
;;nix ; I hereby declare "nix geht mehr!"
;;ocaml ; an objective camel
(org +hugo) ; organize your plain life in plain text
;;php ; perl's insecure younger brother
;;plantuml ; diagrams for confusing people more
#+end_src

This enables [[https://ox-hugo.scripter.co/][ox-hugo]] package which exports your posts in your ~.org~ file to markdown that is readable by Hugo(which we will install now).
If you are using standard Emacs config, an equivalent config with ~use-package~ is this
#+begin_src emacs-lisp
(use-package ox-hugo
:ensure t
:pin melpa
:after ox)
#+end_src

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 [[https://github.com/doomemacs/doomemacs/tree/master/modules/lang/org][here]].
This enables [[https://ox-hugo.scripter.co/][ox-hugo]] package which exports your posts in your ~.org~ file to markdown that is readable by Hugo(which we will now install)
** Hugo
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,
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.
Go to the install [[https://go.dev/doc/install][page]] and follow the instructions, they are clear and you can confirm it is installed using ~go version~ in your terminal, the
*** Installing Golang
Go to the install [[https://go.dev/doc/install][page]] and follow the instructions, they are clear and make sure you have added ~/usr/local/go/bin~ to the PATH environment variable. Confirm it is installed using ~go version~ in your terminal, the
version should be ~1.20~ or greater since Hugo requires this.

*** Get Hugo
To install Hugo after you have installed the Go language run the following command,
#+begin_src
go install github.com/gohugoio/hugo@latest
#+end_src
This is the standard version of Hugo and not the extended edition, if you need that refer [[https://github.com/gohugoio/hugo?tab=readme-ov-file#build-from-source][here]]

You can check that hugo is installed using ~hugo version~ at the commandline.
By default, binaries are installed to the bin subdirectory of the default ~GOPATH~ (~$HOME/go~ in linux) so make sure to add it like so in your ~.bashrc~
#+begin_src
# Add go installs to PATH
export PATH="$PATH:~/go/bin"
#+end_src

In a new terminal or once you have sourced your ~.bashrc~ file, check that hugo is installed using ~hugo version~.
** Setting things up
Create an empty git repository on Github, the name of your repository should be ~<username>.github.io~
and clone it on your machine to a folder named ~blog~ or something else.

Now intialize hugo in the blog folder, use ~--force~ since it is a non-empty directory since it contains ~.git~ folder
Now intialize hugo in the blog folder, use ~--force~ since it is a non-empty directory and it contains ~.git~ folder
#+begin_src
hugo new site --force blog
#+end_src
Expand All @@ -207,11 +220,29 @@ hugo mod get -u

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/

*** Github actions
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
~C-c C-e H H~, see [[https://gohugo.io/hosting-and-deployment/hosting-on-github/#step-by-step-instructions][here]].
*** Writing a post and exporting it
Once you are done writing your post in org file residing in your ~content-org/~ directory, export it using ~C-c C-e H H~.
This will create a markdown file in ~content/~ directory with the name that you provide in the properties of the org heading
#+begin_src org
:PROPERTIES:
:EXPORT_FILE_NAME: org-doomemacs-hugo
:END:
#+end_src
Hugo reads this markdown file in the ~content/~ directory and generates the necessary contents for the site.
Commit the markdown file to your repository.

*** Auto deploy using Github actions
To setup github actions to start deploying once you commit a markdown post that gets generated in the ~content/~ directory to your repository on Github see [[https://gohugo.io/hosting-and-deployment/hosting-on-github/#step-by-step-instructions][here]].

+ Change the settings of your repository to enable Github actions
+ Create a file ~.github/workflows/hugo.yaml~ in your repository and paste the contents from the link
+ Commit this file to your repository and see the magic happen 🎉

** References
For references (or) further reading:
+ https://ox-hugo.scripter.co/doc/quick-start/
+ https://ridaayed.com/posts/howto-ox-hugo-github-pages/

** Thanks
Thanks to [[https://baali.muse-amuse.in/][Shantanu]] and [[https://github.com/punchagan][Punch]] for suggesting me to write this post and for feedback which helped clarify
things. Thank you for reading
79 changes: 62 additions & 17 deletions content/posts/org-doomemacs-hugo.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,32 +29,46 @@ Quick refresher of doomemacs commands, from the commandline:

### Enable org-mode and +hugo it {#enable-org-mode-and-plus-hugo-it}

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.
In doomemacs org-mode should be enabled by default. To add `ox-hugo`, go to your `init.el` file in your doom config folder. You can use `SPC f p` and then select by filename.

In it, enable org-mode and hugo under the `:lang` heading.
Under the `:lang` heading, look for the line with `org` and add `+hugo` like below

```emacs-lisp
:lang
;; ... OTHER packages
;;nix ; I hereby declare "nix geht mehr!"
;;ocaml ; an objective camel
(org +hugo) ; organize your plain life in plain text
;;php ; perl's insecure younger brother
;;plantuml ; diagrams for confusing people more
:lang
;; ... OTHER packages
;;nix ; I hereby declare "nix geht mehr!"
;;ocaml ; an objective camel
(org +hugo) ; organize your plain life in plain text
;;php ; perl's insecure younger brother
;;plantuml ; diagrams for confusing people more
```

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).
If you are using standard Emacs config, an equivalent config with `use-package` is this

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).
```emacs-lisp
(use-package ox-hugo
:ensure t
:pin melpa
:after ox)
```

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 now install)


## Hugo {#hugo}

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,
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.
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


### Installing Golang {#installing-golang}

Go to the install [page](https://go.dev/doc/install) and follow the instructions, they are clear and make sure you have added `/usr/local/go/bin` to the PATH environment variable. Confirm it is installed using `go version` in your terminal, the
version should be `1.20` or greater since Hugo requires this.


### Get Hugo {#get-hugo}

To install Hugo after you have installed the Go language run the following command,

```nil
Expand All @@ -63,15 +77,22 @@ go install github.com/gohugoio/hugo@latest

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)

You can check that hugo is installed using `hugo version` at the commandline.
By default, binaries are installed to the bin subdirectory of the default `GOPATH` (`$HOME/go` in linux) so make sure to add it like so in your `.bashrc`

```nil
# Add go installs to PATH
export PATH="$PATH:~/go/bin"
```

In a new terminal or once you have sourced your `.bashrc` file, check that hugo is installed using `hugo version`.


## Setting things up {#setting-things-up}

Create an empty git repository on Github, the name of your repository should be `<username>.github.io`
and clone it on your machine to a folder named `blog` or something else.

Now intialize hugo in the blog folder, use `--force` since it is a non-empty directory since it contains `.git` folder
Now intialize hugo in the blog folder, use `--force` since it is a non-empty directory and it contains `.git` folder

```nil
hugo new site --force blog
Expand Down Expand Up @@ -100,10 +121,28 @@ hugo mod get -u
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/>


### Github actions {#github-actions}
### Writing a post and exporting it {#writing-a-post-and-exporting-it}

Once you are done writing your post in org file residing in your `content-org/` directory, export it using `C-c C-e H H`.
This will create a markdown file in `content/` directory with the name that you provide in the properties of the org heading

```org
:PROPERTIES:
:EXPORT_FILE_NAME: org-doomemacs-hugo
:END:
```

Hugo reads this markdown file in the `content/` directory and generates the necessary contents for the site.
Commit the markdown file to your repository.


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
`C-c C-e H H`, see [here](https://gohugo.io/hosting-and-deployment/hosting-on-github/#step-by-step-instructions).
### Auto deploy using Github actions {#auto-deploy-using-github-actions}

To setup github actions to start deploying once you commit a markdown post that gets generated in the `content/` directory to your repository on Github see [here](https://gohugo.io/hosting-and-deployment/hosting-on-github/#step-by-step-instructions).

- Change the settings of your repository to enable Github actions
- Create a file `.github/workflows/hugo.yaml` in your repository and paste the contents from the link
- Commit this file to your repository and see the magic happen 🎉


## References {#references}
Expand All @@ -112,3 +151,9 @@ For references (or) further reading:

- <https://ox-hugo.scripter.co/doc/quick-start/>
- <https://ridaayed.com/posts/howto-ox-hugo-github-pages/>


## Thanks {#thanks}

Thanks to [Shantanu](https://baali.muse-amuse.in/) and [Punch](https://github.com/punchagan) for suggesting me to write this post and for feedback which helped clarify
things. Thank you for reading

0 comments on commit 556d3dc

Please sign in to comment.