GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

Rename `index.md` to `_index.md` for better repository navigation

Open
#164 2 comments 10 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
9.2k
Forks
782
Avg merge
6h 36m
Merged PRs (30d)
85

Description

## Summary

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

Current structure:

```text
path/to/bundle/
├── index.md
├── log.md
├── .md
└── /
├── index.md
├── .md
└── /
└── …
```

Proposed structure:

```text
path/to/bundle/
├── _index.md
├── log.md
├── .md
└── /
├── _index.md
├── .md
└── /
└── …
```

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

Contributor guide

Open the contributing guide

Research direction

Start by locating every index.md file and checking repository tooling or references that depend on that filename. Rename the bundle entry files to _index.md only if compatibility is preserved; done means all intended files are consistently renamed and repository navigation still works.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown
Domain
documentation
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.