Support :target attribute for #+toc keyword

[asthagiri]

Actual Behavior

To place a TOC at a specific location, I inserted: #+toc: headlines 3 :target #reading-material

It produces the expected behavior when I use org-export to produce HTML.

However, when I use ox-hugo, the Message buffer shows the following error when it reaches the subtree containing the #+toc: .... statement:
org-hugo-keyword: Wrong type argument: char-or-string-p, nil

Expected Behavior

How to Reproduce the Issue

Below is a simplified version of the org file:

* Reading
:PROPERTIES:
:EXPORT_HUGO_SECTION: reading
:EXPORT_OPTIONS: toc:3 num:3
:CUSTOM_ID: reading-material
:END:

** landing page
:PROPERTIES:
:EXPORT_FILE_NAME: _index
:EXPORT_TITLE: blah blah
:HUGO_MENU: :menu main
:END:

#+toc: headlines 3 :target #reading-material

** first subsection in Reading
:PROPERTIES:
:CUSTOM_ID: asdfasdf
:EXPORT_FILE_NAME: asdfasdf
:END:

Example Org File

Generated Markdown File or Error

Ox-Hugo Debug Information

Debug Info

[kaushalmodi]

Hello, I will review how ox-html supports the :target attribute and attempt to port it to ox-hugo.

[kaushalmodi]

Hello, the issue is auto-closed as I linked it to the commit implementing this feature. But feel free to comment here if the TOC :target is not working for you.

You can find the ox-hugo test added for this feature in 082f229.

The ox-hugo exported Markdown is here and the Hugo rendered output of that test is on https://ox-hugo.scripter.co/test/posts/toc-target/ .

[asthagiri]

Strangely, still not working on my end. I updated my ox-hugo installation to version 20200911.453 through MELPA. I confirmed that the new ox-hugo.el contains updated code as shown at 082f229

[kaushalmodi]

still not working on my end

ox-hugo test suite is passing. So it's certainly working in the remote environment on Travis CI. Unfortunately I cannot help fix this if I cannot reproduce the issue locally.

I will leave this issue open until you have figured it out.

[asthagiri]

Still working on troubleshooting... the error I get now is different from the OP. Now, the error is:

user-error: Unable to resolve link: "targetname"

Strangely, it still works fine on regular org-export to HTML.

Below is my full org-mode file:

#+TITLE: test site
#+AUTHOR: tester
#+EMAIL: [email protected]
#+DATE: 2020
#+LANGUAGE: en

#+HUGO_BASE_DIR: ./public/bioe3380fa20
#+HUGO_SECTION: /
#+HUGO_MENU: :menu main

#+LATEX_HEADER: \usepackage{mhchem}

#+HTML_MATHJAX: align: left indent: 5em tagside: left font: Neo-Euler
#+HTML_MATHJAX: cancel.js noErrors.js


* Home Page
:PROPERTIES:
:EXPORT_FILE_NAME: _index
:EXPORT_HUGO_TYPE: homepage
:END:

Hi this is the home page

Bookmark this site for convenience.


* Foreward
:PROPERTIES:
:EXPORT_FILE_NAME: foreward
:ID: forewardID
:END:

# :EXPORT_OPTIONS: toc:nil num:nil

# this is just some commentary in my org file

** sub1-foreward
thanks to family

I have some math: $\xi = e^2$

** sub2-foreward
thanks to pets


* The Heart of the Book
:PROPERTIES:
:EXPORT_HUGO_SECTION: heart
:END:

** landing page
:PROPERTIES:
:EXPORT_FILE_NAME: _index
:EXPORT_TITLE: heartmatter
:END:



** Chapter One
:PROPERTIES:
:CUSTOM_ID: chapter-1
:EXPORT_FILE_NAME: chapter1
:EXPORT_HUGO_MENU: :menu 
:EXPORT_HUGO_PUBLISHDATE: 2020-09-10
:END:



some front matter for Ch1

*** Section 1.1
now we get into it

*** Section 1.2
some more stuff

** Chapter Two
:PROPERTIES:
:CUSTOM_ID: chapter-2
:EXPORT_FILE_NAME: chapter2
:EXPORT_HUGO_MENU: :menu 
:EXPORT_HUGO_PUBLISHDATE: 2020-09-17
:END:

#+toc: headlines 3 :target #chapter-1

some front matter for Ch2

*** Section 2.1
now we get into it

*** Section 2.2
some more stuff

[kaushalmodi]

Hello,

Sorry for the late reply, but I just found some time to look into this.

The reason your example won't export is that you are trying to inject the toc from a different export scope (different post subtree) into the current export scope.

You have:

** Chapter Two
:PROPERTIES:
:CUSTOM_ID: chapter-2
:EXPORT_FILE_NAME: chapter2
:EXPORT_HUGO_MENU: :menu 
:EXPORT_HUGO_PUBLISHDATE: 2020-09-17
:END:

#+toc: headlines 3 :target #chapter-1

When I try to export the "chapter-2" post, I see this error, which I expect:

org-export-data: Unable to resolve link: "chapter-1"

It's because the Org exporter "looks" only within the scope of that subtree and it's unable to find the #chapter-1 reference -- it's present in outside the current export scope.

Strangely, it still works fine on regular org-export to HTML.

You will get the same error with HTML export as well. Try putting the point somewhere in the ** Chapter Two subtree, like on the #+toc: headlines 3 :target #chapter-1 line and do C-c C-e C-s h o. The C-s will do a subtree-scope export just as ox-hugo does. And you will see the same error

---

What does this mean?

It's a limitation of the Org exporter and we cannot export one subtree which has references outside the scope of that. So this request cannot be supported by ox-hugo.

You should be able to work this out using a custom Hugo shortcode or page template though. You can call a shortcode to inject a TOC from a different page (chapter 1 in your example). Reach out on the Hugo Discourse forum for help on this.

I'll close this issue as the basic toc :target feature works when the target is in the current export scope. While the issue is closed, you can still comment and we can continue the discussion if you are still interested in this.