Quick Start

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:

• ox-hugo documentation site (you’re reading it)
• ox-hugo test site
• scripter.co – My blog