Web page titles range from H1 to H6, but this does not necessarily imply a reasonable hierarchical structure

This paper uses synthetic samples to demonstrate the processing method. The code has been verified using examples in an isolated environment; this does not guarantee effectiveness for all real files or products. Before processing important files, please retain the original copies and verify them against the boundaries and acceptance criteria specified in the text. When dealing with technical documentation or web content, a common misconception is that as long as there is in HTML <h1> to <h6> tag; the document structure is correct. In fact, the presence of a tag merely indicates “there is a heading here” and does not guarantee that the hierarchical logic holds. For example, <h1> directly followed by <h3> , multiple <h1> coexists, or use <div class="title"> disguised titles will all lead to errors in table-of-contents generation, failure of translation-memory matching, or barriers to accessible reading. The real issue is not whether “title tags are present,” but rather whether “the titles form a valid nested tree.” Why does the existence of a tag not imply structural validity? The HTML specification imposes clear semantic constraints on heading levels: <hN> They should be nested in sequence and not skipped. However, in real-world production environments, factors such as CMS templates, pasting from rich-text editors, and front-end component encapsulation often lead to structural corruption. An even more insidious situation is when visual styles (CSS) override semantic tags, causing font-size: 24px 's <p> looks like H1, whereas the actual <h2> is instead rendered in small type. If one relies solely on regular expressions to match tag names or on the browser’s rendering results for judgment, the “visual hierarchy” may be mistakenly taken as the “semantic hierarchy.” The value of Beautiful Soup lies in its parsing of the DOM tree itself, unaffected by CSS, enabling us to perform structural validation based on the original markup. synthesis example: correct and incorrect title sequences To illustrate the issue, we construct a set of in-memory HTML fragments as synthetic examples. Note: The following samples are intended solely for demonstrating the logical design; they do not represent real-world pages nor do they correspond to any industry-standard thresholds. correct input example ： <h1>API 概览</h1> <h2>认证机制</h2> <h3>OAuth2 流程</h3> <h2>错误处理</h2> The expected output should be: hierarchical continuity, no skipped levels, a unique H1, and subheadings strictly subordinate to their parent headings. error/boundary input example ： <h1>用户指南</h1> <h3>快速开始</h3> <!-- 跳过 H2 --> <div class="section-title">高级配置</div> <!-- 非标题标签 --> <h1>附录</h1> <!-- 第二个 H1 --> This example involves three types of issues: skipping levels from H1 to H3, using div elements to simulate headings, and having multiple H1 tags. The correct approach is to label these as “skip-level,” “non-heading-title,” and “multiple-h1,” respectively, rather than simply reporting an error or ignoring them. Special note: <div class="section-title"> contains the word “title,” but semantically it is not a title and should not be included in the hierarchical tree; if business requirements dictate treating it as a title, a conversion rule must be explicitly declared, and it should be separately annotated during acceptance testing. code example for implementing hierarchical validation using Beautiful Soup The following Python example uses Beautiful Soup 4.15.0 (with the Python standard library's html.parser) to construct a sample in memory and perform basic validation. input preparation : Assign the HTML string to be inspected to html_snippet variable; if reading from a file, use open().read() obtains the string content and then passes it to the parser. output expected : The script will print a structured list of issues and verify known defects in the synthetic data through assertions. The code does not rely on external networks or file system operations; all assertions are based on the design expectations for the synthetic data. Please run it in your own isolated dependency environment, without assuming version compatibility. from bs4 import BeautifulSoup # 输入准备：合成示例包含跳级、伪标题、多H1 # 实际使用时可替换为 open('page.html').read() html_snippet = """ <h1>用户指南</h1> <h3>快速开始</h3> <div class="section-title">高级配置</div> <h1>附录</h1> """ soup = BeautifulSoup(html_snippet, 'html.parser') headings = soup.find_all(['h1', 'h2', 'h3', 'h4', 'h5', 'h6']) issues = [] prev_level = 0 h1_count = 0 for tag in headings: level = int(tag.name[1]) text = tag.get_text(strip=True) if level == 1: h1_count += 1 if prev_level > 0 and level > prev_level + 1: issues.append(f"skip-level: H{prev_level} -> H{level} at '{text}'") prev_level = level if h1_count != 1: issues.append(f"multiple-h1: found {h1_count} H1 tags") # 检查伪标题（仅作为补充信号，不自动纳入层级） pseudo_titles = soup.find_all('div', class_='section-title') if pseudo_titles: issues.append(f"non-heading-title: {len(pseudo_titles)} div.section-title found") # 输出与验收：针对本合成示例的预期断言 print("Detected issues:") for issue in issues: print(f"- {issue}") assert len(issues) == 3, f"Expected 3 issues, got {len(issues)}" assert any('skip-level' in i for i in issues) assert any('multiple-h1' in i for i in issues) assert any('non-heading-title' in i for i in issues) This script only verifies structural anomalies at the tag level and does not address content quality or visual consistency. find_all returns a list of tags in document order, so hierarchical inference relies entirely on the state records maintained during traversal. To support complex nesting (e.g., section/article wrappers), parent-node analysis should be incorporated; however, this example focuses on the most basic linear-sequence validation. Acceptance Criteria and Manual Review Boundary code can catch mechanical errors, but it cannot replace human judgment of semantics. The table below lists typical observations and their corresponding handling decisions, distinguishing between automated capabilities and points requiring human intervention: Observation of the phenomenon automated processing Necessity of human review Note H1→H3 jump level marks skip-level high It is necessary to confirm whether this is a typographical error or an intentional omission of the intermediate chapters. multiple H1 marks multiple-h1 high single-page application or multilingual version may be legal div/span with the class name marks non-heading-title in If it is a legacy template, it may require batch conversion to H2 content is empty or consists solely of symbols does not detect high pertains to content quality issues and falls outside the scope of structural validation The title contains a link or an emphasis tag normal text extraction low get_text(strip=True) has been processed Note: The rules described in this table apply only to the validation logic of the current synthesis example and do not constitute a general specification. When encountering CMS-generated dynamic pages, Shadow DOM, or JS-rendered content, Beautiful Soup cannot obtain the complete DOM; in such cases, you should switch to pre-processing with a headless browser or submit the original source code for manual review. References and Next Steps Beautiful Soup Documentation Next step: Select an HTML document you are working on, run the aforementioned validation script, and record the types of issues detected. If non-tagged headings or complex nesting are present, extend the script to support parent container analysis, or proceed directly to the manual review process. uses this checklist for document translation The body text, links, code, and structure of the web document should be processed separately. Include the protected sections in the acceptance checklist, then assess the readability and visual presentation of the translated content. OmniDoc (product entry point) provides an entry point for translating multi-format documents, and the official website highlights its OCR, terminology database, and bilingual alignment features. For teams that wish to start processing directly from files, this is a path worth evaluating with real-world samples. Please use de-identified files that you are authorized to upload, and verify the results against the checklist provided in this document; we do not claim that OmniDoc utilizes the open-source libraries or internal algorithms referenced herein, nor do we substitute examples for product performance testing. - 1 -