TOC Macro - Exclude two headings with different names

[Steven Parsons]

Has anybody successfully managed to exclude headings from the TOC that have different names?  For example if I want to exclude the two following headers from my TOC

Issues

Management

what RegEx would I use?

[Steffen Heller]

You can use this:

(Issues|Management).*

[Mick Davidson]

Steffen, thank you, that worked. I agree with other people, the Confluence help for this is appalling and totally unhelpful. The help in the macro is absolutely useless and has been for years. Why this hasn't been fixed is beyond me.

[Richard Colvin]

IN fact the regex seems broken: just get "Error rendering macro 'toc' : null" applying a similar regex. 

[Luke Hart]

I agree. Atlassian's documentation that refers people to Sun's RegEx docuemntation is woefully inadequate. I think all they would need to do to appease 95% of users who just want to exclude a handful of names from the TOC list is add a few examples:

(Issues|Management)

(Issues|Management|Examples|Revision History)

A few simple examples would explain how to use the exclusion feature for the vast majority of users.

[jernandez]

Hey Luke!

I came across your post just now and thought I'd let you know that I added an example to the doc. 

Let me know what you think,

Javier.

https://confluence.atlassian.com/doc/table-of-contents-macro-182682099.html

[Luke Hart]

Just read through this topic again, and I'm not sure which example you're referring to. I don't see anything that explains the syntax (Issues|Management) used for excluding multiple headings.

@jernandez

[Deleted user]

Thanks for this. I can't believe how poor Atlassian doco is, and it still hasn't been addressed after 4 years. Pity no one is addressing this. This is a small feature, but I am wasting large amounts of time trying to do these simple things.

[Steffen Heller]

Some general thoughts:

Although regular expressions can be quite complex, a few simple rules are probably enough to know how to use them in the table of contents macro.

What is most important to know, is this:

• . is a placeholder for any kind of letter or number (a-z, A-Z, 0-9).
  That letter or number must occur exactly once.
• if * comes behind such a placeholder, it defines that that placeholder can also occur multiple times or not at all.

The combinatin of both is .* and that stands for basically every combination of numbers and letters, e.g. "a", "1", "abc", "123", "abc 123 xyz", but also "" (nothing at all = a letter or number that occurs zero times).

And so

• .*Peter.* will find any headline that includes the word "Peter".
• .*(Peter|Paul).* will find any headline that includes "Peter" or "Paul".
• .*(Peter|Paul|Mary).* will find any headline that includes "Peter" or "Paul" or "Mary" or combinations of them.
• The position of "Peter", "Paul" and "Mary" does not matter. They can be at the beginning of the headline, at the end or in between.

[Fabienne Gerhard]

Thank you so much for this amazing informations according 'include' and 'exclude' parameters in Table of Contents Macro -> Should be transferred right into documentation!

That helps a lot and offers the opportunity to find the best solution by your own.

[Jan Anderson]

WOO HOO - Steffen Heller's solution works very nicely!! Thank you!!

[Helen Gosper]

WOO HOO double!

[Richard Colvin]

Massively agree with these comments. Presumably a feature designed by a developer, not an end user.

[Helen Gosper]

An update to the doco would be useful. It's such a simple solution and should be on the TOC doco page.

[Mason Danner]

@Atlassian ditto. Wasted an hour on the help doc before finding this page

[Mick Davidson]

@Atlassian: see the complaints below and fix the documentation which is years out of date. This should be a simple task to do. users shouldn't have to "See Sun's Regex documentation for examples of constructing regular expression strings." Even if they were developers they shouldn't have to, let alone the rest of us!

[Steven Parsons]

Steffen,

thank you for the help. This was exactly what I was looking for.

Steven

[Melanie DuPont]

Following up on Steffen Heller's response from Nov 14, 2017:

To suppress "Why Are We Writing This?", I had to use Why.* in Exclude Headings. I guess question mark (?) counts as a non-letter!

[Steffen Heller]

My response from Nov 13, 2017 (perhaps Nov 14 in other parts of the world) should work:

But since ? is part of the regular expression syntax you must escape it.

Try .*\? (add \ before the ?) and it should work ;-)

In other words:

.*\? will exclude headlines that end with a question mark (?).

[Dmitriy Alekseev]

For any case read https://www.geany.org/manual/gtk/glib/glib-regex-syntax.html

For my case I need regex for exclude any paragraf that befin from space, and resolution is:

(^[\s])

[Alexander Suvorov]

In my case I had to exclude headings "Date" and "Table of Content". This is what I entered in the "Exclude Headings" field and that worked:

Date|Table of Contents

Notes:

• There's no need to surround this RegEx string into parenthesis (unless you use them intentionally for complex RegEx code)
• Don't put any non-headings-related blanks in the RegEx string (e.g. around vertical bar "I" character) as these will be treated as part of RegEx code

[Fabienne Gerhard]

Worked perfect for me - thanks to @Steffen Heller

-> Maybe you can also help me with a problem belonging to this trouble here 

1. I used the Question Macro to show the Recent Question for a topic
2. Used  (Recent).* in Exclude Heading to get rid off the Question Heading  in TOC
3. Now i also want to exclude the recent Question in TOC!

Problem:

I can't use a specific word, there are several questions on the page which start with different words -> is there an opportunity to exclude h2 after the used (Recent).* excluding?

Thanks!

[Steffen Heller]

Complex question, To make it short, I don't think that what you want is possible as those regular expressions only refer to the headline text but not any kind of underlying source code.

Possible workaround?

Would it be possible to add a consistent prefix to the questions e.g. having all questions start with "Q:"?

PS: I am not an expert on that, just a normal user that was searching for a solution and posted it here (years ago ;-))

[Fabienne Gerhard]

Thanks for your answer!

No expert? That's impossible ;) because you solved a problem many people had.

Workaround sounds good, but i'm afraid that starting with a certain kind of letter is impossible. 

But I will try and post my results! 

[Fabienne Gerhard]

Made a workworkaround:

1. Switched all heading 2 to heading 1
2. Changed heading 3 to heading 2
3. Used (Recent).* in  Exclude Heading
4. Used minlevel 1 and maxlevel 2

Not very elegant, but worked. So all questions (which have heading 3) will not be shown.

I tried exclude with a certain ending (in my case '?' -> because all questions should end with ?) by using .*? -> did  not work

[Steffen Heller]

The question mark idea is good.

But since ? is part of the regular expression syntax you must escape it.

Try .*\? (add \ before the ?) and it should work ;-)

[Fabienne Gerhard]

Wohoo - worked perfect - combined both and now it's perfect (as long as all questions end with ?)

Looks like this now:

{toc:exclude=(Recent).*|.*\?}

Or just as text in the exclude macro: (Recent).*|.*\?

Thank you so much for your help @Steffen Heller - saved my day! 

[Steffen Heller]

You are welcome. I am glad to help.

[Yousaf]

Hello Steffen, 

just saw this post. Can I also exclude the title of the document?

Because the title is H1, and other headings are also H1, the document looks like this when exported as pdf:

1. Title of document

1.1 Bla

1.1.1 Blabla

1.1.2 Blablabla

1.2 Blu

1.2.1 Blublu

etc etc.. 

Because of the h1 in the title the whole document numbering is wrong. And I tried h2 and h3 then excluded h1 but then h3 numbering is not shown at all. 

[Steffen Heller]

I am afraid I cannot fully follow your explanation. Specifically, I don't understand in what way the h1 in the title makes the numbering wrong.

Can you explain the following:

What do you mean by "title"?

The first heading in the page (= your "1. Title of document") or the page name?

And how do you export to PDF?

With Tools > Export to PDF or with Browse > Space Admin > PDF Export

And just to be sure:
Are you talking about the TOC macro or do make space exports and use the "normal" TOC that is a part of that?

[Yousaf]

Title= Page Name

I export from the page directly: Tools > Export to PDF

But I also tried exporting it from Space Operations > PDF Export > Custom Export. 

I´m talking about the Toc Macro ;) 

[Fabienne Gerhard]

Hi Yousaf,

i tried to reproduce your problem. As you can see on the pic, page title is never a part of TOC.

How did you produce numbering in the page title?

How did you create the numbering in TOC:

• by using Display Section Numbering (selected)
• by using List Style (decimal)
• manually?

Maybe this creates the problem - even if it doesn't explain the numbering and appearing for page title.

Another option could be a Confluence Theme running in background that influences list style and/or pdf export

[Steffen Heller]

@Yousaf

There is still something missing between your explanation and our understanding ;-)

Screenshots would probably help. One of the page, one of the PDF, should make your topic clear.

[Eric Wersel]

Maybe the  ‘Table of Content Zone’ macro will work better for you than the "Table of Contents' macro? It creates a TOC only for the enclosed document.

[Jen Dye]

This solved my woes. Thank you.

[Steven Parsons]

I wish  I need to keep them just exclude them from the TOC. I have seen examples of excluding one heading, but not two.

[Hugh Bathurst]

Not as simple as taking those entries off Heading 1 I guess?