16

Q: How can I tell org-mode to exclude specific headlines from the table of contents when exporting?

For example, exporting

* Headline 1: Put me in TOC
* Headline 2: Put me in TOC
* Headline 3: DO NOT put me in TOC

to HTML produces

...
<div id="text-table-of-contents">
  <ul>
    <li><a href="#sec-1">1. Headline 1: Put me in TOC</a></li>
    <li><a href="#sec-2">2. Headline 2: Put me in TOC</a></li>
    <li><a href="#sec-3">3. Headline 3: DO NOT put me in TOC</a></li>
  </ul>
</div>
...

but I want it to produce

...
<div id="text-table-of-contents">
  <ul>
    <li><a href="#sec-1">1. Headline 1: Put me in TOC</a></li>
    <li><a href="#sec-2">2. Headline 2: Put me in TOC</a></li>
  </ul>
</div>
...

The Table of contents section of the org-mode manual doesn't have any information on this.

Also, I know that I can keep org-mode from exporting headlines by setting the COMMENT keyword via C-c ; (org-toggle-comment) or by tagging them with :noexport:. While this does keep affected headlines from showing up in the TOC, it also causes their contents to be omitted from the resulting document, which is not what I want.

2
  • 1
    This isn't the answer you're looking for, but just as a note of another dead-end: EXPORT_OPTIONS: toc:nil almost does what you want, but only when you export only just the subtree. To clarify, do you want the section to still be numbered, or do you want something akin to LaTeX's \section*? Nov 13, 2014 at 13:25
  • @SeanAllred I'd like the section to still be numbered. More generally, I don't want to change anything about the way individual sections are exported. I just don't want some of them to show up in the TOC.
    – itsjeyd
    Nov 13, 2014 at 17:06

1 Answer 1

14

Note that as of 2014-10-03 20:06:34 (GMT) check of UNNUMBERED is built-in already

Org uses org-export-collect-headlines to collect headlines that should be in the TOC. This function already includes two criteria for excluding headlines: the headline depth and whether it is a "footnote section" (*), so it is easy to add another one.

See the modified version of org-export-collect-headlines below. This version makes it possible to prevent a headline from showing up in the TOC by setting the NOTOC property.

* Section 1: shows up in the TOC

* Section 2: modified Org code (not in the TOC)
  :PROPERTIES:
  :NOTOC:    t
  :END:

  This is the modified =org-export-collect-headlines=:

  #+BEGIN_SRC elisp
  (defun org-export-collect-headlines (info &optional n)
    "Collect headlines in order to build a table of contents. [...]

  Return a list of all exportable headlines as parsed elements.
  Footnote sections, if any, will be ignored."
    (let ((limit (plist-get info :headline-levels)))
      (setq n (if (wholenump n) (min n limit) limit))
      (org-element-map (plist-get info :parse-tree) 'headline
        #'(lambda (headline)
            (unless (or (org-element-property :NOTOC headline)               ; new condition
                        (org-element-property :footnote-section-p headline)) ; old condition
              (let ((level (org-export-get-relative-level headline info)))
                (and (<= level n) headline))))
        info)))
  #+END_SRC

** Sub-section
   This shows up in the TOC: property inheritance is off by default.

(*) I don't know what "footnote sections" are, though.

This works for export backends that build the TOC manually. LaTeX, Beamer, and Texinfo backends don't.

By adding this advice to org-export-numbered-headline-p one can make headlines with the UNNUMBERED property export as \section*{...}, excluding them from TOC when exporting to LaTeX and Beamer:

(advice-add 'org-export-numbered-headline-p :around
            (lambda (orig headline info)
              (and (funcall orig headline info)
                   (not (org-element-property :UNNUMBERED headline)))))
10
  • 1
    Thanks, this works fine for HTML exports. I actually also need this to work for LaTeX/Beamer; I didn't mention this initially because I assumed that there had to be a generic solution that would work for all (or at least most) export back-ends... Do you have any idea how to tackle this issue for LaTeX export? Comparing .html and .tex files that org-mode produces when exporting, the main problem seems to be that org-mode builds the TOC manually for HTML, but simply dumps a generic \tableofcontents into the .tex file.
    – itsjeyd
    Nov 14, 2014 at 9:18
  • @itsjeyd: I don't think a generic solution is possible: as you said, LaTeX (and beamer, and Texinfo) export backends use native commands to build TOC while other backends build TOC manually. It is possible to exclude a section from TOC in LaTeX, but I haven't found a solution that is accepted by the community as the right one. Using the idea I linked to in org-mode export code would require major changes to org-latex-headline. As for implementing this in the Texinfo backed, I even don't know where to start. Nov 15, 2014 at 6:23
  • OK, thanks a lot for for following up. For Beamer, I think I'll just resort to making the sections I don't want to show up in the TOC unnumbered. Case closed. :)
    – itsjeyd
    Nov 15, 2014 at 9:12
  • @itsjeyd: You can modify org-export-numbered-headline-p to get this behavior almost automatically -- if turning it into a unnumbered section is an option, that is. I can elaborate if you're interested. Nov 15, 2014 at 17:37
  • Please do - always interested in simplifying solutions!
    – itsjeyd
    Nov 15, 2014 at 17:41

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.