Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Custom table of contents #964

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Custom table of contents #964

wants to merge 2 commits into from

Conversation

cjdbarlow
Copy link

@cjdbarlow cjdbarlow commented Oct 4, 2020

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.

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

Additionally, when used in the gitbook style:
- Can define "headers" in the TOC without an associated page, which are styled appropriately
- Can insert custom dividers between TOC elements
- Can set page names in TOC to be different from the actual page name (the H1 header)
- Best results seen/designed seen when _output.yml has toc_depth: 1 and split_by: rmd
@CLAassistant
Copy link

CLAassistant commented Oct 4, 2020

CLA assistant check
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.

Tiny change so that extra_dependencies (e.g. css) piped to gitbook() take precedence over default options, because it means they will be loaded later in the DOM
@cderv
Copy link
Collaborator

cderv commented Oct 5, 2020

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
Copy link
Author

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
Copy link
Collaborator

cderv commented Oct 5, 2020

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
Copy link
Author

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants