Using headline slug as anchor breaks some features

Question

Using headline slug as anchor breaks some features

punchagan opened this issue 7 years ago · comments

We use org-hugo-slug to create a custom anchor for headlines. This creates readable, consistent anchors for headlines which don't change between exports, which is nice.

But, this breaks the TOC keyword.

I wonder if it would be a good idea to add the slugs as custom ids to headlines. Something like what these helper functions do.

(defun pc/org-hugo-set-anchor-custom-ids ()
  "Sets hugo headline anchors as custom ids on headlines."
  (interactive)
  (save-excursion
    (save-restriction
      (ignore-errors
        (org-back-to-heading :invisible-ok))
      (org-hugo--get-valid-subtree)
      (org-map-entries #'pc/add-anchor-as-custom-id "CUSTOM_ID=\"\"&EXPORT_FILE_NAME=\"\"" 'tree))))

(defun pc/add-anchor-as-custom-id ()
  "Add anchor for headline as custom id to it."
  (let* ((title (org-entry-get (point) "ITEM"))
         (slug (org-hugo-slug title)))
    (org-set-property "CUSTOM_ID" slug)))

Having these custom ids set makes it easier to link to headlines within a post using the org internal links mechanism for headlines, and also fixes the TOC keyword to work correctly.

I think it may not be a good idea for the export functions to modify the files they are exporting, but it would be nice to have the creation of these custom ids happen automatically somehow. May be add them as an after/before save hook?

Kaushal Modi · Answer 1 · Fri Oct 27 2017 18:18:38 GMT+0800 (China Standard Time)

That's an interesting case. I don't use TOC with Hugo exports, as Hugo generates one automatically.

I wonder if it would be a good idea to add the slugs as custom ids to headlines. Something like what these helper functions do. I believe I even disable toc by default in ox-hugo.

I can make that an option, but not enabled by default. But as you said, I didn't do that in the first place as I don't want to mess with the source Org file.

Btw, before I do this, can you create a branch with a test for this, with the expected .md file? That way when I export it, git diff shows me the difference between the actual and the expected export.

Also, would it help if that function can go in before export hook? If that works, we can add this to the manual.

Either way, let's start with the test case. :)

Kaushal Modi · Answer 2 · Fri Oct 27 2017 18:40:52 GMT+0800 (China Standard Time)

Just a thought.. may be temporarily advice the Org toc generation logic ..

Kaushal Modi · Answer 3 · Fri Oct 27 2017 22:27:07 GMT+0800 (China Standard Time)

I strongly believe that we shouldn't be modifying the Org file in ox-hugo.

Having these custom ids set makes it easier to link to headlines within a post using the org internal links mechanism for headlines, and also fixes the TOC keyword to work correctly.

Thinking further, this problem is a 2-part problem:

ox-hugo and TOC support
- #+TOC "worked" but by mistake :) .. ox-md was kicking in to support #+TOC. The below referred branch now supports that correctly.
- The export option toc:N was removed intentionally as I rely on the Hugo TOC feature. But I can see the Org TOC feature being useful (especially with the upcoming NOTOC feature on Org master branch .. I still haven't tested that on ox-hugo!). The same branch now supports the toc:N option too.
Org internal links mechanism for headlines.

Try out the support-org-toc branch; this aims to fix part 1 of the problem above.

Regarding part 2 of the problem, it is closely related to #30. WDYT?

Force-setting the CUSTOM_ID tag is a workaround, which I don't think ox-hugo should do. You can add the function you suggested to before-save-hook in your personal config. (Additionally it also becomes difficult to write tests accounting the before-save-hook.. I haven't even given full thought to how I would even implement that!)

Puneeth Chaganti · Answer 4 · Tue Oct 31 2017 00:03:12 GMT+0800 (China Standard Time)

Thinking further, this problem is a 2-part problem:

ox-hugo and TOC support

#+TOC "worked" but by mistake :) .. ox-md was kicking in to support #+TOC. The below referred branch now supports that correctly.

The export option toc:N was removed intentionally as I rely on the Hugo TOC feature. But I can see the Org TOC feature being useful (especially with the upcoming NOTOC feature on Org master branch .. I still haven't tested that on ox-hugo!). The same branch now supports the toc:N option too.

Org internal links mechanism for headlines.

Are you referring to this, when you say you rely on Hugo TOC feature? This appears to be a template level feature - Do you have a special template for posts which need a TOC?

Try out the support-org-toc branch; this aims to fix part 1 of the problem above.

I shall try this out, and let you know what I find.

Regarding part 2 of the problem, it is closely related to #30. WDYT?

Yes, it does seem related to #30, but I'm not sure how closely. The TOC is generated dynamically, and so I'm guessing the solution would be quite different from replacing links as discussed in the mailing list for #30.

Also, links which link to headlines in the current post are also broken -- [[* Link dest][Link to Link dest subtree]] -- which would be automatically fixed, if I end up using the CUSTOM_ID workaround.

Force-setting the CUSTOM_ID tag is a workaround, which I don't think ox-hugo should do.

I completely agree with you on this.

Puneeth Chaganti · Answer 5 · Tue Oct 31 2017 00:22:43 GMT+0800 (China Standard Time)

Are you referring to this, when you say you rely on Hugo TOC feature? This appears to be a template level feature - Do you have a special template for posts which need a TOC?

I realize I could either change my template to include the TOC conditionally, based on some metadata in the post, or create a short code that I can include in posts. But, I find the org TOC to provide much more granular control.

Kaushal Modi · Answer 6 · Tue Oct 31 2017 00:24:04 GMT+0800 (China Standard Time)

Are you referring to this, when you say you rely on Hugo TOC feature? This appears to be a template level feature - Do you have a special template for posts which need a TOC?

I just rely on an inverse Page param in my custom theme. By default, I always insert the TOC.. unless I have set a Page param notoc to true (which I haven't yet done). I do not show the TOC in the body of the post, but instead move it to the sidebar using this little JS as you see here (that's the biggest TOC of all my posts). Credit for the JS goes to @carsonip (https://github.com/carsonip/hugo-theme-minos).

The TOC is generated dynamically, and so I'm guessing the solution would be quite different from replacing links as discussed in the mailing list for #30.

Right, but once I figure out how to intercept that internal link insertion, I just need to call org-hugo-slug to generate the slug on the fly before inserting (if CUSTOM_ID is not already defined).

Also, links which link to headlines in the current post are also broken -- [[* Link dest][Link to Link dest subtree]] -- which would be automatically fixed, if I end up using the CUSTOM_ID workaround.

I believe these can be fixed once I know how to intercept at the right point and make org-hugo-slug do its thing. The CUSTOM_ID workaround is a user-level workaround.

Kaushal Modi · Answer 7 · Tue Oct 31 2017 00:25:13 GMT+0800 (China Standard Time)

I realize I could either change my template to include the TOC conditionally, based on some metadata in the post,

Yes, I do just that.. I have put a bunch of reference links in my earlier reply.

But, I find the org TOC to provide much more granular control.

I agree.. I hope that this test branch at least resolves the TOC issue.

Kaushal Modi · Answer 8 · Tue Oct 31 2017 01:33:21 GMT+0800 (China Standard Time)

(I just force-pushed by mistake (just a rebase) to support-org-toc branch, FYI.)

Puneeth Chaganti · Answer 9 · Tue Oct 31 2017 12:23:52 GMT+0800 (China Standard Time)

I agree.. I hope that this test branch at least resolves the TOC issue.

This seems to work well for me. 👍

Kaushal Modi · Answer 10 · Tue Oct 31 2017 20:01:45 GMT+0800 (China Standard Time)

Thanks for confirming, I'll merge the branch today.

As a side, would you consider publishing the Org source of your blog too? I am thinking of adding mentions of ox-hugo testers/users with links to their site Org sources.

Puneeth Chaganti · Answer 11 · Tue Oct 31 2017 21:27:19 GMT+0800 (China Standard Time)

Thanks for confirming, I'll merge the branch today.

👍

As a side, would you consider publishing the Org source of your blog too? I am thinking of adding mentions of ox-hugo testers/users with links to their site Org sources.

I have considered that, given that the sources of my blog were public previously. But, I really like the fact that keeping the org file private allows me to write and have as many draft/unpublished posts as I like in the org source file.

I could possibly write a script to copy over the org sources of all the published posts to a different file, and publish that, though.

Kaushal Modi · Answer 12 · Tue Oct 31 2017 21:30:12 GMT+0800 (China Standard Time)

have as many draft/unpublished posts as I like in the org source file.

I do that too! But I use hunk staging using Magit to commit only the part of the Org file I want :)

Puneeth Chaganti · Answer 13 · Tue Oct 31 2017 23:32:42 GMT+0800 (China Standard Time)

As a side, would you consider publishing the Org source of your blog too? I am thinking of adding mentions of ox-hugo testers/users with links to their site Org sources.

Done. You can find the source file here: https://github.com/punchagan/punchagan.muse-amuse.in/blob/master/content-org/all-posts.org

Kaushal Modi · Answer 14 · Tue Nov 07 2017 03:08:22 GMT+0800 (China Standard Time)

The TOC feature is now merged into master in f0fa731.

Documentation: https://ox-hugo.scripter.co/doc/org-toc/

Kaushal Modi · Answer 15 · Sat Nov 11 2017 03:17:37 GMT+0800 (China Standard Time)

@punchagan From your earlier post:

easier to link to headlines within a post using the org internal links mechanism for headlines

Org heading-based internal linking now works without having having to set CUSTOM_ID! (though only within the same post or valid Hugo subtree.. for now, until you, I or someone else figures out how to make it work across posts too 😄).

This was fixed in this commit (a89fb81). See the same commit for Org example.

And here's the Hugo rendered test: https://ox-hugo.scripter.co/test/posts/link-to-headings-by-name/

ChloeZhou · Answer 16 · Sun Dec 26 2021 08:46:40 GMT+0800 (China Standard Time)

@punchagan From your earlier post:

easier to link to headlines within a post using the org internal links mechanism for headlines

Org heading-based internal linking now works without having having to set CUSTOM_ID! (though only within the same post or valid Hugo subtree.. for now, until you, I or someone else figures out how to make it work across posts too 😄).

This was fixed in this commit (a89fb81). See the same commit for Org example.

And here's the Hugo rendered test: https://ox-hugo.scripter.co/test/posts/link-to-headings-by-name/

Hi, how this function work? it seems not working in my case.

Kaushal Modi · Answer 17 · Fri Dec 31 2021 17:40:20 GMT+0800 (China Standard Time)

@ChloeZhou1997 What function are you referring to? Your quoted text just says that linking to Org headings works.