master/SOP-Navigation-and-Layout.md

Revised SOP-Navigation-and-Layout.md (full suggested content)

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 (Updated)

• Navigation-first design — Every folder containing subfolders or >2–3 .md files must have an INDEX.md.
• Recursive TOC in every INDEX.md — Show the full subtree (nested folders + files) using indented, hyperlinked markdown lists. Use <details> + <summary> for collapsible deep sections to avoid overwhelming long pages.
• Tabular lists preferred over full markdown tables — For folder overviews / quick indexes use definition lists, bolded bullets, or simple indented pairs instead of | Name | Description | Link | tables.
• Hyperlinks everywhere — All files, folders, external sites, GitHub repos, and the schema must be clickable (relative links whenever possible).
• Consistency over perfection — Use the same patterns (naming, list styles, link formats) across the repo.
• GitHub rendering — Prefer native markdown (<details>, relative links, lists) over code blocks for interactive elements.
• Tool tables only — All tool/resource lists follow TOOL-TABLE-SCHEMA.md exactly (those remain proper tables).

2. Naming Conventions

• Navigation / overview file: INDEX.md (uppercase I) — preferred over README.md in content folders
  Alternatives (legacy only): _INDEX.md, 00_index.md
• 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: No spaces in file/folder names (use - or _). Escape special characters in links when needed.

3. Folder-Level INDEX.md Structure (Recommended Template – Updated)

Every INDEX.md should follow this minimal layout:

[Category Name] Index

Short 1–2 sentence purpose of this folder.

All tool tables in this section follow → TOOL-TABLE-SCHEMA.md

Contents (Recursive Overview)

• Subfolder A — brief one-line description of what it contains

  • file-one.md — short note
  • file-two.md — short note
  • Nested Subfolder — purpose
    • deep-file.md

• Subfolder B — brief description

  • ...

• Standalone Files

  • example-file.md — purpose / note
  • another.md

Quick Navigation

• ↑ Back to Parent Index (or ../_INDEX.md for legacy)
• ↑ Back to Tools Root (adjust level as needed)
• ↑ Repository Root

For deeper folders, wrap large subtrees in:

<details>
<summary>Expand: Network Engineering subtree</summary>

- [diagnostics-troubleshooting/](./diagnostics-troubleshooting/INDEX.md)
  - ...
</details>

This creates a recursive, explorable map without forcing the reader to click into every folder.

4. Top-Level README.md Requirements (Updated)

Near the top, include:

• Brief mission/fork statement
• Collapsible recursive-ish directory structure (use indented list with key folders hyperlinked; full recursion optional here to avoid bloat)
• Quick Access section using a simple tabular list (not full table)

Example:

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

- **[tools/](./tools/INDEX.md)** — main tool & resource collections
  - [my-contributions.md](./tools/my-contributions.md)
  - **[network-engineering/](./tools/network-engineering/INDEX.md)**
  - **[security/](./tools/security/INDEX.md)**
  - ...
- **[documentation/](./documentation/INDEX.md)** — guides, cheat sheets, learning
- [TOOL-TABLE-SCHEMA.md](./TOOL-TABLE-SCHEMA.md) — mandatory table format
- [SOP-Navigation-and-Layout.md](./SOP-Navigation-and-Layout.md)

</details>

### Quick Access
- **Tools Overview** → [tools/_INDEX.md](./tools/_INDEX.md) (or INDEX.md once renamed)
- **Documentation & Guides** → [documentation/INDEX.md](./documentation/INDEX.md)
- **Schema Rules** → [TOOL-TABLE-SCHEMA.md](./TOOL-TABLE-SCHEMA.md)
- **This SOP** → [SOP-Navigation-and-Layout.md](./SOP-Navigation-and-Layout.md)

5. Linking Rules (Mandatory – no change)

• Internal file: [shell-one-liners.md](./manuals-howtos-guides/shell-one-liners.md)
• Internal folder: [diagnostics-troubleshooting/](./network-engineering/diagnostics-troubleshooting/)
• Schema: [TOOL-TABLE-SCHEMA.md](../TOOL-TABLE-SCHEMA.md)
• Upward: ↑ [Tools Overview](../_INDEX.md) or ↑ [Root](../../README.md)

6. Maintenance Checklist (When Adding/Editing – Updated)

• Create/update INDEX.md in every qualifying folder
• Build recursive contents list with relative hyperlinks
• Use tabular lists (bold bullets / definition style) instead of tables for index overviews
• Ensure tool-list .md files match TOOL-TABLE-SCHEMA.md exactly
• Update parent INDEX.md and root README.md when structure changes
• Use <details> liberally for deep recursion
• Commit message example: "feat: recursive INDEX.md for security/; tabular list conversion"

7. Future Improvements (Nice-to-Have)

• Rename tools/_INDEX.md → tools/INDEX.md for consistency
• Add item counts next to folders in recursive lists (e.g. (12 tools) )
• Consider a single all-tools.md A–Z list if repo becomes very large
• Explore GitHub Actions to auto-generate/update recursive INDEX files

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

Happy building!