Bookdown: how to break chapters into multiple Rmd files

bookdown

#1

Hi,

I have just started to loot into porting a very large user manual into bookdown. From the beginning of the reference guide (https://bookdown.org/yihui/bookdown/theming.html), it seems that multiple Rmd files can be used: one per chapter.
My question is: can I break a chapter onto multiple Rmd files and merge the whole thing?


#2

yes, you can. just do it.


#3

Hi,

This generally works. There is one formatting problem though when one uses bibtext references in .Rmd files which are not chapters (## level and down): the html contains one to many resulting in References section showing with improper formatting and alignment.

I will submit a github issue.


#4

one way to break a chapter into multiple files is to use the child feature to pull in subchapter sections.

In the main chapter rmd you would include a chunk like this:

```{r child="chapter2-b.Rmd", echo=FALSE}

#5

Thanks @jdlong

This happens to solve the bibtext reference formatting problem...
A thing to consider though is that using this notation will combine the outputs of the chapter and child .Rmd files into a single html file. If there is a large amount of material to display, the html page can take a long time to load.


#6

This is a pretty unique edge case. You initially asked, "can I break a chapter onto multiple Rmd files and merge the whole thing?" but that's doesn't seem like what you want. What I think you want is nonlinear chapter numbering:

Ch 1a: intro part 1
Ch 1b: intro part2
Ch 2: some stuff
Ch 3a: long chapter part a
Ch 3b: long chapter part b
Ch 3c: long chapter part c

That's going to be hard as it breaks the chapter number paradigm completely.


#7

"This is a pretty unique edge case. "

I happen to work on a user manual with about 150+ Rmd files, 200,000 words, hundreds of images/screen captures... So I kind of jumped directly into the deep end of the bookdown pool :smiley:

"Can I break a chapter onto multiple Rmd files and merge the whole thing?"
I meant can I create a bookdown with multiples Rmd which are either chapter and subsections. So the answer provided by @dapeng is right and allows the structure you referenced (with each row being a Rmd and a gitbook html):

Ch 1a: intro part 1
Ch 1b: intro part2
Ch 2: some stuff
Ch 3a: long chapter part a
Ch 3b: long chapter part b
Ch 3c: long chapter part c

Overall, I would say that it is a matter of adapting the solution to the specific content and need of the book.


#8

Hey @pomchip I’m not sure if what you’re interested in doing is possible or not, but wanted to ask how wedded to that organizational format you were?

If you take a look at a lot of the bookdown books out there, including the authoritative guide to R Markdown, you’ll notice that there are part numbers in Roman numerals. Could you organize using parts and chapters instead of chapters and sub chapters?


#9

@chris.prener

I forgot I read that from the reference bookdown guide. What looks interesting to me is the alignment in TOC which saves a bit of real-estate...
Do you know if there is a way to restart the numbering of chapters in each part?


#10

Not that I’m aware - the chapter numbering has implications for how the html files are named and for cross referencing things like tables, so I think there are a couple reasons for not readjusting this numbering.

Are you ultimately going to be displaying this book online or as a pdf or both?


#11

One thought I just had @pomchip - check out the source for Kieran Healy’s visualization book - he has an appendix section at the end where the chapter numbering has been modified. That might give you some clues about possible changes you can make.


#12

Thanks @chris.prener

Kieran's github does not seem to include the source of his book... or I did not look at the right spot.


#13

hm I wonder if it was taken down - I could have sworn it was up beforehand. Sorry about that! At least you know some modifications are possible.

Re my other question - Are you ultimately going to be displaying this book online or as a pdf or both? This seems like a project better suited for LaTeX if the chapter numbering is so consequential.


#14

@Chris

I am still on the fence regarding the format. My preference, right now, is to use the html gitbook format because of the fairly large size of this document and how users would access to it. Also, I had to use pure html tags to create many tables with complex designs. My understanding is that the LaTeX/pdf output would simply ignore those. I could get a pdf by creating an epub which I, then, convert to pdf using Calibre. There is maybe a better way to go about that, but that's what I have right now :smiley:

I am not attached to a particular numbering style, as long as there is some form of resetting for the subsection numbering within chapters, which the #, ##, ### formats allow. My titles are a bit long, so gaining a bit of real-estate in the TOC would be nice (although not critical). I am considering removing numbering all together using {-#} tags...


#15

Maybe I'm confused (totally possible!) - you want to reset numbering within chapters for sections or within parts for chapters?


#16

@chris.prener

I probably make it more confusing than I needed to be.

What I have right now using #, ##, and ### is roughly fine:

1- Section ABC
1.1- A subsection
1.2- Another one
1.3- A third one
1.3.1- A sub-subsection
1.3.1- Another one
2- Section DEF
2.1- Some subsection
2.2- Another one

If I transform my sections into parts, my subsections into sections, and my sub-subsections into subsections, I get:

Section ABC
1- A subsection
2- Another one
3- A third one
3.1- A sub-subsection
3.1- Another one
Section DEF
4- Some subsection
5- Another one

I would need the section numbering to reset within parts... which is impossible. So I will keep using the first approach but will add the following css to allow TOC text to wrap when it is larger than the panel width:

.book .book-summary ul.summary li a, .book .book-summary ul.summary li span {
  white-space: normal; 
}

#17

@pomchip - I have this lingering feeling that what you want in terms of organization, and what you can get with Bookdown, might not be 100% compatible. I've had similar struggles at points with Bookdown, coming from LaTeX land where everything can be modified. My experience was that I needed to manage my own expectations.

In this case, I think what I would suggest is revisiting your organizing paradigm for the TOC. Are there ways where you can work within the Part / Chapter / Section format? Rather than pushing uphill with your current TOC, you might find more success in revisiting how that TOC is formatted...


#18

As I said, I am fine working with the "#, ##, ###" approach and found a compromise between my expectations and the limitations of bookdown (don't get me wrong, it is an awesome authoring platform!)

As a beginner, I wasn't sure if my inability to achieve certain design aspects was due to my limited knowledge of the platform or to the limitations of the platform itself. Hence my questions.


#19

Makes sense @pomchip - totally get where you're coming from. Good luck with your project!