Ensure an H2 section ``heading`` exists in ``lines``; append if missing. Recovers from hand-edited or drifted index.md files where the expected section was removed or renamed — without this, downstream inserts would silently no-op and entries would be dropped. ``quiet=True`` suppre
(lines: list[str], heading: str, *, quiet: bool = False)
| 799 | |
| 800 | |
| 801 | def _ensure_h2_section(lines: list[str], heading: str, *, quiet: bool = False) -> None: |
| 802 | """Ensure an H2 section ``heading`` exists in ``lines``; append if missing. |
| 803 | |
| 804 | Recovers from hand-edited or drifted index.md files where the expected |
| 805 | section was removed or renamed — without this, downstream inserts would |
| 806 | silently no-op and entries would be dropped. |
| 807 | |
| 808 | ``quiet=True`` suppresses the drift warning. Use it when adding a section |
| 809 | is the normal, expected operation (e.g. a backlink helper creating a |
| 810 | ``## Related Documents`` / ``## Entities`` section on a page for the first |
| 811 | time), as opposed to repairing a drifted index. |
| 812 | """ |
| 813 | if _get_section_bounds(lines, heading) is not None: |
| 814 | return |
| 815 | if not quiet: |
| 816 | logger.warning( |
| 817 | "Wiki page is missing %r section; appending it. " |
| 818 | "Check whether the file was hand-edited away from the canonical layout.", |
| 819 | heading, |
| 820 | ) |
| 821 | while lines and lines[-1] == "": |
| 822 | lines.pop() |
| 823 | if lines: |
| 824 | lines.append("") |
| 825 | lines.append(heading) |
| 826 | lines.append("") |
| 827 | |
| 828 | |
| 829 | def _ensure_h2_section_before( |