Custom table of contents

[cjdbarlow]

Allows a custom TOC file to be specified in _bookdown.yml, so component rmd files (and the order of) can be specified. This is mutually exclusive with other build options (e.g. rmd_subdir).

An example toc could be:

# Main
---
* [Home](index.Rmd)
* [Intro](content/01-intro.Rmd)
	* [Literature](content/02-literature.Rmd)
* [Methods](content/03-method.Rmd)
	* [Applications](content/04-application.Rmd)
		* [Summary](content/05-summary.Rmd)
* [Refs](content/06-references.Rmd)

• Warnings will be flagged to console if there are files in the toc that can't be found, or relevant files in the book directory that aren't included in the toc. It has been helpful typo detection.

Additionally, when used in the gitbook style:

• The "headers" (e.g. '#Main') are rendered on their own line in the TOC, and styled differently. This allows blocks of first-level TOC elements to be broken up visually into groups.
• Dividers ('---') can be inserted arbitrarily between TOC elements. Dividers break any indentation/sublists.
• Page names in TOC to be different from the actual page name (the H1 header). The [Name] is used for the TOC, whilst the H1 header on the page is still used on the page.
• Subsections are determined by indentation in the TOC (tab-separated), rather than by #/##/### etc. This means that #/##/### etc can be used for internal page styling, rather than determining TOC components.
• Best results seen/designed for/only tested when _output.yml has toc_depth: 1 and split_by: rmd, but this is not forced - I can see the toc being useful even if the gitbook style isn't used.

Other stuff:

• A 'stubs' folder is also specified, for holding bits of .rmd/.md files that are designed to be included in other files. This meets a criteria of my planned workflow. It affects how warnings are flagged (stubs are ignored), but no other material effects.
• A 'stringr' dependency has been 'added' - as rmarkdown already is dependent I think this is reasonable.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[cderv]

Hi @Chrisjake, Thanks for your contribution.

In order to better understand the need of this, as there was no issue opened to discuss this prior to the PR, I am curious about why the classic header 1, header 2, ... structure that is usually reflecting in the TOC does not work for you ?
Would it be because you want to have separate files for sub chapters ?

IMO h1 / h2 / h3 represented by #/##/## are meant to structure the content first and not provide styling - there is css for that.

I am just trying to better understand the problem you aim to solve with this PR before looking at it any further.

Thank you very much.

[cjdbarlow]

Hi @cderv ,
There are two ways I see it being useful for my use case, which is migrating this gitbook to bookdown.

1. Separate files as subchapters (as you have said)
   • Allows subchapters to be moved around easily as the design changes (relevant for another project I have)
   • Increases resilience of the system to merge conflicts between multiple authors
   • Easier to manage long books with multiple subchapters
2. Customising the toc with headings (e.g. curriculum, in my example), and dividers

[cderv]

Customising the toc with headings (e.g. curriculum, in my example), and dividers

I think this is equivalent to the already supported special (PART) header (https://bookdown.org/yihui/bookdown/markdown-extensions-by-bookdown.html#special-headers) : Have you tried that already ?

Separate files as subchapters (as you have said)

Bookdown is currently design to have one file per header 1 chapter, otherwise it could lead to undesired issues with some features (like #947 (comment)). Having the ability to be more free on how to organize the source file is an often asked question, and it is not just a matter of TOC. There is a splitting that happens from the rendered HTML to the multiple files - this is the challenge I think here.

But it is definitly a asked-feature we should look into.

[cjdbarlow]

I think this is equivalent to the already supported special (PART) header (https://bookdown.org/yihui/bookdown/markdown-extensions-by-bookdown.html#special-headers) : Have you tried that already ?

I had not seen that! That would provide the same function but also translate better to other formats; I will use that instead.

There is a splitting that happens from the rendered HTML to the multiple files - this is the challenge I think here... definitly a asked-feature we should look into.

I agree; though I am not sure the best way to do this (YAML probably better than what I have done...) - I am not a software engineer by any stretch. Provided there is only 1 H1 header per file it seems to behave though, and I do like the flexibility it provides. I think functionality like this is valuable, even if this is not the mechanism by which it should be implemented.