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
    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