Inline Links
Links are the blood vessels of a document. Without them, a page is a stack of parallel statements; with them, a reader can jump from how to why, from a conclusion to its source, from one chapter to the next. Markdown offers three ways to write a link, and the inline form is the most direct of them: the visible text and the address sit side by side in the source, so both you and the reader can tell what is about to be opened without following it.
This page works through the exact syntax of that form and spends most of its time on the case behind the majority of dead links in the wild: an address that contains a space or a stray parenthesis. Along the way you will pick up the title attribute, the relative path that keeps working after a domain change, the rules for leaving out a URL scheme, and the criteria for deciding when an inline link should become a reference link instead.
The visible text goes in square brackets, the address goes in round parentheses, and the two are written next to each other with nothing in between:
[Coffic Official Site](https://coffic.cn)<p><a href="https://coffic.cn">Coffic Official Site</a></p>What comes out is an ordinary anchor element. The text between the brackets becomes the label the reader sees; the address between the parentheses becomes the href attribute. Nothing else about the paragraph changes — an inline link stays inside the flow of the sentence and never introduces a block of its own.
Adding a Title
The address may be followed by a title wrapped in quotation marks:
[Coffic Official Site](https://coffic.cn "The project home page")<p><a href="https://coffic.cn" title="The project home page">Coffic Official Site</a></p>The title never appears in the rendered text. It shows up as a tooltip when the reader hovers over the link, and screen readers announce it as supplementary information about the destination. The title is optional: closing the parenthesis straight after the address is equally valid.
The Link Text Is Parsed Content
The text between the brackets is ordinary inline content, so it may carry emphasis or code spans:
See the [**API reference**](https://example.com/api) for the `getUser()` function.<p>See the <a href="https://example.com/api"><strong>API reference</strong></a> for the <code>getUser()</code> function.</p>That is convenient, and it is also the sharpest edge of the syntax: the brackets in the link text have to be balanced. Written as [See [Note 1]](https://example.com), the parser matches the outer pair and keeps the inner brackets as visible text. Written as [See [Note 1](https://example.com), the first closing bracket is consumed by the inner pair, so the link swallows only Note 1 and the rest of the sentence is stranded outside it.
Two characters cause most of the trouble in an address: spaces and parentheses.
Spaces
A space inside the destination ends the link. Write it as %20, or wrap the whole destination in angle brackets and let the parser do the encoding:
[Download the sample](<./my file.zip>)<p><a href="./my%20file.zip">Download the sample</a></p>The angle-bracket form is the better habit. It separates the address as you typed it from the address the parser sees: everything up to the closing bracket is taken verbatim, and the space becomes %20 on its own. Writing %20 by hand works too, but it makes the source harder to read and easy to break with a copy-paste that turns the escape back into a space.
Parentheses
Parentheses are legal inside an address, and the parser pairs them for you:
[Wikipedia entry](https://en.wikipedia.org/wiki/Parenthesis_(disambiguation))<p><a href="https://en.wikipedia.org/wiki/Parenthesis_(disambiguation)">Wikipedia entry</a></p>So a(b)c survives as written. What does not survive is an unbalanced parenthesis: a(b leaves the link unterminated, and the parser falls back to treating the whole thing as plain text.
Angle Brackets as a General Escape
The angle-bracket form is not limited to spaces. It is the general escape hatch for any destination you do not want the parser to interpret, and it is the safest way to write an address whose query string contains an ampersand. The rule of thumb for writing about this syntax: outside a code block, always show the angle-bracket form inside backticks, because a bare < in the body of an MDX page is read as the start of a JSX tag and breaks the build.
An inline link may point at a document in the same repository, and such a link should use a relative path so that it keeps working when the domain changes:
[The previous chapter](./syntax-highlighting.mdx) and [a fragment](https://example.com#syntax)<p><a href="./syntax-highlighting.mdx">The previous chapter</a> and <a href="https://example.com#syntax">a fragment</a></p>A relative path is resolved against the directory of the file that contains it, not against the root of the site. Move the file and the link breaks; split one long document into several and the links have to be maintained alongside the directory structure. That cost is worth paying for documents that live in the same repository. It is not worth paying for a link to a third-party site, where a full address is clearer and survives being copied out of the page.
When You May Leave the Scheme Out
Writing https:// on every address is repetitive, and in three situations it can safely be left off. The first is a root-relative path, which stays on the current host: [the guide](/docs/guide) resolves to /docs/guide on whatever site you are reading. The second is a protocol-relative address, [the guide](//example.com/guide) inherits the scheme of the page, so it works over both HTTP and HTTPS. The third is a plain relative path such as [the guide](./guide).
What you must not assume is that a scheme is added for you. Write [the guide](example.com/guide) and the destination is the relative path example.com/guide, which the browser resolves against the current directory — it does not reach the site example.com at all. The one case where a scheme really is filled in for you is the GFM automatic link form, where a www. prefixed host gains an http:// prefix; the last page of this chapter covers it.
When the Link Text Is the Address
Sometimes the visible text is exactly the address — a download URL that readers are expected to copy, an API endpoint, an email address. Writing it twice is noise:
[https://example.com/docs](https://example.com/docs)<p><a href="https://example.com/docs">https://example.com/docs</a></p>When the text and the address are the same, do not reach for the inline form at all. An automatic link does the job with a single copy of the address, and the result is exactly what you typed. That is the subject of the last page of this chapter.
The inline form keeps the text and the address in one place, which is what you want when the address is itself important information: a download link, an API endpoint, an email address. The reader can read the destination straight out of the sentence and copy it without following the link.
The reference form separates them, which is what you want when the same destination appears again and again. Ten links to the same site become ten short markers and one definition at the bottom of the file, and changing the address is a one-line edit. The price is that the reader can no longer see where a link points without scrolling to the end of the document. The next page works through that form in full; the rule of thumb is that the address should be background information for a reference link and foreground information for an inline link.
| Written as | What actually happens | Why |
|---|---|---|
[text](https://x.com/a b) | Not a link | A space ends the destination; the rest is left as plain text |
[text](<https://x.com/a b>) | A link | The angle-bracket form keeps the space and encodes it |
[text](https://x.com/a(b) | Not a link | The parenthesis is never closed |
[text](https://x.com/a(b)c) | A link | Parentheses inside an address are paired automatically |
[text](url "Title" "Another") | Not a link | Only one quoted title is allowed |
[text](example.com) | A link to a relative path | No scheme means the browser resolves it against the current page |
[See [Note]](https://x.com) | Text reads See [Note] | Balanced brackets in the link text are allowed |
A space inside an address breaks the link, and it breaks it quietly. The parser does not raise an error; it ends the destination at the space, so the bracket pair is not a link at all and the leftover characters trail along the page as ordinary text. It reads like the link was only half written. Encode the space as %20, or wrap the destination in angle brackets and let the parser handle it.
Rewrite the following sentence as Markdown. Requirements: the “Download the sample” link must point at my file.zip, and because that address contains a space the destination has to be wrapped in angle brackets; the text “[full documentation]” must appear on the page with its brackets intact and point at https://coffic.cn/docs; and the home page address must stay clickable as plain text.
Click "Download the sample" to get my file.zip, read [full documentation] for the details, and the home page is https://coffic.cn.Approach:
An inline link is square brackets for the visible text plus round parentheses for the destination. This exercise has two traps. The destination contains a space, which ends the link unless the destination is wrapped in angle brackets. And the visible text contains brackets of its own, which the parser can only treat as literal text if they are balanced — one left bracket and one right bracket inside the outer pair.
Steps:
- Put “Download the sample” in square brackets and write the destination in round parentheses. Because the destination contains a space, write it as
<my file.zip>, so that the angle brackets carry the address past the space and the parser encodes it. - For the text “[full documentation]”, give the outer square brackets a second, inner pair: an outer bracket, then
[full documentation], then the closing outer bracket, immediately followed by the destination. The parser then sees balanced brackets inside the link text and keeps them as visible characters. - The home page address has no space and no special characters, so it goes straight into round parentheses.
- Check the result: the download link resolves to
my%20file.zip, the text “[full documentation]” appears with its brackets intact, and the home page address is clickable.
Answer:
Click [Download the sample](<my file.zip>), read [[full documentation]](https://coffic.cn/docs) for the details, and the home page is [https://coffic.cn](https://coffic.cn).You should now be able to write an inline link with a title, embed emphasis or code in its text, keep the brackets in that text balanced, encode or wrap an address that contains spaces, rely on automatic pairing for parentheses, point at a sibling document with a relative path, and explain why a destination without a scheme is a relative URL rather than an absolute one. You should also be able to say when an inline link is the right tool and when the reference form on the next page is better. The next page takes that second form apart: the definition, the reference, and the two shorthands that keep a long document readable.