How to reference other .md files in README.md

Question

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

Earl McCutcheon · Answer

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:

* https://community.atlassian.com/t5/Bitbucket-questions/Re-How-to-reference-other-md-files-in-README-md/qaq-p/1113742

Regards,
Earl

Chris M__otzji0 · Answer

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

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! :-)

Boris Berenberg · Answer

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.