book-chapter-body.html

{%- comment -%}
  Per-chapter body processing for the book's chapter iteration. Pulled
  out of book.html so the three call sites (front-matter loop, flat
  per-part chapter loop, chaptered-part chapter loop) stay in sync.

  Inputs (passed via `{% include ... key=value %}`):
    chapter                  page object (required).
    article_class_override   optional. When set, the emitted <article>
                             uses this class literally; sub-page
                             detection still affects the internal
                             heading shift but doesn't add the
                             " sub-chapter" suffix. Default class is
                             "page" with " sub-chapter" appended for
                             sub-pages.
    chapter_anchor_override  optional. When set, replaces the URL-
                             derived chapter anchor. Used for the root
                             URL `/` in front matter where the default
                             derivation collapses to an empty seed; the
                             caller supplies an `fm.title`-derived
                             fallback.
    skip_sub_page_detection  optional truthy. When set, this chapter
                             doesn't update or read the
                             `current_index_*` state machine -- used by
                             front-matter (where there are no nested
                             sub-pages) so the root URL `/` doesn't
                             accidentally make every subsequent chapter
                             a sub-page of itself.
    extra_heading_shift      optional truthy. When set, applies an
                             additional +1 heading depth shift on top
                             of the standard 1.5a shift (and the 1.6b
                             sub-page shift, if applicable). Used by
                             chaptered-part chapters (1.9) so a class
                             index nests one outline level below its
                             chapter-divider H2 rather than appearing
                             as the chapter divider's sibling.
    skip_base_heading_shift  optional truthy. When set, skips the
                             standard 1.5a +1 shift entirely so the
                             chapter's source headings keep their
                             original depths. Used together with a
                             part / chapter divider's `no_outline_entry`
                             flag to keep the content at the outline
                             level the suppressed divider would have
                             occupied. 1.6b sub-page and 1.9
                             `extra_heading_shift` still apply on top
                             when their conditions are met.

  Reads + mutates outer-scope globals:
    current_index_url, current_index_kind, current_index_name -- the
      1.6a sub-page state machine. Caller is responsible for
      initialising these before its for-loop and resetting between
      independent chapter sequences (e.g. between chapters of a
      chaptered Part).
    p1_search/p1_replace .. p4_search/p4_replace, p3i*/p4i* -- the
      whitespace patterns defined at the top of book.html.

  Emits one `<article>...</article>` block at the call site. Empty
  chapter bodies are skipped silently (no article emitted).
{%- endcomment -%}
{%- assign first_char = include.chapter.content | strip | slice: 0, 1 -%}
{%- if first_char == '<' -%}
  {%- assign body = include.chapter.content -%}
{%- else -%}
  {%- assign body = include.chapter.content | markdownify -%}
{%- endif -%}

{%- comment -%}
  1.6a sub-page detection + 1.6c kind/name capture. When we see an
  index URL we read the index's H1 to decide class vs module --
  relying on the sub-page's `parent:` field would be wrong because
  several VBRUN class folders mistakenly suffix it with " Module"
  (e.g. AmbientProperties' BackColor.md). The H1 text (`# Foo class`
  / `# Foo module`) is the source of truth.
{%- endcomment -%}
{%- assign is_sub_page = false -%}
{%- unless include.skip_sub_page_detection -%}
  {%- assign url_last_char = include.chapter.url | slice: -1, 1 -%}
  {%- if url_last_char == '/' -%}
    {%- assign current_index_url = include.chapter.url -%}
    {%- assign current_index_name = include.chapter.title
          | replace: ' Module', ''
          | replace: ' module', ''
          | replace: ' Class', ''
          | replace: ' class', ''
          | replace: ' Package', '' -%}
    {%- assign content_head = include.chapter.content | slice: 0, 200 | downcase -%}
    {%- if content_head contains 'module' -%}
      {%- assign current_index_kind = 'module' -%}
    {%- else -%}
      {%- assign current_index_kind = 'class' -%}
    {%- endif -%}
  {%- elsif current_index_url != '' -%}
    {%- assign sized_prefix = include.chapter.url | slice: 0, current_index_url.size -%}
    {%- if sized_prefix == current_index_url -%}
      {%- assign is_sub_page = true -%}
    {%- else -%}
      {%- assign current_index_url = '' -%}
    {%- endif -%}
  {%- endif -%}
{%- endunless -%}

{%- comment -%}
  Body transformation: the `src="<baseurl>/` strip (so pagedjs's
  render-time `<img>` fetches resolve against `_site/`), the 12
  inter-span whitespace patterns (so pagedjs's page splitter doesn't
  mash code-line tokens together at page breaks), the 0-3 heading
  shift cascades (1.5a base, 1.6b sub-page, 1.9 chaptered-part
  extra), and the per-heading anchor-id prefix injection all run in
  one Ruby method via the `book_chapter_transform` filter (see
  `_plugins/book-chapter-transform.rb` for the per-step rationale).

  `heading_shift_n` is the total number of cascade levels to apply,
  precomputed in Liquid from the three flags. The plugin then bumps
  every heading by exactly N in a single regex pass, capping at
  `h7-stub` for source levels that exceed 6.

  `chapter_anchor` is the per-chapter id prefix derived from the
  chapter URL (or supplied by the caller via
  `chapter_anchor_override`). It's still computed in Liquid because
  the article element below also reads it; the plugin just injects
  it into every heading-id and `href="#..."` in the body.
{%- endcomment -%}
{%- assign heading_shift_n = 0 -%}
{%- unless include.skip_base_heading_shift -%}{%- assign heading_shift_n = heading_shift_n | plus: 1 -%}{%- endunless -%}
{%- if is_sub_page -%}{%- assign heading_shift_n = heading_shift_n | plus: 1 -%}{%- endif -%}
{%- if include.extra_heading_shift -%}{%- assign heading_shift_n = heading_shift_n | plus: 1 -%}{%- endif -%}

{%- if include.chapter_anchor_override -%}
  {%- assign chapter_anchor = include.chapter_anchor_override -%}
{%- else -%}
  {%- assign url_path = include.chapter.url | replace: '/', '-' -%}
  {%- assign anchor_first_char = url_path | slice: 0, 1 -%}
  {%- if anchor_first_char == '-' -%}
    {%- assign url_len = url_path.size | minus: 1 -%}
    {%- assign url_path = url_path | slice: 1, url_len -%}
  {%- endif -%}
  {%- assign anchor_last_char = url_path | slice: -1, 1 -%}
  {%- if anchor_last_char == '-' -%}
    {%- assign url_len = url_path.size | minus: 1 -%}
    {%- assign url_path = url_path | slice: 0, url_len -%}
  {%- endif -%}
  {%- assign chapter_anchor = 'ch-' | append: url_path -%}
{%- endif -%}

{%- assign body = body | book_chapter_transform: site.baseurl, heading_shift_n, chapter_anchor -%}

{%- assign stripped = body | strip -%}
{%- unless stripped == "" -%}

  {%- comment -%}
    Pick the article class and running-header text. When the caller
    overrides the class (front-matter, part-foreword), the override
    is used as-is and sub-page styling never kicks in. Otherwise
    sub-pages get the " sub-chapter" suffix and a compound running
    header ("Parent - Member").
  {%- endcomment -%}
  {%- if include.article_class_override -%}
    {%- assign article_class = include.article_class_override -%}
    {%- assign header_title = include.chapter.title -%}
  {%- else -%}
    {%- assign article_class = 'page' -%}
    {%- if is_sub_page -%}
      {%- assign article_class = article_class | append: ' sub-chapter' -%}
      {%- assign header_title = current_index_name | append: ' - ' | append: include.chapter.title -%}
    {%- else -%}
      {%- assign header_title = include.chapter.title -%}
    {%- endif -%}
    {%- if include.extra_heading_shift -%}
      {%- assign article_class = article_class | append: ' chaptered' -%}
    {%- endif -%}
  {%- endif -%}
<article class="{{ article_class }}" id="{{ chapter_anchor }}">
<span class="header-string">{{ header_title }}</span>
{{ body }}
</article>
{%- endunless -%}