GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
Proposal: nearest index.md file as root for `@/` links and referenceable by `@folder_name/` links
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
## The Idea
Instead of the concept's entire path being part of it's identity/name and to allow portability (and shenanigans such as sub-bundles and cross-bundle linking)
Define "from nearest matching `@named` index.md file" as a valid linking strategy.
From within a file, you can make a link using `@/` to link from the nearest index,md file as the root.
You can also `@other_scope` to link from the nearest (sibling of nearest index.md file? upwards from it?) as the start of a link.
Wikilinks can resolved based on nearest scope so `[[x_concept]]` checks from the nearest index.md file first for files named `x_concept.md` and then goes up scopes afterwards?
## How did I get here / Example
I'm trying to organize a markdown file based document writing project...
Sub directories MAY have their own index.md but that... sometimes overkill especially if you are trying to have separate domain areas...
So far I've settled on...
```
project_root/
index.md
world_info/
index.md
feedback/
index.md
planning/
index.md
```
with NO deeper index.md files since that seems like a headache to stay on top of... but alsooooo
I was thinking it would be really great to have the ability to make links be relative to the nearest index.md file and the "source-root alias" link convention used by some coding projects is unused. "@package_name"
So I was thinking I could do things like `@character/bob.md` from inside another file within world_info... or from that file link to `@/mechanics/magic_system.md` (deliberately generic examples sorry)
in a planning document I could use "@world_info/xyz" to refer to another directory scoped by having an index.md file...
Now I looked in this repo/online to see what others were cooking up and... there's a few issues where this idea could help.
# Issues
The biggest issue I see is that... the **presence** of a `index.md` or not becomes semantically/structurally meaningful and might break setups that already exist... but also `@scoped_links` aren't used anywhere so this might not be a huge issue?
# Related?
#176 #120 #
Contributor guide
Research direction
The issue names no files, tests, or entry points. First clarify the nearest index.md and @scope resolution rules, then inspect the existing Markdown link and wikilink handling; done means agreed behavior for nested index.md layouts and compatibility with existing links.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown, typescript
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100