diff --git a/SOP-Navigation-and-Layout.md b/SOP-Navigation-and-Layout.md index ad69525..32db204 100644 --- a/SOP-Navigation-and-Layout.md +++ b/SOP-Navigation-and-Layout.md @@ -1,3 +1,5 @@ +### Revised SOP-Navigation-and-Layout.md (full suggested content) + # SOP: Repository Layout, Navigation & Index Files **Purpose** @@ -6,106 +8,126 @@ This SOP defines the standard structure, naming conventions, linking rules, and **Last Updated**: March 2026 **Applies to**: All folders, especially `tools/`, `documentation/`, and root-level files -## 1. Core Principles +## 1. Core Principles (Updated) -- **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 (`
`, tables, relative links) over code blocks for interactive elements. -- **Tool tables only** — All tool/resource lists follow [TOOL-TABLE-SCHEMA.md](./TOOL-TABLE-SCHEMA.md) exactly. +- **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 `
` + `` 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 (`
`, relative links, lists) over code blocks for interactive elements. +- **Tool tables only** — All tool/resource lists follow [TOOL-TABLE-SCHEMA.md](../TOOL-TABLE-SCHEMA.md) exactly (those remain proper tables). ## 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 | +- 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**: Avoid spaces in file names (use `-` or `_`). Encode special characters in links if needed (e.g. `%20` for space, `%26` for &). +**Rule**: No spaces in file/folder names (use `-` or `_`). Escape special characters in links when needed. -## 3. Folder-Level INDEX.md Structure (Minimum Template) +## 3. Folder-Level INDEX.md Structure (Recommended Template – Updated) -Every `INDEX.md` should include: +Every `INDEX.md` should follow this minimal layout: -```markdown # [Category Name] Index Short 1–2 sentence purpose of this folder. -All tool tables follow → [TOOL-TABLE-SCHEMA.md](../TOOL-TABLE-SCHEMA.md) +All tool tables in this section follow → [TOOL-TABLE-SCHEMA.md](../TOOL-TABLE-SCHEMA.md) -## Sub-categories & Files +## Contents (Recursive Overview) -| 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) | +- **[Subfolder A](./subfolder-a/INDEX.md)** — brief one-line description of what it contains + - [file-one.md](./subfolder-a/file-one.md) — short note + - [file-two.md](./subfolder-a/file-two.md) — short note + - **[Nested Subfolder](./subfolder-a/nested/INDEX.md)** — purpose + - [deep-file.md](./subfolder-a/nested/deep-file.md) -### Quick Links / Backlinks -- [↑ Back to Tools Overview](../_INDEX.md) (or ../INDEX.md) -- [↑ Back to Root README.md](../../README.md) +- **[Subfolder B](./subfolder-b/INDEX.md)** — brief description + - ... + +- **Standalone Files** + - [example-file.md](./example-file.md) — purpose / note + - [another.md](./another.md) + +## Quick Navigation +- ↑ [Back to Parent Index](../INDEX.md) (or `../_INDEX.md` for legacy) +- ↑ [Back to Tools Root](../_INDEX.md) (adjust level as needed) +- ↑ [Repository Root](../../README.md) + + +**For deeper folders**, wrap large subtrees in: + +``` +
+Expand: Network Engineering subtree + +- [diagnostics-troubleshooting/](./diagnostics-troubleshooting/INDEX.md) + - ... +
``` -Use `
` for long lists if desired. +This creates a recursive, explorable map without forcing the reader to click into every folder. -## 4. Top-Level README.md Requirements +## 4. Top-Level README.md Requirements (Updated) -Must contain (at minimum, near the top): +Near the top, include: - Brief mission/fork statement -- `
` 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 +- 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 snippet (update paths as needed): +Example: ```markdown
Repository Structure (click to expand) -- **tools/** — ... - - [_INDEX.md](./tools/_INDEX.md) — ... -- ... +- **[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)
### Quick Access -| Area | Link | -|---------------|--------------------------------------| -| Tools | [tools/_INDEX.md](./tools/_INDEX.md) | -| ... | ... | +- **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) +## 5. Linking Rules (Mandatory – no change) -| 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)` | +- 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) +## 6. Maintenance Checklist (When Adding/Editing – Updated) -- [ ] 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](./TOOL-TABLE-SCHEMA.md) columns exactly -- [ ] Update parent INDEX.md and top-level README.md if structure changes significantly -- [ ] Use `
` for long collapsible sections -- [ ] Commit message includes affected areas, e.g. "Add INDEX.md to security/; update README quick links" +- 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](../TOOL-TABLE-SCHEMA.md) exactly +- Update parent `INDEX.md` and root `README.md` when structure changes +- Use `
` 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` -- 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) +- 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.