Make your references useful.
Connect an idea to its source with a link that tells the reader what to expect.
Read the descriptive transcript
Follow the complete narration and the changes shown in the video. Each example can be copied.
1. A label and a destination
A useful link tells the reader where it goes. Let's turn Syntax into a link to the CommonMark reference.
Source shown
Useful reference:
SyntaxOn screen
The document stays visible while the narration explains the idea.
2. 01 / Put the label in square brackets
Click before Syntax and type an opening square bracket. Then put a closing square bracket after the word.
Source shown
Useful reference:
[Syntax]On screen
The cursor moves to the edit point. Each character is inserted or removed in the source, and the preview updates from that text.
3. The label is what the reader sees
The words inside the brackets are the visible label. Choose a description of the destination, rather than a vague instruction such as click here.
Source shown
Useful reference:
[Syntax]On screen
The document stays visible while the narration explains the idea.
4. 02 / Add parentheses immediately after it
After the closing bracket, type an opening parenthesis, the destination address, and a closing parenthesis. Keep the address attached to the label.
Source shown
Useful reference:
[Syntax](https://commonmark.org/help/)On screen
The cursor moves to the edit point. Each character is inserted or removed in the source, and the preview updates from that text.
5. One rendered link
The preview now shows the label as a link. The source keeps both the label and the address together.
Source shown
Useful reference:
[Syntax](https://commonmark.org/help/)On screen
The document stays visible while the narration explains the idea.
6. 03 / Spot the broken syntax
Watch what happens if we remove the final parenthesis. The renderer no longer recognizes the complete link. What would repair it?
Source shown
Useful reference:
[Syntax](https://commonmark.org/help/On screen
The cursor moves to the edit point. Each character is inserted or removed in the source, and the preview updates from that text.
7. Restore the closing parenthesis
Put the closing parenthesis back. The link returns. Paired brackets and parentheses make the two parts unambiguous.
Source shown
Useful reference:
[Syntax](https://commonmark.org/help/)On screen
The cursor moves to the edit point. Each character is inserted or removed in the source, and the preview updates from that text.
8. Check the destination and the claim
In a finished document, open the link and check the page. A plausible label does not prove that the page supports what you wrote.
Source shown
Useful reference:
[Syntax](https://commonmark.org/help/)On screen
The document stays visible while the narration explains the idea.
9. Relative links follow your file structure
A link can also point to a file in your project. Moving that file can break the relationship, so check relative links after reorganizing folders.
Source shown
Useful reference:
[Syntax](https://commonmark.org/help/)On screen
The document stays visible while the narration explains the idea.
10. Your turn / Write a descriptive reference
Pause and build your own reference below the video. Give it a descriptive label and the supplied address. The practice preview keeps links inactive while you learn.
Source shown
Useful reference:
[Syntax](https://commonmark.org/help/)On screen
The document stays visible while the narration explains the idea.
A label and a destination
A Markdown link has two parts: the text the reader sees in square brackets and the destination in parentheses. Keep them together. CommonMark links.
[CommonMark syntax reference](https://commonmark.org/help/)“CommonMark syntax reference” tells the reader more than “click here”. Pick a label that makes sense in the surrounding sentence and when scanned on its own.
Put the reference beside the claim
A research note should make it easy to tell which source supports which statement. Place a reference next to the relevant passage. Keep your observations, quotations and interpretation distinguishable. Open the source and check it; plausible link text is not evidence that a source exists or supports the claim.
Links inside a project
A relative link points from the current document to another file. Moving files can break that relationship. Keep your project structure consistent and check links where the document will be used.
[Planting notes](notes/planting.md)An image uses a related syntax with an exclamation mark. Its text should describe the image meaningfully. Unlike a link, a renderer may load an image automatically, so understand the application’s image settings. CommonMark images.
Practise without leaving your draft
The lesson preview displays link labels without making them navigable, and displays image descriptions without fetching images. This keeps experimentation on the page. Copy your source into your document when you want to check the real destination.
YOUR TURN
Make the idea your own.
Add a descriptive Markdown link to an HTTPS page. For this exercise, use https://commonmark.org/help/ and choose a useful label.
Readable result
Useful reference: CommonMark
Compare with one possible answer
Useful reference: [CommonMark syntax reference](https://commonmark.org/help/)This is one approach. Your writing can differ while meeting the same structural goal.
TAKE IT WITH YOU
A useful label explains the destination; a link alone does not prove a claim.
Read the editor guide →Progress is stored in this browser. Your practice text is not saved.