{"id":13653287,"url":"https://github.com/kaushalmodi/ox-hugo","last_synced_at":"2025-05-14T19:09:31.593Z","repository":{"id":37359661,"uuid":"81684869","full_name":"kaushalmodi/ox-hugo","owner":"kaushalmodi","description":"A carefully crafted Org exporter back-end for Hugo ","archived":false,"fork":false,"pushed_at":"2025-02-12T19:36:50.000Z","size":8425,"stargazers_count":906,"open_issues_count":46,"forks_count":130,"subscribers_count":20,"default_branch":"main","last_synced_at":"2025-05-10T06:34:47.386Z","etag":null,"topics":["blackfriday","blog","commonmark","elisp","emacs","emacs-lisp","exporter","goldmark","hugo","markdown","org","org-mode","static-site-generator"],"latest_commit_sha":null,"homepage":"https://ox-hugo.scripter.co","language":"Emacs Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kaushalmodi.png","metadata":{"files":{"readme":"README.org","changelog":"CHANGELOG.org","contributing":"CONTRIBUTING.org","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-02-11T21:53:04.000Z","updated_at":"2025-05-04T09:22:03.000Z","dependencies_parsed_at":"2024-01-14T14:29:34.930Z","dependency_job_id":"faa96afa-5001-45ef-be1d-254c6e49d5f8","html_url":"https://github.com/kaushalmodi/ox-hugo","commit_stats":{"total_commits":1704,"total_committers":60,"mean_commits":28.4,"dds":0.06455399061032863,"last_synced_commit":"c4156d9d383bf97853ba9e16271b7c4d5e697f49"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaushalmodi%2Fox-hugo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaushalmodi%2Fox-hugo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaushalmodi%2Fox-hugo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaushalmodi%2Fox-hugo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kaushalmodi","download_url":"https://codeload.github.com/kaushalmodi/ox-hugo/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254209859,"owners_count":22032897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blackfriday","blog","commonmark","elisp","emacs","emacs-lisp","exporter","goldmark","hugo","markdown","org","org-mode","static-site-generator"],"created_at":"2024-08-02T02:01:08.251Z","updated_at":"2025-05-14T19:09:30.877Z","avatar_url":"https://github.com/kaushalmodi.png","language":"Emacs Lisp","funding_links":[],"categories":["Emacs Lisp"],"sub_categories":[],"readme":"#+title: Ox-Hugo: A carefully crafted Org exporter back-end for Hugo\n#+author: Kaushal Modi\n[[https://github.com/kaushalmodi/ox-hugo/actions][https://github.com/kaushalmodi/ox-hugo/actions/workflows/test.yml/badge.svg]] [[https://melpa.org/#/ox-hugo][file:https://melpa.org/packages/ox-hugo-badge.svg]] [[https://www.gnu.org/licenses/gpl-3.0][https://img.shields.io/badge/License-GPL%20v3-blue.svg]]\n\n/If you have any questions or if you have anything interesting to\nshare related to ox-hugo, feel free to do so on [[https://github.com/kaushalmodi/ox-hugo/discussions][Discussions]]!/\n\n=ox-hugo= is an Org exporter backend that exports Org to\n[[https://gohugo.io/][Hugo]]-compatible Markdown ([[https://github.com/russross/blackfriday][Blackfriday]]) and also generates the\nfront-matter (in TOML or YAML format).\n\nThe =ox-hugo= backend extends from a /parent/ backend\n=ox-blackfriday.el=. The latter is the one that primarily does the\nBlackfriday-friendly Markdown content generation. The main job of\n=ox-hugo= is to generate the front-matter for each exported content\nfile, and then append that generated Markdown to it.\n\nThere are, though, few functions that =ox-hugo.el= overrides over\nthose by =ox-blackfriday.el=.\n\n-----\nSee the [[https://ox-hugo.scripter.co/doc/examples/][Real World Examples]] section to quickly jump to sites generated\nusing =ox-hugo= and their Org sources.\n* Table of Contents\n- [[#screenshots][Screenshots]]\n- [[#documentation][Documentation]]\n  - [[#source-of-the-documentation-site][Source of the Documentation site]]\n- [[#demo][Demo]]\n- [[#installation][Installation]]\n  - [[#use-package][Use Package]]\n  - [[#spacemacs][Spacemacs]]\n- [[#usage][Usage]]\n  - [[#before-you-export][Before you export]]\n  - [[#export-bindings][Export bindings]]\n  - [[#customization-options][Customization Options]]\n- [[#thanks][Thanks]]\n\n* Screenshots\nBefore you read further, you can see below how =ox-hugo= translates\nOrg to Markdown (Org on the left; exported Markdown with Hugo\nfront-matter on the right).\n** One post per Org subtree (preferred)\n[[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/main/doc/static/images/one-post-per-subtree.png][https://raw.githubusercontent.com/kaushalmodi/ox-hugo/main/doc/static/images/one-post-per-subtree.png]]\n- Files in above screenshot :: [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/main/test/site/content-org/screenshot-subtree-export-example.org][Org]] -\u003e [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/main/test/site/content/writing-hugo-blog-in-org-subtree-export.md][Markdown]]\n** One post per Org file\n[[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/main/doc/static/images/one-post-per-file.png][https://raw.githubusercontent.com/kaushalmodi/ox-hugo/main/doc/static/images/one-post-per-file.png]]\n- Files in above screenshot :: [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/main/test/site/content-org/writing-hugo-blog-in-org-file-export.org][Org]] -\u003e [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/main/test/site/content/writing-hugo-blog-in-org-file-export.md][Markdown]]\n** Editorial\nThe preferred way to organize the posts is as Org subtrees (also the\nmain reason to write this package, as nothing like that was out there)\nas it makes the meta-data management for Hugo front-matter pretty\neffortless.\n\nIf you are a /one Org-file per post/ type of a person, that flow works\ntoo! Just note that in this flow many of those =#+hugo_= properties\nneed to be managed manually.. just as one would manage the front-matter\nin Markdown files --- See the Org versions in the above screenshots for\ncomparison.\n* Documentation\n=ox-hugo= uses *itself* to generate its documentation!\n\nhttps://ox-hugo.scripter.co/\n\nYou can generate the same too! Simply clone this repo and do =make\ndoc_md=.\n\n*Make sure you visit the above link to read more on:*\n- [[https://ox-hugo.scripter.co/doc/why-ox-hugo/][Why =ox-hugo=?]]\n- [[https://ox-hugo.scripter.co/doc/auto-export-on-saving/][Auto exporting to Markdown each time the Org file is saved]]\n- [[https://ox-hugo.scripter.co/doc/org-capture-setup/][Using Org Capture to start a new blog post]]\n- .. and many more topics and examples\n** Source of the Documentation site\n- [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/main/doc/ox-hugo-manual.org][Org source]]\n\nThe documentation site is published by first using =ox-hugo= to\nexport from Org to Markdown, and then finally =hugo=.\n/So no Markdown files are committed in the =doc/content/= directory./\n* Demo\n[[https://github.com/kaushalmodi/ox-hugo/tree/main/test/site/content-org][Org source]] → [[https://github.com/kaushalmodi/ox-hugo/tree/main/test/site/content][=ox-hugo= Exported Markdown]] → [[https://ox-hugo.scripter.co/test/]]\n\nThe test site uses a [[https://github.com/kaushalmodi/hugo-bare-min-theme][minimal]] theme written just for debug purposes\n(not extra aesthetics). The test site is designed to verify if all the\ncontent translates from Org to Markdown as expected.\n\n/See [[https://themes.gohugo.io/][Hugo Themes]] for examples of really good site prettification and\npresentation styles./\n* Installation\nThis package requires at least GNU Emacs *26.3* and\nOrg Mode *9.0*. It is available on Melpa\n([[https://melpa.org/#/ox-hugo]]), and it's recommended to install this\npackage from [[https://melpa.org/#/getting-started][Melpa]] (​_not_ Melpa /Stable/).\n\nYou will need to /require/ the package after installing it to get the\n=ox-hugo= export options in the /Org Export Dispatcher/ menu (the one\nyou see when you hit =C-c C-e= to initiate any export).\n\nYou can do that by adding the below to your config:\n#+begin_src emacs-lisp\n(with-eval-after-load 'ox\n  (require 'ox-hugo))\n#+end_src\n** Use Package\nIf you use [[https://github.com/jwiegley/use-package][=use-package=]], you can do the below instead:\n#+begin_src emacs-lisp\n(use-package ox-hugo\n  :ensure t   ;Auto-install the package from Melpa\n  :pin melpa  ;`package-archives' should already have (\"melpa\" . \"https://melpa.org/packages/\")\n  :after ox)\n#+end_src\n** Spacemacs\nSpacemacs users can use =ox-hugo= by setting the variable\n=org-enable-hugo-support=.\n\n#+begin_src emacs-lisp\n(setq-default dotspacemacs-configuration-layers\n              '((org :variables\n                  org-enable-hugo-support t)))\n#+end_src\n\n/This was verified to work on Spacemacs =develop= branch ([[https://github.com/kaushalmodi/ox-hugo/pull/440][ref]])./\n* Usage\n#+begin_note\nJump to the [[https://ox-hugo.scripter.co/doc/quick-start/][Quick Start]] section to quickly try\nout ~ox-hugo~ with Hugo.\n#+end_note\n** Before you export\nBefore you export check that these properties are set as you need:\n- HUGO_BASE_DIR :: Root directory of the source for the Hugo site. If\n     this is set to =~/hugo/=, the exported Markdown files will be saved\n     to =~/hugo/content/\u003cHUGO_SECTION\u003e/= directory[fn:-0-section_more].  By\n     default, the Markdown files reside in a hierarchy under the\n     =content/= directory in the site root directory ([[https://gohugo.io/content-management/organization/][ref]]).\n\n     If you try to export without setting this property, you will get\n     this error:\n     #+begin_example\n       user-error: It is mandatory to set the HUGO_BASE_DIR property\n                   or the `org-hugo-base-dir' local variable\n     #+end_example\n     This property can be set by one of two ways:\n  1. Setting the ~#+hugo_base_dir:~ keyword in the Org file.\n  2. Setting the ~org-hugo-base-dir~ variable in a ~.dir-locals.el~ or\n     File Local Variables.\n\n- HUGO_SECTION :: The default Hugo section name for all the posts.\n     See [[https://gohugo.io/content-management/sections/][here]] for more information on Hugo sections.  It is common for\n     this property to be set to =posts= or =blog=.  The default value is\n     set using =org-hugo-default-section-directory=. See\n     [[https://ox-hugo.scripter.co/doc/hugo-section/][Hugo Section]] for details.\n\n*Important*: If you choose to export an Org subtree as a post, you\n need to set the =EXPORT_FILE_NAME= subtree property. That property is\n used by this package to figure out where the current post starts. For\n that reason, *a subtree with =EXPORT_FILE_NAME= property cannot nest\n another subtree with that property*. If you can analogize with the\n [[https://en.wikipedia.org/wiki/Tree_(data_structure)][branch/leaf data structure terminlogy]], then the subtrees with\n =EXPORT_FILE_NAME= property need to be /leaf nodes/.\n\n[fn:-0-section_more] The ~HUGO_SECTION~ is the bare-minimum requirement\nto specify the destination path. That path can be further tweaked\nusing ~HUGO_BUNDLE~ key (and the associated ~EXPORT_HUGO_BUNDLE~\nproperty), and the ~EXPORT_HUGO_SECTION_FRAG~ property (only for\n/per-subtree/ exports).\n** Export bindings\nThe common =ox-hugo= export bindings are:\n*** For both one-post-per-subtree and one-post-per-file flows\n- =C-c C-e H H= :: Export \"What I Mean\". This is same as calling the\n     ~org-hugo-export-wim-to-md~ function interactively or via\n     ~(org-hugo-export-wim-to-md)~ in Emacs Lisp.\n  - If point is in a /valid Hugo post subtree/, export that\n    subtree to a Hugo post in Markdown.\n\n    A /valid Hugo post subtree/ is an Org subtree that has the\n    =EXPORT_FILE_NAME= property set. *Note that a subtree with\n    =EXPORT_FILE_NAME= property cannot nest a subtree with the same\n    property set.* If you can analogize with the [[https://en.wikipedia.org/wiki/Tree_(data_structure)][branch/leaf data\n    structure terminlogy]], then the subtrees with =EXPORT_FILE_NAME=\n    property need to be /leaf nodes/.\n  - If the file is intended to be exported as a whole (i.e. has the\n    =#+title= keyword), export the whole Org file to a Hugo post in\n    Markdown.\n- =C-c C-e H A= :: Export *all* \"What I Mean\". This is same as\n     executing ~(org-hugo-export-wim-to-md :all-subtrees)~ in Emacs Lisp.\n  - If the Org file has one or more 'valid Hugo post subtrees', export\n    them to Hugo posts in Markdown.\n  - If the file is intended to be exported as a whole (i.e. no 'valid\n    Hugo post subtrees' at all, and has the =#+title= keyword), export\n    the whole Org file to a Hugo post in Markdown.\n*** For only the one-post-per-file flow\n- =C-c C-e H h= :: Export the Org file to a Hugo post in\n     Markdown. This is same as calling the ~org-hugo-export-to-md~\n     function interactively.\n\n/Also see the [[https://ox-hugo.scripter.co/doc/auto-export-on-saving/][Auto Exporting]]\nsection./\n** Customization Options\nDo =M-x customize-group=, and select =org-export-hugo= to see the\navailable customization options for this package.\n* Thanks\n- Matt Price ([[https://github.com/titaniumbones][@titaniumbones]])\n- Puneeth Chaganti ([[https://github.com/punchagan][@punchagan]])\n- Also thanks to\n  ~http://whyarethingsthewaytheyare.com/setting-up-the-blog/~ (/not\n  hyperlinking the link as it is insecure --- not https/),\n  ~http://www.holgerschurig.de/en/emacs-blog-from-org-to-hugo/~ (/not\n  hyperlinking the link as it is insecure --- not https/) and the\n  [[https://github.com/chaseadamsio/goorgeous][=goorgeous=]] project by Chase Adams ([[https://github.com/chaseadamsio][@chaseadamsio]]) for inspiration\n  to start this project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaushalmodi%2Fox-hugo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkaushalmodi%2Fox-hugo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaushalmodi%2Fox-hugo/lists"}