* Document top-level heading

This is an example of a complex document.  To see the Org syntax, view the [[https://raw.githubusercontent.com/alphapapa/org-make-toc/master/example.org][raw version]] of this file.

** Main ToC: Itself excluded
:PROPERTIES:
:TOC:      :include all :ignore this
:END:

This heading itself is excluded from its TOC.

:CONTENTS:
- [[#document-top-level-heading][Document top-level heading]]
  - [[#chapter-1-inline-toc][Chapter 1: Inline TOC]]
    - [[#section-1a][Section 1a]]
      - [[#subsection-1a1][Subsection 1a1]]
      - [[#subsection-1b1-included-despite-its-excluded-parent][Subsection 1b1: Included, despite its excluded parent]]
  - [[#chapter-2-toc-as-sibling][Chapter 2: TOC as sibling]]
    - [[#chapter-2-toc][Chapter 2 TOC]]
    - [[#section-2a][Section 2a]]
      - [[#subsection-2a1][Subsection 2a1]]
    - [[#section-2b-child-is-excluded][Section 2b: Child is excluded]]
  - [[#chapter-3-toc-as-parent][Chapter 3: TOC as parent]]
    - [[#chapter-3-toc][Chapter 3 TOC]]
      - [[#section-3a][Section 3a]]
        - [[#subsection-3a1][Subsection 3a1]]
      - [[#section-3b][Section 3b]]
        - [[#subsection-3b1][Subsection 3b1]]
  - [[#chapter-4-limited-depth][Chapter 4: Limited depth]]
    - [[#section-4a][Section 4a]]
    - [[#section-4b][Section 4b]]
  - [[#chapter-5-local-settings][Chapter 5: Local settings]]
    - [[#section-5a][Section 5a]]
      - [[#section-5a1][Section 5a1]]
      - [[#section-5a2][Section 5a2]]
    - [[#section-5b][Section 5b]]
      - [[#section-5b1][Section 5b1]]
    - [[#section-5c][Section 5c]]
      - [[#section-5c1][Section 5c1]]
        - [[#section-5c1a][Section 5c1a]]
        - [[#section-5c1b][Section 5c1b]]
  - [[#appendices][Appendices]]
    - [[#appendix-a-comprehensive-toc][Appendix A: Comprehensive TOC]]
    - [[#appendix-b][Appendix B]]
    - [[#appendix-c][Appendix C]]
:END:

** Chapter 1: Inline TOC
:PROPERTIES:
:TOC:       :include descendants
:END:

This chapter includes its TOC inline, with text before...

:CONTENTS:
- [[#section-1a][Section 1a]]
  - [[#subsection-1a1][Subsection 1a1]]
  - [[#subsection-1b1-included-despite-its-excluded-parent][Subsection 1b1: Included, despite its excluded parent]]
:END:

...and after it.

*** Section 1a

This section is included in the chapter's TOC.

**** Subsection 1a1

This subsection is also included.

*** Section 1b: Excluded, but child included
:PROPERTIES:
:TOC:      :ignore this
:END:

This section is not included in the chapter's TOC, but its subsection is (you probably wouldn't want to do this, but you could).

**** Subsection 1b1: Included, despite its excluded parent

This subsection is included in the chapter's TOC even though its parent is excluded.

** Chapter 2: TOC as sibling

This chapter has its TOC as a sibling of its sections.

*** Chapter 2 TOC
:PROPERTIES:
:TOC:    :include siblings
:END:
:CONTENTS:
- [[#section-2a][Section 2a]]
  - [[#subsection-2a1][Subsection 2a1]]
- [[#section-2b-child-is-excluded][Section 2b: Child is excluded]]
:END:

*** Section 2a

This section is included.

**** Subsection 2a1

This subsection is included.

*** Section 2b: Child is excluded
:PROPERTIES:
:TOC:      :depth 0
:END:

This section is included in the TOC.

**** Subsection 2b1: The excluded child

But its subsection is not.

** Chapter 3: TOC as parent

This chapter has its TOC as a parent of the chapter sections.

*** Chapter 3 TOC
:PROPERTIES:
:TOC:      :include descendants
:END:
:CONTENTS:
- [[#section-3a][Section 3a]]
  - [[#subsection-3a1][Subsection 3a1]]
- [[#section-3b][Section 3b]]
  - [[#subsection-3b1][Subsection 3b1]]
:END:

**** Section 3a

This section is included.

***** Subsection 3a1

This subsection is included.

**** Section 3b

This section is included.

***** Subsection 3b1

This subsection is included.

** Chapter 4: Limited depth
:PROPERTIES:
:TOC:       :include descendants :depth 1
:END:

This chapter's TOC uses =:depth 1= to exclude subsections.

:CONTENTS:
- [[#section-4a][Section 4a]]
- [[#section-4b][Section 4b]]
:END:

*** Section 4a

This section is included in the chapter's TOC.

**** Subsection 4a1

This subsection is excluded.

*** Section 4b

This section is included in the chapter's TOC.

**** Subsection 4b1

This subsection is excluded.

** Chapter 5: Local settings
:PROPERTIES:
:TOC:      :include descendants :depth 2
:END:

This chapter's TOC includes descendants only two levels deep by default.  However, Section 5b sets =:depth 3= (relative to itself) in order to include deeper descendants in its own section TOC.  Normally this depth setting would propagate up to the Chapter 5 TOC and cause, e.g. Section 5b1a to be included in the Chapter 5 TOC.  However, Section 5b also sets =:local depth=, which prevents its depth setting from propagating up the tree, so the sections 5b1a and 5b1b are excluded from the Chapter 5 TOC.

One could also set =:force depth= in the chapter 5 TOC to accomplish the same thing.  However, doing so would force the depth setting for /all/ subtrees in its TOC.  Instead, by using =:local depth= on Section 5b, we allow Section 5c to set =:depth 3=, which /is/ allowed to propagate up to the chapter 5 TOC.  So notice that, although Sections 5b and 5c are structurally identical, the way they are shown in the Chapter 5 TOC differs, because Section 5b sets =:local depth= while Section 5c does not.

If this seems complicated, perhaps it is, but it's optional power that's available when needed.

:CONTENTS:
- [[#section-5a][Section 5a]]
  - [[#section-5a1][Section 5a1]]
  - [[#section-5a2][Section 5a2]]
- [[#section-5b][Section 5b]]
  - [[#section-5b1][Section 5b1]]
- [[#section-5c][Section 5c]]
  - [[#section-5c1][Section 5c1]]
    - [[#section-5c1a][Section 5c1a]]
    - [[#section-5c1b][Section 5c1b]]
:END:

*** Section 5a

This section is included in the Chapter 5 TOC.

**** Section 5a1

This section is included in the Chapter 5 TOC.

**** Section 5a2

This section is included in the Chapter 5 TOC.

*** Section 5b
:PROPERTIES:
:TOC:      :include descendants :depth 3 :local depth
:END:
:CONTENTS:
- [[#section-5b1][Section 5b1]]
  - [[#section-5b1a][Section 5b1a]]
  - [[#section-5b1b][Section 5b1b]]
:END:

**** Section 5b1

This section is included in the Chapter 5 TOC.

***** Section 5b1a

This section is *not* included in the Chapter 5 TOC.

***** Section 5b1b

This section is *not* included in the Chapter 5 TOC.

*** Section 5c
:PROPERTIES:
:TOC:      :include descendants :depth 3
:END:
:CONTENTS:
- [[#section-5c1][Section 5c1]]
  - [[#section-5c1a][Section 5c1a]]
  - [[#section-5c1b][Section 5c1b]]
:END:

**** Section 5c1

This section is included in the Chapter 5 TOC.

***** Section 5c1a

This section is included in the Chapter 5 TOC.

***** Section 5c1b

This section is included in the Chapter 5 TOC.

** Appendices
:PROPERTIES:
:TOC:      :include descendants :depth 1
:END:

The appendices have a local TOC, and one of them is a comprehensive TOC of the entire document (unlike the main TOC at the top of the document, which is abridged).

:CONTENTS:
- [[#appendix-a-comprehensive-toc][Appendix A: Comprehensive TOC]]
- [[#appendix-b][Appendix B]]
- [[#appendix-c][Appendix C]]
:END:

*** Appendix A: Comprehensive TOC
:PROPERTIES:
:TOC:      :include all :force (depth ignore)
:END:

This comprehensive TOC uses =:include all :force (depth ignore)= to force all headings to be included, regardless of their local settings.

:CONTENTS:
- [[#document-top-level-heading][Document top-level heading]]
  - [[#main-toc-itself-excluded][Main ToC: Itself excluded]]
  - [[#chapter-1-inline-toc][Chapter 1: Inline TOC]]
    - [[#section-1a][Section 1a]]
      - [[#subsection-1a1][Subsection 1a1]]
    - [[#section-1b-excluded-but-child-included][Section 1b: Excluded, but child included]]
      - [[#subsection-1b1-included-despite-its-excluded-parent][Subsection 1b1: Included, despite its excluded parent]]
  - [[#chapter-2-toc-as-sibling][Chapter 2: TOC as sibling]]
    - [[#chapter-2-toc][Chapter 2 TOC]]
    - [[#section-2a][Section 2a]]
      - [[#subsection-2a1][Subsection 2a1]]
    - [[#section-2b-child-is-excluded][Section 2b: Child is excluded]]
      - [[#subsection-2b1-the-excluded-child][Subsection 2b1: The excluded child]]
  - [[#chapter-3-toc-as-parent][Chapter 3: TOC as parent]]
    - [[#chapter-3-toc][Chapter 3 TOC]]
      - [[#section-3a][Section 3a]]
        - [[#subsection-3a1][Subsection 3a1]]
      - [[#section-3b][Section 3b]]
        - [[#subsection-3b1][Subsection 3b1]]
  - [[#chapter-4-limited-depth][Chapter 4: Limited depth]]
    - [[#section-4a][Section 4a]]
      - [[#subsection-4a1][Subsection 4a1]]
    - [[#section-4b][Section 4b]]
      - [[#subsection-4b1][Subsection 4b1]]
  - [[#chapter-5-local-settings][Chapter 5: Local settings]]
    - [[#section-5a][Section 5a]]
      - [[#section-5a1][Section 5a1]]
      - [[#section-5a2][Section 5a2]]
    - [[#section-5b][Section 5b]]
      - [[#section-5b1][Section 5b1]]
        - [[#section-5b1a][Section 5b1a]]
        - [[#section-5b1b][Section 5b1b]]
    - [[#section-5c][Section 5c]]
      - [[#section-5c1][Section 5c1]]
        - [[#section-5c1a][Section 5c1a]]
        - [[#section-5c1b][Section 5c1b]]
  - [[#appendices][Appendices]]
    - [[#appendix-a-comprehensive-toc][Appendix A: Comprehensive TOC]]
    - [[#appendix-b][Appendix B]]
    - [[#appendix-c][Appendix C]]
  - [[#footer-excluded][Footer: Excluded]]
:END:

*** Appendix B

Possibly vestigial.

*** Appendix C

Definitely vestigial.

** Footer: Excluded
:PROPERTIES:
:TOC:      :ignore this
:END:

# Local Variables:
# before-save-hook: org-make-toc
# End: