Hugo w/Org Mode

I'm transitioning to hugo from the custom python and org-export scripts tangled in org-mode /readme! I want to remove barriers to getting text out 1, streamline exported org style control, and get better RSS support.

Initially, the reports and publishing system itself were an effort to experiment with literate programming. I couldn't find publishing tools that easily also executed babel and tangled files.

But my literate programming effort has been complicated. tangling code from org files has consistently been too much overhead. In part, this is because I wasn't able to adequately commit: I forgot to look to org file when returning to the project. But more of a hurdle are the normal transpiling reasons. Error messages are on different line numbers and tools jump to the offending file, not the org source block. Additionally, generating consistent html header ids requires custom elisp.

Org-mode still seems like the best way to write reports. And hugo supports (a subset) of the format.

I like markdown syntax better and mkdocs-material has some very nice features (code annotations!). But I haven't yet found a compelling markdown interface to compete with org-babel. Despite the time it takes to figure out the right src_block headers, quick figure generating and embedding is still a win for org-mode.

Notes

  • Using hugo/go-org over ox-hugo because of the same aforementioned transpiling issues. hugo server live updates are also nice. It wouldn't be too bad to need make in the middle. But why add more tech to the pipeline?

  • go-org doesn't yet support easy internal linking: https://github.com/niklasfasching/go-org/issues/32

  • reworked images with config.toml mount so org and the exported files share ../images. (rewrote links in /netflix and /org-codealias)

  • minimal theme with index.html, layouts/_default/page.html, and static/css/style.css

    • page.html not single.html

    > found no layout file for "HTML" for kind "page": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.

    • can probably move theme files back into main hugo and reduce file tree

Inter-site links

slightly adapted from https://kisaragi-hiu.com/links-in-both-hugo-and-org/

(defun k/alternate-path-element-wrapper (parser)
  "Make `org-element-link-parser' try the relative directory and add `.org'.
PARSER is `org-element-link-parser', passed in by the :around advice.
Modified from https://kisaragi-hiu.com/links-in-both-hugo-and-org/"
  (let* ((elem (funcall parser))
         (path (org-element-property :path elem)))
    (when (and (equal "file" (org-element-property :type elem))
               (stringp path)
               (f-absolute? path)
               (not (f-exists? path)))
      (-when-let* ((base (f-relative path "/"))
                   (newpath (concat base ".org"))
                   (exists (f-exists? newpath)) ;not used but if false, below not run
                  )
        (setq elem (org-element-put-property elem :path newpath))))
    elem))

(advice-add 'org-element-link-parser :around #'k/alternate-path-element-wrapper)

Using Custom ID

this section defines a custom id ustingcustomid. org-mode looks like

 ** Using Custom ID
:PROPERTIES:
:CUSTOM_ID: Using_Custom_ID
:END:
[fn:1] Here's a foot note

Here's a writeup outlining an elisp function to add custom ids.


(defun my/org-custom-id-from-header (&optional pom)
  "Create a custom_id property from the header.
Use header for POM (point of marker; when nil point)."
  (interactive)
  (org-with-point-at pom
    (-when-let* ((id (car (last (org-get-outline-path t))))
                 (id (string-replace " " "_" id)))
      (message id)
      (message pom)
      (org-entry-put pom "CUSTOM_ID" id)
      (org-id-add-location id (buffer-file-name (buffer-base-buffer))))))

Mounts

tail -n6 ../hugo/config.toml
[[module.mounts]]
  source = '../reports/'
  target = 'content'
[[module.mounts]]
  source = "../images/"
  target = "static/images"

Files

tree ../hugo -I public
../hugo
├── archetypes
│   └── default.md
├── assets
├── config.toml
├── content -> ../reports
├── data
├── layouts
├── resources
│   └── _gen
│       ├── assets
│       └── images
├── static
└── themes
    └── wf
        ├── archetypes
        │   └── default.md
        ├── layouts
        │   ├── 404.html
        │   ├── _default
        │   │   ├── baseof.html
        │   │   ├── list.html
        │   │   ├── page.html -> single.html
        │   │   └── single.html
        │   ├── index.html
        │   └── partials
        │       ├── footer.html
        │       ├── header.html
        │       └── head.html
        ├── LICENSE
        ├── static
        │   ├── css
        │   │   └── style.css
        │   └── js
        └── theme.toml

20 directories, 15 files
1

like ensuring the laptop's version of org-export doesn't change header ids

2

Here's a foot note


..