diff --git a/.obsidian/workspace.json b/.obsidian/workspace.json index ae16e3e..b7b6d26 100644 --- 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", diff --git a/SOP-Navigation-and-Layout.md b/SOP-Navigation-and-Layout.md new file mode 100644 index 0000000..8a8a8ef --- /dev/null +++ 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 (`
`, 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 `
` for long lists if desired. + +## 4. Top-Level README.md Requirements + +Must contain (at minimum, near the top): + +- 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 + +Example snippet (update paths as needed): + +```markdown +
+Repository Structure (click to expand) + +- **tools/** — ... + - [_INDEX.md](./tools/_INDEX.md) — ... +- ... + +
+ +### 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 `
` 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/`. \ No newline at end of file