Link to filenames with spaces in Bitbucket Markdown

Question

Let's say I have a README.md and I'd like to create a link to a file that contains spaces in its name, file with spaces.md. I'd like to be able to jump to the file's source code.

/
 -- README.md
 -- File with spaces.md

After inspecting the element in the browser, I figured out what the href should be (changed it manually, then clicking on it brought me to the page I want to reach):

<a href="username/repository/src/c0mm1th4sH/File%20with%20%spaces.md">

Unfortunately I couldn't accomplish that. Some of the things I have tried so far:

[Link](File with spaces.md)
[Link](File%20with%20spaces.md)
[Link](File\ with\ spaces.md)
[Link]("File with spaces.md")

It results in the following HTML in Bitbucket:

<a href="/username/repository/src/c0mm1th4sH/File%2520with%2520spaces.md">
<a href="/username/repository/src/c0mm1th4sH/File%2520with%2520spaces.md">
<a href="/username/repository/src/c0mm1th4sH/File%5C%2520with%5C%2520spaces.md">
<a href="" title="File with spaces.md">

You can play with the example repository I created.

Update: the bug is gone, so simple spaces or %20 will work now.

Hemminger

Appears to be a tremendous amount of variation in how implementations render those. However, your second example seems to work most consistently. If that doesn't work, then I would report it as a bug. – Epicrisis

Thanks, I reported the bug. I also updated my questions with an example repository. – Hemminger

The bug has been solved (2017-04-06), so %20 effectively works now, including in the example repository. You can update the question accordingly, although I would suggest preserving the original (incorrect) output as well, so readers can understand what you've been through. – Administrator

@Administrator Thank you, I submitted a new answer https://mcmap.net/q/469083/-link-to-filenames-with-spaces-in-bitbucket-markdown I didn't want to edit the question, as it would make things harder to understand. Bugs come and go, workarounds become unnecessary, that is expected, and the question was detailed and correct at the time of asking. Besides that, I don't use Bitbucket anymore (nor will, hopefully) so I don't want to submit edits to a question that might make the quality of the question worse than it originally was. – Hemminger

@Administrator I added a short note to the question with a link to the accepted answer that includes the simple, straightforward solution. I hope that helps – Hemminger

@VinceVarga Yes, good idea, readers won't have to scroll all the way down. – Administrator

Answer 1

There was, in fact, a bug on Bitbucket's side, however, the bug is now fixed.

Assuming your file is called File with spaces.md and the text you want to be displayed is Link, either of these two methods will work:

* [Link](File with spaces.md)
* [Link](File%20with%20spaces.md)

Hemminger

Thanks, I was "tricked" by myself 😂🙈 reading the markdownguide.org/cheat-sheet and by mistake prefixed the expression with '!' (as you do when linking images), (i.e. "" instead of "[Keyboard shortcuts](./keyboard-shortcuts-windows.pdf). Though I had to use '%20' instead of spaces. Using the built in preview and also for the extension 'Markdown Preview Enhanced' – Once

For VS Code that is :) – Once

Answer 2

This seems to work well for me: Replace the space with  .

Source

[Link](File with spaces.md)

Witten

  worked for me, but %20 also worked and I think I prefer the latter. – Schwa

  is better than  , because the &#x version use Unicode numbers, the both versions come from Numeric character reference, for example on github, not all of it's codes is supported . _ _ %20 is an Percent-encoding . – Klara

Thank you for the answer. Right now, both simple spaces or %20 will work so this workaround is not needed anymore. See answer: https://mcmap.net/q/469083/-link-to-filenames-with-spaces-in-bitbucket-markdown – Hemminger

Answer 3

Different Markdown implementations (even versions of these) differ in how they handle these. I found the following very informative (click on "preview" after the page fully loads - it takes a while):

http://johnmacfarlane.net/babelmark2/?text=%5B1%5D(is+not)+OK%2C%0A%5B2%5D(is%2520not)+OK%2C%0A%5B3%5D(%22is+not%22)+OK%2C%0A%5B4%5D(%22is%2520not%22)+OK%2C%0A%5B5%5D(is%5C+not)+OK.%0A

Summary if the link stops working... Five different possibilities are shown against many different implementations:

[1](is not) OK,
[2](is%20not) OK,
[3]("is not") OK,
[4]("is%20not") OK,
[5](is\ not) OK.

It appears that all work somewhere but #2 seems to work everywhere (or almost everywhere) and every other option fails in at least one case.

Output:

marked 0.5.2, MD4C 0.2.7, MD4C (strict) 0.2.7, markdig 0.15.6.0

[1](is not) OK, 2 OK, 3 OK, 4 OK, [5](is\ not) OK.

commonmark.js 0.28.1, markdown-it 8.4.2

[1](is not) OK, 2 OK, 3 OK, 4 OK, 5 OK.

Markdown.pl 1.0.1, Python-Markdown 2.6.5

1 OK, 2 OK, 3 OK, 4 OK, 5 OK.

Markdown.pl 1.0.2b8

[1](is not) OK, 2 OK, 3 OK, 4 OK, [5](is\ not) OK.

pandoc (strict) 2.5

1 OK, 2 OK, 3 OK, 4 OK, 5 OK.

cheapskate 0.1.0.5, Parsedown 1.6.0

[1](is not) OK, 2 OK, 3 OK, 4 OK, [5](is\ not) OK.

pandoc 2.5

1 OK, 2 OK, 3 OK, 4 OK, 5 OK.

lunamark 0.4.0

[1](is not) OK, 2 OK, 3 OK, 4 OK, [5](is\ not) OK.

RedCarpet 3.3.4

1 OK, 2 OK, 3 OK, 4 OK, 5 OK.

RDiscount 2.1.8

1 OK, 2 OK, 3 OK, 4 OK, 5 OK.

PHP Markdown 1.8.0, PHP Markdown Extra 1.8.0

[1](is not) OK, 2 OK, 3 OK, 4 OK, [5](is\ not) OK.

Maruku 0.7.3.beta1, Maruku (Math-Enabled) 0.7.3.beta1

1ot) OK, 2 OK, 3ot“) OK, 4 OK, 5ot) OK.

MultiMarkdown 5.1.0

[1](is not) OK, 2 OK, [3](“is not”) OK, 4 OK, [5](is\ not) OK.

Blackfriday

1 OK, 2 OK, [3](“is not”) OK, 4 OK, 5 OK.

kramdown 1.2.0, mistune 0.8.3

1 OK, 2 OK, 3 OK, 4 OK, 5 OK.

MultiMarkdown 6 6.3.0

1 OK, 2 OK, 3 OK, 4 OK, 5 OK.

s9e\TextFormatter (Fatdown/PHP)

[1](is not) OK, 2 OK, [3](“is not”) OK, 4 OK, [5](is\ not) OK.

cebe/markdown 1.2.0, cebe/markdown GFM 1.2.0, cebe/markdown MarkdownExtra 1.2.0

[1](is not) OK, 2 OK, 3 OK, 4 OK, [5](is\ not) OK.

Gambas 3.8.90

1 OK, 2 OK, OK, OK, 5 OK.

showdown 1.7.4

[1](is not) OK, 2 OK, 3 OK, 4 OK, [5](is\ not) OK.

showdown (flavor: github) 1.7.4

[1](is not) OK, 2 OK, 3 OK, 4 OK, [5](is\ not) OK.

Seymour

Is there any method that works for all of them? I find this quite hard to understand. Maybe a table would be good? – Witten

Answer 4

According to the Markdown specification, a link target is specified by an URL. In a URL, a space is encoded as + or as %20.

See W3Schools - URL Encoding:

URLs cannot contain spaces. URL encoding normally replaces a space with a plus (+) sign, or %20.

But since + is not supported everywhere (GitHub, MDX, etc; see comments below), better use %20.

Xebec

Answer 5

substitute - for spaces

e.g for file name 'Hello World.md' your markdown will be as follows

[link_caption](./Hello-World.md)

Lesialesion

Answer 6

I use

[Title](/username/repo/Name-file-with-)

and works!

Mythicize

I don't think it worked for me (updated repo). – Hemminger

doesn't work for VSCode's default preview either – Klara

Answer 7

Maybe you should try to input "raw html" into the markdown content.

e.g.

# this is title

para...

this is the link: 

<a href=google.com>google</a>

Cinerarium

Answer 8

Use <> around paths or URLs with spaces in them to consistently get better results across markdown viewers

I just want to point out that like this answer says, the bug is now fixed on Bitbucket's end, and Bitbucket now works perfectly fine on URLs with spaces!

This markdown:

Test links:

1. [some file with spaces.md](some file with spaces.md)
1. [some file with spaces.md](<some file with spaces.md>)

Renders like this on Bitbucket. Notice both rendered well:

However, on most markdown viewers, it will render like this (this is rendered by Markdown Viewer, available on both Edge and Chrome). Notice that only the [some file with spaces.md](<some file with spaces.md>) version renders well:

So, for most markdown viewers, and to be more-compatible, whenever you have spaces in paths, just wrap the path in <>, like this:

[some file with spaces.md](<some file with spaces.md>)

...in order to consistently get better output across multiple markdown viewers/renderers.

Dehorn

Answer 9

If your are using VS Code then there is an easy way you can get that link which work s with online github as well as local markdown reviews.

See the link which I received and that a spaced replaced link which is browser compatible.

From this
User-Login: JWT and SQLAlchemy/README.md
to this
./User-Login:%20JWT%20and%20SQLAlchemy/README.md

Esquibel

The question is about Bitbucket, your answer is mentioning GitHub – Hemminger

Is that not addressing the problem in bit bucket have you tried? Though the example is of github but the issue is relate to spaces in link. Any way you can remove the initial github address and then make the link a relative one like I have done ./User .... – Esquibel