Skip to content

Fail early with clear message if book header structure is not the expected one #1017

Open
@cderv

Description

@cderv

This follows an investigation from this question
https://community.rstudio.com/t/bookdown-debugging-fixing-incomprehensible-error/87014/6

  • The book start with a header h2. By default, split_by = "chapter" so a h1 is expected - this fails with a cryptic error (see community question)
  • If the book start with a header h2 but split_by: section is set, the render stop early because of what I believe to be a wrong check

    bookdown/R/html.R

    Lines 268 to 276 in 0098721

    if (split_level > 1) {
    body = x[(i5 + 1):(i6 - 1)]
    h1 = grep('^<div (id="[^"]+" )?class="section level1("| )', body) + i5
    h2 = grep('^<div (id="[^"]+" )?class="section level2("| )', body) + i5
    h12 = setNames(c(h1, h2), rep(c('h1', 'h2'), c(length(h1), length(h2))))
    if (length(h12) > 0 && h12[1] != i5 + 1) stop(
    'The document must start with a first (#) or second level (##) heading'
    )
    h12 = sort(h12)

    h1 header will always be before h2 header, so if the book start with a h2 header, h12[1] != i5 + 1 will always be TRUE. I think sort(h12) should be done before the if

We may need to check the first header found according to split_by

  • split_by = "chapter" => h1 should be first
  • split_by = "section" => h1 or h2 could be first

Error message should be clear on what is expected.

Metadata

Metadata

Assignees

No one assigned

    Labels

    featurea feature request or enhancementnextto consider for next release

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions