How to reference other .md files in README.md

sboss December 21, 2014

 

I have read the docs but can't figure out how to reference other .md files in the README.md.  I have some .md files in the root and subdirectories (folders) that I want to reference in the README.md for people to read.

I am probably doing something very simple that is wrong.  Please point me in the right direction.

thanks

sb

1 answer

0 votes
Boris Berenberg
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
December 22, 2014

Are you trying to create links to those files, and then have Bitbucket render those files for you? If so, this syntax should work to create the link: http://daringfireball.net/projects/markdown/syntax#link Though I am not sure how BB will handle it.

Or are you trying to include them to essentially build a README.md out of component files?

sboss December 23, 2014

Boris,

Thanks for your response. It is the former over the later.  I followed the syntax on the daring fireball website.  But whatever link I use to the subdocs or secondary docs (whatever you want to call them), I get nasty 404 errors saying it can't find my docs (.md files).

any advice on the structure of the URL links would be great.

thanks

scott

Boris Berenberg
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
December 23, 2014

http://stackoverflow.com/questions/4779582/markdown-and-including-multiple-files I don't think that Markdown itself has support for including other files. My recommendation would be to have the README.md file built using a pre-commit script. There is no limitation on links within Markdown, and all Bitbucket does is render it. Your links should just be the links you see in your browser's url bar when you view the .md file in your repo as a user which has access to it. You can use http://www.markdownviewer.com/ to test your syntax on the fly.

Chris M_ June 21, 2019

Hi guys,

I'm not sure if i am in the right place, but I'll have a try:

We use a server version of Bitbucket (currently 5.16) in our company and have project with 15+ repositories.

Now from the documentation (MARKDOWN) of one repo (e.g. from the main README.md) I want to link to information in another repo.

Say we have

MyProject
|-repo1
| |-README.md
| `-other_stuff
|
`-repo2
|-docs
| |-index.md
| `-setup.md
`-other_stuff

So I want to create a link in repo1/README.md to repo2/docs/setup.md.

 

Locally (e.g. when viewing the markdown in my IDE or browser), it is as simple as

See [here](../repo2/docs/setup.md) for setup.

But when I use the docs in the Bitbucket Web UI, the links don't work and lead to a "404 dead link" page.

I figure that the reason is the "virtual" /browse folder that bitbucket creates.

When viewing the Readme, I have the url

https://our.bitbucket.server/projects/MyProject/repos/repo1/browse/README.md

, so ../repo2/docs/setup.md leads to

... /repo1/repo2/docs/setup.md

 

I'm wondering if this can be mitigated somehow. So far I just created two links, one that works locally (in the "normal" file structure) and one that works on bitbucket with the extra "directories":

See [here](../repo2/docs/setup.md) for setup (or [here](../../repo2/browse/docs/setup.md) if you are on Bitbucket).

 But this is kind of ugly and possibly confusing to others.

 

I read some tickets here, but all of them seem to be resolved and don't say for which version and also don't explicitly mention the /browse problem... Like:

https://bitbucket.org/site/master/issues/6315

https://bitbucket.org/site/master/issues/7504/

https://bitbucket.org/site/master/issues/15949/

Especially the last one seems to relate to this problem. So, I wonder how (or where) this was fixed and hope I get some helpful information here.

 

Thank you! :-)

Earl McCutcheon
Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
June 21, 2019

Hi Chris, 

As this is a 3 year old post it may not get any traction in this location so I created a new post from your comment to get some additional attention, the new post is viewable here:

Regards,
Earl

Suggest an answer

Log in or Sign up to answer
TAGS
AUG Leaders

Atlassian Community Events