Относительная ссылка GitHub в файле Markdown

832

Есть ли способ создать <a>привязку URL-адреса , ссылку из файла Markdown, на другой файл в том же хранилище и ветви (или ссылку относительно текущей ветви)?

Например, в основной ветке у меня есть файл README.md, который я хотел бы сделать что-то вроде:

# My Project
is really really cool. My Project has a subdir named myLib, see below.

## myLib documentation
see documentation [here](myLib/README.md)

Это позволило бы мне ссылаться с одного .md на другой в пределах одной и той же ветви и не беспокоиться о том, в какую ветку я нахожусь (избегайте создания абсолютного URL-адреса, включающего имя ветви github.com).

Вот рабочий пример того, что я имею в виду:

  1. GOTO http://github.com/rynop/testRel , ссылка не работает.
  2. GOTO http://github.com/rynop/testRel/blob/master/README.md , ссылка работает.

Это ожидается, потому что на данный момент начальный URL находится в ветви. Как мне получить текущую ветку в файле README.md в корне хранилища?

Обновление : я открыл проблему против GitHub для этого запроса функции.

rynop
источник
21
Наконец : относительные ссылки теперь поддерживаются! Я обновил свой ответ :)
VonC
Это хорошая информация, если вы пытаетесь открыть другой .md или перейти на другой веб-сайт http / s или html или даже .jpg, .png или jpeg, но как сделать Markdown открытием .pdf? Я не могу получить правильный синтаксис, чтобы он открывал мой .pdf, который находится в том же каталоге, что и файл .md. Кто-нибудь может помочь открыть .pdf?
Элтон
Вы можете найти некоторые решения в этом вопросе: stackoverflow.com/questions/40422790/…
Oleg Pro

Ответы:

971

Обновление 30 января 2013 г. , 16 месяцев спустя:

GitHub Blog Post Относительные ссылки в файлах разметки :

Начиная с сегодняшнего дня, GitHub поддерживает относительные ссылки в файлах разметки .
Теперь вы можете связывать напрямую между различными файлами документации, независимо от того, просматриваете ли вы документацию на самом GitHub или локально, с помощью другого средства визуализации разметки.

Вы хотите примеры определений ссылок и как они работают? Вот некоторая уценка для вас.
Вместо абсолютной ссылки:

[a link](https://github.com/user/repo/blob/branch/other_file.md)

... вы можете использовать относительную ссылку:

[a relative link](other_file.md)

и мы позаботимся о том, чтобы это было связано с user/repo/blob/branch/other_file.md.

Если вы использовали подобный обходной путь [a workaround link](repo/blob/master/other_file.md), вам придется обновить документацию, чтобы использовать новый синтаксис.

Это также означает, что ваша документация теперь может легко стоять сама по себе, не всегда указывая на GitHub .


Обновление от 20 декабря 2011 года:

Проблема разметки GitHub 84 в настоящее время закрыта technoweenie с комментарием:

Мы попытались добавить <base>тег для этого, но это вызывает проблемы с другими относительными ссылками на сайте.


12 октября 2011 г .:

Если вы посмотрите на исходный источник самойREADME.md Markdown (!), Относительные пути не поддерживаются.
Вы найдете ссылки, такие как:

[r2h]: http://github.com/github/markup/tree/master/lib/github/commands/rest2html
[r2hc]: http://github.com/github/markup/tree/master/lib/github/markups.rb#L13
VonC
источник
1
Хм ... я могу сделать относительный URL (попробуйте [link] someDir / README.md, он сделает якорь) - но я хочу, чтобы относительная ссылка поддерживала ветку github, например: myRepo / tree / <$ curBranch> /pathToMd.md , Я, вероятно, просто открою запрос на функцию с github.com
rynop
1
нет. Смотрите полный пример здесь github.com/rynop/testRel . Я мог бы сделать относительную ссылку с указанием ветви, но это в первую очередь противоречит цели того, что я пытаюсь сделать. Если бы я ссылался из .md в одном подкаталоге на другой, я думаю, он справился бы с относительной ссылкой просто отлично. Проблема возникает при линковке из .md в корень репо.
Рыноп
2
Связано: [Welcome](./wiki/Hello)Работает для ссылки с одной вики-страницы на другую , где Hello - это еще одна вики-страница в том же репо.
Уэйн Блосс
1
@wizlb Я только что попробовал без пути, и он тоже работает, [Welcome](Hello)где Hello - другая вики-страница в том же репо.
Мотти
2
Это работает на обычных вики-страницах, но если вы добавляете файл _Sidebar.md, есть разница между тем, как ссылки разрешаются на домашней странице вики, по сравнению с остальными страницами. Я попробовал все здесь без удачи. Единственное, что я до сих пор придумал, - это использование 2 разных файлов _Sidebar.md и организация файлов в подкаталоги.
NightOwl888
93

Например, у вас есть репозиторий, подобный следующему:

project/
    text.md
    subpro/
       subtext.md
       subsubpro/
           subsubtext.md
       subsubpro2/
           subsubtext2.md

Относительная ссылка на subtext.mdin text.mdможет выглядеть так:

[this subtext](subpro/subtext.md)

Относительная ссылка на subsubtext.mdin text.mdможет выглядеть так:

[this subsubtext](subpro/subsubpro/subsubtext.md)

Относительная ссылка на subtext.mdin subsubtext.mdможет выглядеть так:

[this subtext](../subtext.md)

Относительная ссылка на subsubtext2.mdin subsubtext.mdможет выглядеть так:

[this subsubtext2](../subsubpro2/subsubtext2.md)

Относительная ссылка на text.mdin subsubtext.mdможет выглядеть так:

[this text](../../text.md)
mathsyouth
источник
1
Одна вещь, которую я нашел, ссылки чувствительны к регистру, чего я не ожидал.
Энди Визендангер
Что если в моих каталогах есть пробелы?
Ришав
16

По состоянию на 31 января 2013 года уценка Github поддерживает относительные ссылки на файлы .

[a relative link](markdown_file.md)

Однако есть несколько недостатков, которые обсуждались в этой ветке комментариев .

В качестве альтернативы, вы можете использовать Gitdown, чтобы создать полные URL-адреса для хранилища и даже сделать их осведомленными о ветвлении, например,

{"gitdown": "gitinfo", "name": "url"} // https://github.com/gajus/gitdown
{"gitdown": "gitinfo", "name": "branch"} // master

Gitdown - это препроцессор GitHub. Он упрощает общие задачи, связанные с ведением страницы документации для репозитория GitHub, например, генерацию оглавления, включая переменные, генерацию URL и получение информации о самом репозитории во время обработки ввода. Gitdown легко интегрируется с вашими строительными скриптами.

Я являюсь автором библиотеки Gitdown.

Gajus
источник
1
@Thomas Является ли это частью условий использования Stack Overflow? Если да, пожалуйста, поделитесь ссылкой. Мне любопытно узнать мотивацию такого требования.
Gajus
5
«Публикуйте хорошие, релевантные ответы, и если некоторые (но не все) касаются вашего продукта или веб-сайта, это нормально. Однако вы должны указать свою принадлежность в своих ответах». stackoverflow.com/help/behavior
Томас
1
Можно было бы подумать, что это подпадает под метаинформацию, которую Stack Overflow пытается избежать так много, то есть это способствует обсуждению вне темы.
Gajus
14

GitHub может сделать это намного лучше с минимальной работой. Вот обходной путь.

Я думаю, что вы хотите что-то более похожее

[Your Title](your-project-name/tree/master/your-subfolder)

или указать на README сам

[README](your-project-name/blob/master/your-subfolder/README.md)

Удачи

Алан Виарс
источник
3
да, это то, что я делаю сегодня. Я не хочу запекать в ветке информацию в ссылку. Это должно быть относительным.
rynop
8

Просто хотел добавить это, потому что ни одно из вышеприведенных решений не сработало, если целевой ссылкой является каталог с пробелами в имени. Если целевая ссылка - это каталог, и в нем есть место, то даже выход из пробела с \ не отображает ссылку на Github. Только решение, сработавшее для меня, использует %20для каждого пространства.

Например: если структура каталогов это

Top_dir
|-----README.md
|-----Cur_dir1
      |----Dir A
           |----README.md
      |----Dir B
           |----README.md

Чтобы сделать ссылку на Dir AREADME.md, Top_dirвы можете сделать это:

[Dir 1](Cur_dir1/Dir%20A)
InvisibleWolf
источник
8

Вы можете ссылаться на файл, но не на папки, и имейте в виду, что Github добавит их /blob/master/перед вашей относительной ссылкой (а папкам не хватает этой части, поэтому они не могут быть связаны ни с HTML- <a>тегами , ни со ссылками на Markdown).

Итак, если у нас есть файл myrepo/src/Test.java, он будет иметь вид:

https://github.com/WesternGun/myrepo/blob/master/src/Test.java

И чтобы связать его в файле readme, мы можем использовать:

[This is a link](src/Test.java)

или: <a href="src/Test.java">This is a link</a>.

(Я думаю, masterпредставляет masterветвь, и она отличается, когда файл находится в другой ветке.)

WesternGun
источник
7

Вы можете использовать относительные URL из корня вашего репо с <a href="">. Предполагая, что ваш репо назван testRel, введите следующее testRel/README.md:

# My Project
is really really cool. My Project has a subdir named myLib, see below.

## myLib docs
see documentation:
    * <a href="testRel/myLib">myLib/</a>
    * <a href="testRel/myLib/README.md">myLib/README.md</a>
Джон Чейз
источник
3
это недопустимый синтаксис md
astroanu
6

Этот вопрос довольно старый, но он все еще кажется важным, поскольку нелегко поместить относительные ссылки с readme.md на вики-страницы на Github.

Я немного поиграл, и эта относительная ссылка, кажется, работает довольно хорошо:

[Your wiki page](../../wiki/your-wiki-page)

Эти двое ../будут удалять /blob/master/и использовать вашу базу в качестве отправной точки. Я не пробовал это на других репозиториях, кроме Github, хотя (могут быть проблемы с совместимостью).

Alex
источник
4

Я не уверен, вижу ли я эту опцию здесь. Вы можете просто создать /folderв своем хранилище и использовать его напрямую:

[a relative link](/folder/myrelativefile.md)

Никакое имя BLOB, дерева или хранилища не требуется, и оно работает как шарм.

Антонио Карлос Рибейро
источник
1
Вы могли бы подумать, что это очевидный путь, но он не работает для меня.
Kmeixner
4

Если вы хотите относительную ссылку на вашу вики-страницу на GitHub, используйте это:

Read here: [Some other wiki page](path/to/some-other-wiki-page)

Если вы хотите, чтобы ссылка на файл в хранилище, скажем, ссылалась на какой-то заголовочный файл, а страница вики находится в корне вики, используйте это:

Read here: [myheader.h](../tree/master/path/to/myheader.h)

Обоснование последнего состоит в том, чтобы пропустить путь "/ wiki" с помощью "../" и перейти к главной ветви в дереве хранилища без указания имени хранилища, которое может измениться в будущем.

elomage
источник