RomanNum3ral
/
master
mirror of https://github.com/trimstray/the-book-of-secret-knowledge.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update SOP-Navigation-and-Layout.md

This commit is contained in:
Jacob Kraniak 2026-03-07 21:54:35 -05:00 committed by GitHub
parent bdab230e21
commit 77f486a144
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 83 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

144
SOP-Navigation-and-Layout.md
View File

@ -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 (`<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.
- **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](../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:
```
<details>
<summary>Expand: Network Engineering subtree</summary>
- [diagnostics-troubleshooting/](./diagnostics-troubleshooting/INDEX.md)
- ...
</details>
```
Use `<details>` 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
- `<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
- 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
<details>
<summary>Repository Structure (click to expand)</summary>
- **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)
</details>
### 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 `<details>` 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 `<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`
- 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.