GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

Proposal: nearest index.md file as root for `@/` links and referenceable by `@folder_name/` links

Open
#194 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.