Liên kết tương đối GitHub trong tệp Markdown

Có cách nào để tạo một neo URL <a>, liên kết từ trong tệp Markdown, đến một tệp khác trong cùng một kho lưu trữ và chi nhánh (còn gọi là liên kết liên quan đến chi nhánh hiện tại) không?

Ví dụ: trong nhánh chính tôi có tệp README.md, tôi muốn làm một cái gì đó như:

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

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

Điều này sẽ cho phép tôi liên kết từ một .md đến một chi nhánh khác trong cùng một chi nhánh và không phải lo lắng về việc tôi đang ở chi nhánh nào (tránh phải thực hiện một URL tuyệt đối bao gồm tên chi nhánh github.com).

Đây là một ví dụ hoạt động về những gì tôi muốn nói:

1. GOTO http://github.com/rynop/testRel , liên kết không hoạt động.
2. GOTO http://github.com/rynop/testRel/blob/master/README.md , liên kết hoạt động.

Điều này được mong đợi vì tại thời điểm này, URL bắt đầu nằm trong nhánh. Bây giờ làm thế nào để tôi có được nó để lấy nhánh hiện tại trong README.md ở thư mục gốc của kho lưu trữ?

Cập nhật : Tôi đã mở một vấn đề chống lại GitHub cho yêu cầu tính năng này.

Cập nhật ngày 30 tháng 1 năm 2013 , 16 tháng sau:

GitHub Blog Post Liên kết tương đối trong các tệp đánh dấu :

Bắt đầu từ hôm nay, GitHub hỗ trợ các liên kết tương đối trong các tệp đánh dấu .
Bây giờ bạn có thể liên kết trực tiếp giữa các tệp tài liệu khác nhau, cho dù bạn xem tài liệu trên chính GitHub hoặc cục bộ, bằng cách sử dụng trình kết xuất đánh dấu khác.

Bạn muốn ví dụ về định nghĩa liên kết và cách chúng hoạt động? Đây là một số Markdown cho bạn.
Thay vì một liên kết tuyệt đối:

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

Bạn có thể sử dụng một liên kết tương đối:

[a relative link](other_file.md)

và chúng tôi sẽ đảm bảo nó được liên kết đến user/repo/blob/branch/other_file.md.

Nếu bạn đang sử dụng một cách giải quyết khác [a workaround link](repo/blob/master/other_file.md), bạn sẽ phải cập nhật tài liệu của mình để sử dụng cú pháp mới.

Điều này cũng có nghĩa là tài liệu của bạn giờ đây có thể dễ dàng tự đứng, mà không phải luôn luôn chỉ vào GitHub .

Cập nhật ngày 20 tháng 12 năm 2011:

Các vấn đề đánh dấu GitHub 84 hiện đang đóng bởi technoweenie , với lời nhận xét:

Chúng tôi đã thử thêm một <base>thẻ cho điều này, nhưng nó gây ra vấn đề với các liên kết tương đối khác trên trang web.

Ngày 12 tháng 10 năm 2011:

Nếu bạn nhìn vào nguồn thô củaREADME.md chính Markdown (!), Các đường dẫn tương đối dường như không được hỗ trợ.
Bạn sẽ tìm thấy các tài liệu tham khảo như:

[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

Ví dụ: bạn có một repo như sau:

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

Liên kết tương đối đến subtext.mdtrong text.mdcó thể trông như thế này:

[this subtext](subpro/subtext.md)

Liên kết tương đối đến subsubtext.mdtrong text.mdcó thể trông như thế này:

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

Liên kết tương đối đến subtext.mdtrong subsubtext.mdcó thể trông như thế này:

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

Liên kết tương đối đến subsubtext2.mdtrong subsubtext.mdcó thể trông như thế này:

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

Liên kết tương đối đến text.mdtrong subsubtext.mdcó thể trông như thế này:

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

Kể từ ngày 31 tháng 1 năm 2013, Github markdown hỗ trợ các liên kết tương đối đến các tệp .

[a relative link](markdown_file.md)

Tuy nhiên, có một vài thiếu sót đã được thảo luận trong chủ đề bình luận này .

Thay vào đó, bạn có thể sử dụng Gitdown để tạo URL đầy đủ cho kho lưu trữ và thậm chí làm cho chúng nhận biết được chi nhánh, ví dụ:

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

Gitdown là một bộ tiền xử lý đánh dấu GitHub. Nó sắp xếp hợp lý các tác vụ phổ biến liên quan đến việc duy trì trang tài liệu cho kho lưu trữ GitHub, ví dụ: tạo mục lục, bao gồm các biến, tạo URL và nhận thông tin về chính kho lưu trữ tại thời điểm xử lý đầu vào. Gitdown tích hợp liền mạch với các tập lệnh xây dựng của bạn.

Tôi là tác giả của thư viện Gitdown.

GitHub có thể làm điều này tốt hơn rất nhiều với công việc tối thiểu. Đây là một công việc xung quanh.

Tôi nghĩ bạn muốn một cái gì đó giống như

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

hoặc để chỉ vào README

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

Chúc may mắn

Chỉ muốn thêm điều này bởi vì không có giải pháp nào ở trên hoạt động nếu liên kết đích là thư mục có khoảng trắng trong tên của nó. Nếu liên kết đích là một thư mục và nó có không gian thì thậm chí thoát khỏi không gian với \ không hiển thị liên kết trên Github. Chỉ có giải pháp làm việc cho tôi là sử dụng %20cho từng không gian.

ví dụ: nếu cấu trúc thư mục là cái này

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

Để tạo liên kết đến Dir Atrong README.md, Top_dirbạn có thể làm điều này:

[Dir 1](Cur_dir1/Dir%20A)

Bạn có thể liên kết đến tệp, nhưng không liên kết với các thư mục và hãy nhớ rằng, Github sẽ thêm /blob/master/trước liên kết tương đối của bạn (và các thư mục thiếu phần đó để chúng không thể được liên kết, không có <a>thẻ HTML hoặc liên kết Markdown).

Vì vậy, nếu chúng ta có một tệp trong myrepo/src/Test.javađó, nó sẽ có một url như:

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

Và để liên kết nó trong tệp readme, chúng ta có thể sử dụng:

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

hoặc : <a href="src/Test.java">This is a link</a>.

(Tôi đoán, masterđại diện cho masterchi nhánh và nó khác khi tệp nằm trong một chi nhánh khác.)

Bạn có thể sử dụng URL tương đối từ gốc của repo của bạn với <a href="">. Giả sử repo của bạn được đặt tên testRel, hãy đặt như sau 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>

Câu hỏi này khá cũ, nhưng nó vẫn có vẻ quan trọng, vì không dễ để đưa các tài liệu tham khảo tương đối từ readme.md đến các trang wiki trên Github.

Tôi đã chơi xung quanh một chút và liên kết tương đối này có vẻ hoạt động khá tốt:

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

Cả hai ../sẽ loại bỏ /blob/master/và sử dụng căn cứ của bạn làm điểm bắt đầu. Mặc dù vậy, tôi chưa thử điều này trên các kho khác ngoài Github (có thể có vấn đề tương thích).

Tôi không chắc chắn nếu tôi thấy tùy chọn này ở đây. Bạn chỉ có thể tạo một /foldertrong kho lưu trữ của bạn và sử dụng nó trực tiếp:

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

Không có blob hoặc cây hoặc tên kho lưu trữ là cần thiết, và nó hoạt động như một bùa mê.

Nếu bạn muốn có một liên kết tương đối đến trang wiki của bạn trên GitHub, hãy sử dụng điều này:

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

Nếu bạn muốn liên kết đến một tệp trong kho lưu trữ, hãy giả sử, để tham chiếu một số tệp tiêu đề và trang wiki nằm ở thư mục gốc của wiki, hãy sử dụng:

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

Lý do cuối cùng là bỏ qua đường dẫn "/ wiki" với "../" và đi đến nhánh chính trong cây kho mà không chỉ định tên kho lưu trữ, có thể thay đổi trong tương lai.