Restructure deeply nested documentation sections to improve navigation

[divine7022]

Revised approach:

Description

Following discussion with @mdietze below, the original approach of hiding deep section numbers would mask the underlying problem rather than solve it. Deep heading hierarchies (5-6 levels) indicate content that needs restructuring, not relabeling.

This issue is reframed to focus on auditing and restructuring content with excessive nesting.

Problem

Several documentation files have heading hierarchies 5-6 levels deep, resulting in section numbers like 15.2.3.4.1.2. This creates:

• navigation difficulty (hard to remember/cite section numbers)
• organizational issues (deeply nested content is often misplaced or could be promoted)
• inconsistent structure (some files skip heading levels entirely)

Files requiring restructuring

Priority 1: Structural issues

03_topical_pages/11_adding_to_pecan.Rmd -- the only file with level-6 headings (######)

• contains multiple level-6 headings (e.g. “Example” sections)
• some sections (e.g. Vegetation Data and Soil Data) jump directly from level-4 headings to level-6 “Example” subsections, skipping level-5 entirely
• other sections in the same file (e.g. Meteorological Data) use a more consistent hierarchy

Suggested direction:

• Either fix the skipped heading levels, or
• Flatten “Example” content into lists, callouts, or non-heading blocks rather than deep subheadings

Priority 2: Deep nesting from folder hierarchy

These files have level-5 headings (#####) because they inherit depth from the book's folder structure:

93_installation/03_install_OS/04_Installing-PEcAn-OSX.Rmd -- 14 level-5 headings

• uses multiple “Option 1 / Option 2” subsections that appear quite deep in the hierarchy
• these could likely be simplified or flattened without losing clarity

93_installation/03_install_OS/05_install_BETY.Rmd -- 2 level-5 headings

93_installation/03_install_OS/06_install_models/*.Rmd

• several model install pages follow a similar pattern with deeply nested option style subsections

03_topical_pages/03_pecan_xml.Rmd

Priority 3: Minor instances

02_demos_tutorials_workflows/04_more_web_interface/02_hidden_analyses.Rmd

• ##### Benchmarking Output under #### Setup Benchmarks and metrics

05_developer_workflows/03_coding_practices/03-package-data.Rmd

05_developer_workflows/02_git/01_using-git.Rmd

Proposed approach

1. Audit files listed above to determine if deep nesting is justified
2. Flatten where appropriate:
   • promote subsections to higher levels
   • convert procedural "Example" headings to numbered lists or collapsible sections
   • split overly long chapters into separate files
3. Maintain numbering depth as natural outcome of better organization
   • rarely exceed 3-4 heading levels (x.y.z or x.y.z.a)

Suggested pilot

Start with 11_adding_to_pecan.Rmd as the pilot file because:

• It's the only file with level-6 headings
• Has clear structural bugs (skipped heading levels)
• Contains logical content that could be flattened (Examples as bullet points vs headings)

This establishes the restructuring pattern before tackling other files.

[divine7022]

here i would defer to @infotroph @mdietze and @dlebauer to see if they have any thoughts or concerns about the proposed workaround before folks take this on

[mdietze]

I'm not a fan of the proposal to keep the exact same hierarchical structure but remove subheader numbers after x.y. Places with deep hierarchies are places in need of restructuring, not relabeling. To take the example given, I suspect Meteorology Standard should be at the ## level within PEcAn standards

[divine7022]

you raise a valid point, hiding numbers without addressing the underlying structure would just be masking the real problem. Looking more closely at the examples i listed, yeah many of these deeply nested sections indicate organizational issues rather than a numbering configuration problem.

Taking your suggestion about "Meteorology Standards" - that content currently sits at level 5 within 02_pecan_standards.Rmd, but it really does deserve to be a ## section directly under the chapter. The same is likely true for many other deeply nested sections.

I think then the revised approach would be to :

reframe this issue to focus on restructuring the content hierarchy in files with excessive nesting (5-6 levels), rather than just hiding numbers via CSS. The goal would be:

1. audit files with deep nesting (the ones i listed above)
2. propose flattening where appropriate, promoting subsections to higher levels or splitting into separate chapters
3. keep numbering depth as a natural outcome of better organization (if we never go deeper than 3-4 levels, the numbers stay manageable)

This is a larger effort than a config change, but it addresses the root cause. I can update this issue to reflect that scope;

i suspect it would be helpful to start with a specific file (like 02_pecan_standards.Rmd or 11_adding_to_pecan.Rmd) as a pilot to establish the pattern before tackling others?

[shreyannandanwar]

Hi @divine7022 I'd like to work on this issue.

[divine7022]

@shreyannandanwar -- heads up, the scope has been updated now. Please check out the revised approach.