master/SOP-Navigation-and-Layout.md

SOP: Repository Layout, Navigation & Index Files

Purpose
This SOP defines the standard structure, naming conventions, linking rules, and maintenance practices for the Book of Secret Knowledge fork (JK_Revisions branch). The goal is to keep the repo highly navigable on GitHub, consistent across folders, and easy to extend as new categories/tools are added.

Last Updated: March 2026
Applies to: All folders, especially tools/, documentation/, and root-level files

1. Core Principles

• Navigation-first design — Every folder with >2 subfolders or >3 .md files should have an INDEX.md file.
• Hyperlinks everywhere — All references to files, folders, external sites, GitHub repos, and the schema must be clickable.
• Consistency over perfection — Use the same patterns (naming, table styles, link formats) across the repo.
• GitHub rendering — Prefer native markdown features (<details>, tables, relative links) over code blocks for interactive elements.
• Tool tables only — All tool/resource lists follow TOOL-TABLE-SCHEMA.md exactly.

2. Naming Conventions

File/Folder Type	Recommended Name	Notes / Alternatives
Navigation / overview file	INDEX.md	Uppercase I. Use this instead of README.md in content-heavy folders to distinguish from regular docs. GitHub renders it as folder preview.
Legacy / old index	_INDEX.md or 00_index.md	Rename → INDEX.md when possible for cleaner sorting and visibility.
Tool/resource list files	Lowercase-with-dashes.md	e.g. dns-tools.md, shell-one-liners.md
Personal section	my-contributions.md	Keep at tools/ root
Schema reference	TOOL-TABLE-SCHEMA.md	Root level, never move

Rule: Avoid spaces in file names (use - or _). Encode special characters in links if needed (e.g. %20 for space, %26 for &).

3. Folder-Level INDEX.md Structure (Minimum Template)

Every INDEX.md should include:

# [Category Name] Index

Short 1–2 sentence purpose of this folder.

All tool tables follow → [TOOL-TABLE-SCHEMA.md](../TOOL-TABLE-SCHEMA.md)

## Sub-categories & Files

| Section / Topic              | Description                                      | Link |
|------------------------------|--------------------------------------------------|------|
| Example Subfolder            | What it contains                                 | [subfolder/INDEX.md](./subfolder/INDEX.md) |
| Example File                 | Brief note                                       | [example-file.md](./example-file.md) |

### Quick Links / Backlinks
- [↑ Back to Tools Overview](../_INDEX.md) (or ../INDEX.md)
- [↑ Back to Root README.md](../../README.md)

Use <details> for long lists if desired.

4. Top-Level README.md Requirements

Must contain (at minimum, near the top):

• Brief mission/fork statement
• <details><summary> collapsible directory structure (indented markdown list with hyperlinks)
• Quick Access table linking to major entry points
• Reference to this SOP and the TOOL-TABLE-SCHEMA

Example snippet (update paths as needed):

<details>
<summary>Repository Structure (click to expand)</summary>

- **tools/** — ...
  - [_INDEX.md](./tools/_INDEX.md) — ...
- ...

</details>

### Quick Access
| Area          | Link                                 |
|---------------|--------------------------------------|
| Tools         | [tools/_INDEX.md](./tools/_INDEX.md) |
| ...           | ...                                  |

5. Linking Rules (Mandatory)

Context	Format / Example
Internal file	[shell-one-liners.md](./manuals-howtos-guides/shell-one-liners.md)
Internal folder	[diagnostics-troubleshooting/](./network-engineering/diagnostics-troubleshooting/)
Schema reference	[TOOL-TABLE-SCHEMA.md](../TOOL-TABLE-SCHEMA.md)
GitHub repo in tool table	[trimstray/multitool](https://github.com/trimstray/multitool)
Official site in tool table	[Official Site](https://example.com) or —
Upward navigation	[↑ Tools Overview](../_INDEX.md) or [↑ Root](../../README.md)

6. Maintenance Checklist (When Adding/Editing)

• Create or update INDEX.md in the folder if missing or outdated
• Add relative hyperlinks to all mentioned files/folders
• Ensure tool tables match TOOL-TABLE-SCHEMA.md columns exactly
• Update parent INDEX.md and top-level README.md if structure changes significantly
• Use <details> for long collapsible sections
• Commit message includes affected areas, e.g. "Add INDEX.md to security/; update README quick links"

7. Future Improvements (Nice-to-Have)

• Rename tools/_INDEX.md → tools/INDEX.md
• Add file/tool counts to overview tables
• Create all-tools.md (A–Z consolidated list) if repo grows very large
• Add badges (stars, last commit) to README.md
• Consider GitHub wiki for very long guides (keep core content in repo)

Questions or deviations? Open an issue or PR referencing this SOP.

Happy building!

This SOP is self-contained, actionable, and reinforces the patterns we've established. Once added, link to it from the top-level README.md (e.g. in the Quick Access table or at the bottom: "See SOP-Navigation-and-Layout.md for layout standards").

Let me know if you'd like tweaks (shorter version, more examples, move to a different location), or if the next step is generating INDEX.md for a specific subfolder like tools/security/ or tools/sysadmin-devops/.