Based on the provided code, I'll analyze whether numerical prefix ordering should be limited to documentation pages or kept for all page types. Let me break this down:

Current Implementation

The numerical prefix ordering feature is currently implemented for both documentation pages and main navigation items, as seen in:

## Numerical Prefix Navigation Ordering

HydePHP v2 introduces navigation item ordering based on numerical prefixes in filenames. This feature works for the primary navigation menu.

This has the great benefit of matching the navigation menu layout with the file structure view. It also works especially well with subdirectory-based navigation grouping.

Benefits of Current Approach (All Pages)

Consistency: Using the same ordering system across all page types provides a consistent mental model for developers.
File Structure Matching: As mentioned in the documentation, it matches the navigation menu layout with the file structure view.
Test Coverage: The feature is well-tested for both documentation and main navigation scenarios, as shown in:

    public function testFlatMainNavigationOrdering()
    {
        $this->setupFixture([
            '01-home.md',
            '02-about.md',
            '03-contact.md',
        ]);

        $this->assertOrder(['home', 'about', 'contact']);
    }

    public function testReverseOrderOfFlatMainNavigation()
    {
        // This is just a sanity check to make sure the helper is working, so we only need one of these.
        $this->setupFixture(array_reverse([
            '01-home.md',
            '02-about.md',
            '03-contact.md',
        ]));

        $this->assertOrder(['home', 'about', 'contact']);
    }

    public function testGroupedMainNavigationOrdering()
    {
        $this->setupFixture([
            '01-home.md',
            '02-about.md',
            '03-contact.md',
            '04-api' => [
                '01-readme.md',
                '02-installation.md',
                '03-getting-started.md',
            ],
        ]);

        $this->assertOrder(['home', 'about', 'contact', 'api' => [
            'readme', 'installation', 'getting-started',
        ]]);
    }

Case for Documentation-Only

Natural Hierarchy: Documentation pages inherently have a more hierarchical structure that benefits from numerical ordering:

```shell
_docs/
  01-installation.md     # Priority: 1
  02-configuration.md    # Priority: 2
  03-usage.md            # Priority: 3
```

Common Use Case: The examples and tests show this feature being particularly valuable for documentation organization:

```shell
_docs/
  01-getting-started/
    01-installation.md
    02-requirements.md
    03-configuration.md
  02-usage/
    01-quick-start.md
    02-advanced-usage.md
  03-features/
    01-feature-1.md
    02-feature-2.md
```

Complexity vs Value: Regular pages (like blog posts, landing pages) typically don't require such strict ordering, and their navigation is often simpler.

Recommendation

I recommend limiting numerical prefix ordering to documentation pages only for the following reasons:

Focused Purpose: Documentation is where this feature provides the most value due to its inherently hierarchical nature.
Reduced Complexity: Limiting the feature reduces cognitive load for users who don't need this functionality for regular pages.
Better Defaults: Most sites don't need complex ordering for their main navigation, and can use simpler priority settings when needed.
Documentation Focus: The feature seems to have been primarily designed with documentation in mind, as evidenced by the extensive documentation and test cases focused on documentation scenarios.

Implementation Suggestion

To implement this change:

Modify the NumericalPageOrderingHelper to only process numerical prefixes for DocumentationPage instances.
Update the documentation to clarify this feature is specific to documentation pages.
Keep the configuration option numerical_page_ordering but make it only affect documentation pages.

This would make the feature more focused and easier to maintain while preserving its most valuable use case.

Uh oh!

Should we use numerical prefix ordering only for documentation pages? #1997

Description

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions