Skip to content

Rename index.md to _index.md for better repository navigation #164

Description

@qiujuer

Summary

I would like to propose renaming every index.md file in the repository to _index.md.

Current structure:

path/to/bundle/
├── index.md
├── log.md
├── <concept>.md
└── <subdirectory>/
    ├── index.md
    ├── <concept>.md
    └── <subdirectory>/
        └── …

Proposed structure:

path/to/bundle/
├── _index.md
├── log.md
├── <concept>.md
└── <subdirectory>/
    ├── _index.md
    ├── <concept>.md
    └── <subdirectory>/
        └── …

Motivation

When browsing the repository on GitHub or in most IDEs/editors, files are typically sorted alphabetically.

Using _index.md places the bundle entry file at the top of the directory, making it much easier to:

  • Quickly identify the entry document for a bundle.
  • Reduce the time spent searching for index.md among many files.
  • Improve manual review and repository navigation.
  • Provide a more consistent visual structure across all bundle directories.

This is especially helpful in directories containing many concept files, where the entry document is frequently accessed.

Benefits

  • Better discoverability of the bundle entry file.
  • Improved developer experience when navigating the repository.
  • No change to the document contents or organization—only the filename.

If there are no tooling or compatibility constraints requiring the filename to remain index.md, I think _index.md would provide a small but meaningful usability improvement.

Thanks for considering this suggestion!

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions