navigation SOP: 2026-03-07 21:01:38

Affected files: .obsidian/workspace.json SOP-Navigation-and-Layout.md
2026-03-07 21:01:38 -05:00 · 2026-03-07 21:01:38 -05:00 · 63d8331a48
parent 1497b87d5b
commit 63d8331a48
2 changed files with 127 additions and 26 deletions
--- a/.obsidian/workspace.json
+++ b/.obsidian/workspace.json
@ -13,30 +13,15 @@
            "state": {
              "type": "markdown",
              "state": {
-                "file": "README.md",
+                "file": "SOP-Navigation-and-Layout.md",
                "mode": "source",
                "source": false
              },
              "icon": "lucide-file",
-              "title": "README"
-            }
-          },
-          {
-            "id": "6bdcf74dea1a2b7e",
-            "type": "leaf",
-            "state": {
-              "type": "markdown",
-              "state": {
-                "file": "conflict-files-obsidian-git.md",
-                "mode": "source",
-                "source": false
-              },
-              "icon": "lucide-file",
-              "title": "conflict-files-obsidian-git"
+              "title": "SOP-Navigation-and-Layout"
            }
          }
-        ],
-        "currentTab": 1
+        ]
      }
    ],
    "direction": "vertical"
@ -109,7 +94,7 @@
            "state": {
              "type": "backlink",
              "state": {
-                "file": "conflict-files-obsidian-git.md",
+                "file": "SOP-Navigation-and-Layout.md",
                "collapseAll": false,
                "extraContext": false,
                "sortOrder": "alphabetical",
@ -119,7 +104,7 @@
                "unlinkedCollapsed": true
              },
              "icon": "links-coming-in",
-              "title": "Backlinks for conflict-files-obsidian-git"
+              "title": "Backlinks for SOP-Navigation-and-Layout"
            }
          },
          {
@ -128,12 +113,12 @@
            "state": {
              "type": "outgoing-link",
              "state": {
-                "file": "conflict-files-obsidian-git.md",
+                "file": "SOP-Navigation-and-Layout.md",
                "linksCollapsed": false,
                "unlinkedCollapsed": true
              },
              "icon": "links-going-out",
-              "title": "Outgoing links from conflict-files-obsidian-git"
+              "title": "Outgoing links from SOP-Navigation-and-Layout"
            }
          },
          {
@ -171,13 +156,13 @@
            "state": {
              "type": "outline",
              "state": {
-                "file": "conflict-files-obsidian-git.md",
+                "file": "SOP-Navigation-and-Layout.md",
                "followCursor": false,
                "showSearch": false,
                "searchQuery": ""
              },
              "icon": "lucide-list",
-              "title": "Outline of conflict-files-obsidian-git"
+              "title": "Outline of SOP-Navigation-and-Layout"
            }
          },
          {
@ -209,9 +194,10 @@
      "obsidian-git:Open Git source control": false
    }
  },
-  "active": "6bdcf74dea1a2b7e",
+  "active": "9b2e89c682f5d2ef",
  "lastOpenFiles": [
    "README.md",
+    "SOP-Navigation-and-Layout.md",
    "conflict-files-obsidian-git.md",
    "tools/_INDEX.md",
    "documentation/INDEX.md",
@ -237,7 +223,6 @@
    "tools/tools - (migrate out)/web-tools.md",
    "documentation/readme - to refactor.md",
    "documentation/manuals-howtos-guides/shell-tricks-functions.md",
-    "documentation/other-cheat-sheets.md",
    "documentation/manuals-howtos-guides",
    "documentation",
    "tools/security/hardening-compliance",
--- a/SOP-Navigation-and-Layout.md
+++ b/SOP-Navigation-and-Layout.md
@ -0,0 +1,116 @@
+# 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](./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:
+
+```markdown
+# [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):
+
+```markdown
+<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](./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](./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/`.