Quick Start

Quick start steps from downloading hugo to writing posts in Org mode in Emacs.
  1. Once you have installed hugo, or downloaded a binary of its latest release (tested as of v0.91.2), type this to check that you have the hugo executable available:

    hugo version
    
    Code Snippet 1: Check that hugo is available

    Hugo version used when writing this post:

    hugo v0.91.2-1798BD3F linux/amd64 BuildDate=2021-12-23T15:33:34Z VendorInfo=gohugoio

  2. cd to the directory in which you want to create your Hugo site directory, and run:

    hugo new site quickstart
    cd quickstart
    
    Code Snippet 2: Create quickstart hugo site directory

    In this directory, you will find a config.toml which is referred to as the “site config” file in Hugo docs and the documentation you find on this site.

  3. Follow Installation page to ensure that ox-hugo is installed and available in your Emacs session.

  4. Pick any theme. Here we will arbitrarily pick one of the popular themes: PaperMod.

    • ✨ Using Hugo Modules ✨: This method is preferred, but requires the user to have go (at least version 1.12) installed. go download link.

      Make your Hugo site a Hugo Module (one time thing):

      hugo mod init <any string, like your repo or site URL will work, without https://>
      # example: hugo mod init github.com/user/reponame
      

      Add this to your site config:

      [module]
        [[module.imports]]
          path = "github.com/adityatelange/hugo-PaperMod"
      

      And then run this in the terminal:

      hugo mod get -u
      
    • Using git clone approach: Clone the theme repo inside a themes/ directory in your site dir.

      git clone https://github.com/adityatelange/hugo-PaperMod themes/PaperMod --depth=1
      

      Add this to your site config:

      theme = "PaperMod"
      
  5. Append these lines to the site config:

    [markup.goldmark.renderer]
      unsafe = true
    

    See the page on Goldmark for some more info on the unsafe = true setting.

  6. Create a separate directory for Org content in the Hugo site base directory – let’s call it content-org.

    # In Hugo site directory
    mkdir content-org
    
  7. Start the Hugo server in the Hugo site directory:

    hugo server --buildDrafts --navigateToChanged
    

    You will see a message like:

    Web Server is available at http://localhost:1313/

    Navigate to that address in your browser.

  8. Now, back in Emacs, with ox-hugo loaded, create a file called all-posts.org inside the content-org/ created above.

  9. Paste this in that file

    #+hugo_base_dir: ../
    
    * My first post                                             :tag1:@category1:
    :PROPERTIES:
    :EXPORT_FILE_NAME: my-first-post
    :END:
    This is my post body
    
    Code Snippet 3: Basic post in Org
  10. Take the cursor to the post heading and using the default Shift+left (S-<left>) binding to mark that subtree as DONE.

  11. Now save the file, take the cursor to the end of the post and type the bindings C-c C-e H H.

  12. You should see the site preview in your browser auto-update!

  13. Now as you make changes in your post, save and do C-c C-e H H to see the post update in the browser.

Here are some examples of Hugo sites generated with Markdown exported using ox-hugo:

Fork me on GitHub