Why is a home page (i.e., index.qmd) required for PDF books?

[mattwarkentin]

Hi,

Without getting too much into the weeds of my specific use case, I previously wrote an R package to provide an R Markdown format conforming to my university's thesis format. I am now trying to port this over to Quarto. This has mostly gone smoothly.

The issue I'm running into is that I apparently HAVE to have an index.qmd home page. My _quarto.yml currently looks like:

project:
  type: thesis

book:
  output-file: Last_First_MiddleInitial_Year_PhD_thesis
  title: "An Amazing Thesis Title"
  chapters:
    - index.qmd
    - chapters/01-Introduction.qmd
    - chapters/02-Background.qmd
    - chapters/03-Methods.qmd
    - chapters/04-Results.qmd
    - chapters/05-Discussion.qmd
    - chapters/references.qmd
    - chapters/appendix.qmd

bibliography: references.bib

The index.qmd file is entirely empty, but still shows up in the rendered PDF as a new chapter. If I remove index.qmd from the chapers, the build fails with the following error:

ERROR: Book contents must include a home page (e.g. index.md)

What am I missing here? I am being forced to include this file, but the inclusion adds a blank chapter to my final document. What can I do?

I could, of course, copy the contents of the actual first chapter (01-Introduction.qmd) into index.qmd, but I feel like this is kind of hacky - I want to be able to name my chapters as shown above.

[cderv]

Following #2941 we added some explanation to our doc about the why of index.qmd. See
https://quarto.org/docs/books/book-structure.html#overview

The index.qmd file is required (because Quarto books also produce a website in HTML format). This page should include the preface, acknowledgements, etc. and headings in the index.qmd file are unnumbered by default. The HTML version of the book will use the index.qmd as the home page and if provided, will place the cover-image on that page.

So the file is not required per-se for PDF only, but is for HTML book. Quarto is designed as multiformat first and index.qmd is the way to add unumbered content at the start of the book which is often needed.

In your case, I guess you have nothing to put before the content numbered content of 01-Introduction.qmd ?

[liyongg]

Is there an update on this with regards to docx output as well?

[dragonstyle]

No update from me- this is a larger item so will land in 1.4 of later at this point since we are stabilizing 1.3 right now.

[liyongg]

I'm sorry for my ambiguous question. Is there an issue for this that I can keep tabs on? @cderv

[cderv]

I believe that would be this one looking at opened issues #2556

[ABohynDOE]

Thanks for the response. I did end up stumbling upon this information, but I am unable to place any of those things in the index.qmd file as all of the pre-chapter content (title page, abstract, acknowledgements, list of tables/figures, etc.) are are explicitly handled by the TeX template.

I have nothing to include in this file. This index page is not applicable in my case. But since I can't remove it, it creates a blank chapter in the PDF thesis document. Any suggestions?

This is a bit hacky, but you can add

# {.unnumbered .unlisted}

to your index.qmd file. It will create a blank title that is not numbered and not listed in the TOC. Your chapter 01_introduction should still be numbered chapter 1. However, it will create a blank page between TOC and the first chapter.