[2.x] Support automatic navigation priorities by prefixing a number in filenames

[caendesilva]

Fixes #1646

When source filed are numbered like so (or using the most common convention)

1_foo.md
2_bar.md
3_baz.md

That order should be used for their navigation priorities.

This makes large sites much cleaner as local file systems match the order of the results. Of course it should be possible to disable this as well.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.97%. Comparing base (af3cb6e) to head (8a28111).

Additional details and impacted files

@@            Coverage Diff             @@
##             2.x-dev    #1709   +/-   ##
==========================================
  Coverage      99.97%   99.97%           
- Complexity      1769     1784   +15     
==========================================
  Files            183      184    +1     
  Lines           4705     4738   +33     
==========================================
+ Hits            4704     4737   +33     
  Misses             1        1           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[caendesilva]

Thinking on how to best implement this, since we want to strip the numbers from identifiers, perhaps we should inject a (temporary) meta front matter potion to store the file number.

Edit: Nevermind we can't do this, as it means we lose the source file reference, unless we add another real path identifier which feels double hacky.

Edit 2: Yeah we should not mess with identifiers, instead we need to transform the output path since that's the only time we want it to be clean (so we don't have the numbers in compiled files) so this needs to be done at the route key stage.

Edit 3: Route key stage option might be better as well since it means we can diff out the number instead of a hacky meta field

[caendesilva]

ChatGPT Syntax Response

What are the most common ways in static site generators and flat file content management systems to specify the page order within the filenames?

In static site generators and flat-file content management systems, page order within filenames is often specified using numeric prefixes or timestamps. Here are some common approaches:

1. Numeric Prefixes: Files are named with a numerical prefix indicating the desired order. For example:

   01_home.md
   02_about.md
   03_contact.md
   

2. Timestamps: Files are named with timestamps indicating their creation or modification time. This can be helpful if you want pages to appear in the order they were created or modified. For example:

   2024-05-02_home.md
   2024-04-30_about.md
   2024-05-01_contact.md
   

3. Alphabetic Ordering: If neither numeric prefixes nor timestamps are used, the pages may be ordered alphabetically based on their filenames. For example:

   about.md
   contact.md
   home.md
   

4. Configuration Files: Some static site generators and flat-file CMSs allow specifying page order in a separate configuration file rather than relying on filename conventions. This provides more flexibility and doesn't require changing filenames when adjusting the order.

5. Front Matter: In Markdown files, YAML or JSON front matter can be used to specify metadata, including page order. While this doesn't directly affect filenames, it allows defining the order within the content files themselves.

The choice depends on personal preference, project requirements, and the features supported by the specific static site generator or CMS being used.

What are some various syntaxes for the numeric prefix option?

Various syntaxes can be used for the numeric prefix option in static site generators and flat-file CMSs. Here are some common syntaxes:

1. Leading Zeros: Adding leading zeros can ensure proper sorting, especially when dealing with double-digit or triple-digit numbers.

   01_home.md
   02_about.md
   03_contact.md
   

2. Dash Separator: Using dashes to separate the numeric prefix from the rest of the filename.

   1-home.md
   2-about.md
   3-contact.md
   

3. Underscore Separator: Similar to the dash separator, but using underscores instead.

   1_home.md
   2_about.md
   3_contact.md
   

[caendesilva]

Additionally, when asked about a possible configuration option name (and providing the base hyde config for context) this is the suggestion

Given the current code style and the nature of the configuration options, a suitable name for the configuration option to disable the feature of supporting multiple formats for specifying page order could be:

/*
|--------------------------------------------------------------------------
| Filename Ordering
|--------------------------------------------------------------------------
|
| This setting controls the ordering of filenames used for specifying page
| order within the static site generator. By default, multiple formats
| are supported (e.g., '00X_file.md' and 'X_file.md'). You can disable
| support for multiple formats by setting this option to false.
|
*/
'filename_ordering' => true,

This naming convention follows the pattern used in the existing configuration file, providing a clear and descriptive name for the option along with a brief explanation of its purpose and behavior.

[caendesilva]

AI Documentation Drafts

Prompt

A new feature in HydePHP v2 is that pages can be ordered by prefixing a number to the filenames. I want you to create documentation for this new feature. Below you will see the current navigation documentation as it is important that you match the writing style of the existing documentation. There is also the test attached so you can see some of the example fixtures. You only need to write the new section

(ChatGPT)

Filename Prefix Navigation Ordering

Introduction

HydePHP v2 introduces a new feature that allows you to order pages in the navigation menus by prefixing a number to the filenames. This feature provides a convenient way to control the order of pages without the need for explicit priority settings in the front matter or configuration files.

Enabling the Feature

The filename prefix navigation ordering feature is enabled by default in HydePHP v2. However, if you need to disable it for any reason, you can do so in the configuration file.

To disable the filename prefix navigation ordering feature, set the filename_page_ordering option to false in the hyde.php configuration file:

'filename_page_ordering' => false,

Ordering Pages

Flat Navigation

In a flat navigation structure where all pages are at the same level, you can simply prefix each filename with a number to specify the order in which they should appear in the navigation menu.

For example:

01-home.md
02-about.md
03-contact.md

In this case, the pages will appear in the navigation menu in the order specified by the numerical prefixes.

Grouped Navigation

If your pages are organized into groups or subdirectories, you can still use filename prefix ordering within each group independently.

For example:

01-home.md
02-about.md
03-contact.md
04-api/
    01-readme.md
    02-installation.md
    03-getting-started.md

In this scenario, the pages within the "api" group will be ordered independently of the pages outside the group.

Conclusion

The filename prefix navigation ordering feature in HydePHP v2 offers a flexible and intuitive way to organize the navigation menus of your website or documentation project. By simply prefixing filenames with numbers, you can control the order of pages without the need for complex configuration settings.

(GPT-3.5-Turbo)

Numerical Prefix Navigation Ordering

HydePHP v2 introduces a new feature that allows navigation items to be ordered based on a numerical prefix in the filename. This feature provides a simple and efficient way to control the ordering of pages in both the primary navigation menu and the documentation sidebar.

Enabling the Feature

To enable the numerical prefix navigation ordering feature, simply include a numerical prefix followed by a hyphen in the filenames of your pages. The numerical prefix will determine the order of the pages in the navigation menus.

Ordering Pages

The numerical prefix is used to order pages in ascending order. Lower numerical prefixes will place the pages higher up in the navigation menus. You can use any integer value as the prefix, and pages without a prefix will default to the end of the menu.

Examples

Here are some examples to illustrate how the numerical prefix navigation ordering works:

• 01-home.md: This page will be placed first in the menu.
• 02-about.md: This page will be placed second in the menu.
• 03-contact.md: This page will be placed third in the menu.

Grouping Pages

You can also use numerical prefixes to group pages together. Pages with the same numerical prefix will be grouped together in the navigation menus, allowing for a more organized and structured menu.

Customization

While numerical prefixes provide a convenient way to order pages, you can still customize the order of individual pages using the priority option in the front matter of each page. This gives you flexibility to override the default numerical prefix ordering if needed.

By utilizing numerical prefixes in your page filenames, you can easily control the ordering of pages in your navigation menus, making it easier to create a cohesive and user-friendly website structure.

(GPT-4-Turbo)

Numerical Prefix Navigation Ordering

HydePHP v2 introduces a convenient way to control the order of pages by allowing you to prefix filenames with numbers. This simple numbering scheme determines the position of pages within navigation menus, ensuring a custom sequential layout without additional configurations.

Enabling and Understanding the Feature

This feature is enabled by default. To order your pages, prefix the filenames with numbers followed by a hyphen. For example:

• 01-Home.md
• 02-About.md
• 03-Contact.md

The navigation system interprets the numbers to sort the pages accordingly. Lower numbers result in earlier positions within the menu.

Benefits of Using Numerical Prefixes

Using numerical prefixes helps in organizing the content structurally without diving into configuration files for manual ordering. It's particularly useful for:

• Sequential Documentation: Order chapters or sections in a logical flow.
• Priority Content Placement: Highlight important pages by positioning them at the top of your menu.

Grouped and Nested Navigation

When using numerical prefixes within grouped or nested directories, each group can maintain its own independent numbering. For instance:

• /products/01-overview.md
• /products/02-details.md
• /services/01-introduction.md
• /services/02-portfolio.md

Each group (products, services) will order its pages based on the prefixes, independent of other groups.

Overriding Numerical Order

If you need to override the order specified by filenames temporarily or permanently, you can use the priority setting in the page's front matter. This is particularly handy for special cases where the numerical order doesn't suffice, or when adding new pages without renaming existing files.

Limitations and Considerations

• Uniform Prefix Length: Ensure consistency in prefix lengths (e.g., 01, 02 vs. 1, 2) to avoid unexpected sorting results.
• Disabling the Feature: You can disable this feature by setting a configuration option, allowing the site to revert to alphabetical or manually set priorities.

Practical Usage in a Site Structure

Consider a documentation site with various sections including installation guides, user manuals, and FAQs. Numerical prefixes can directly manage the flow and display of these sections to visitors, minimizing backend management overhead.

This powerful yet straightforward feature enhances HydePHP v2's capability to manage large amounts of content efficiently, reinforcing its utility in building well-structured, navigable websites.