How to reference other .md files in README.md

[sboss]

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

[Boris Berenberg]

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]

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]

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_]

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]

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