The basic link
Square brackets for the text, parentheses for the URL. No space between the closing bracket and the opening paren. That is the whole format. For the full reference, see the syntax reference.
Read [Warren Buffett's annual letters](https://berkshirehathaway.com/letters/) to understand compounding.
Read Warren Buffett's annual letters to understand compounding.
The text in the brackets is what readers see. The URL in the parens is where they go. Keep the link text descriptive — "click here" and "this article" are useless to anyone skimming or to a screen reader reading the page aloud. Write link text that makes sense out of context.
Optional title (tooltip)
Add a title in quotes after the URL and most renderers will show it as a tooltip on hover. Rarely useful — hover does not exist on mobile — but good to know it exists.
[SEC EDGAR](https://sec.gov/edgar/search "Public company filings database")
Auto-links
Wrap a URL in angle brackets and it becomes clickable with the URL itself as the link text. Useful when you want the URL visible — in documentation, references, or a list of sources.
Documentation: <https://docs.example.com> Email: <support@example.com>
Documentation: https://docs.example.com
Email: support@example.com
Many renderers (GitHub, Slack, Discord, most AI chat interfaces) will auto-link a bare URL without any angle brackets — type https://example.com and it becomes clickable. But relying on that behavior is risky; the angle brackets guarantee it.
Reference-style links
For long documents with many links, inline URLs get cluttered. Reference style keeps the prose clean — you write a short label in the text, and put the actual URLs in a block at the end of the document (or section).
Our research draws on [Apple's 10-K filings][aapl-10k], [the Bureau of Labor Statistics][bls], and [peer-reviewed energy research][nature-energy]. [aapl-10k]: https://investor.apple.com/sec-filings [bls]: https://bls.gov [nature-energy]: https://nature.com/nenergy/
Our research draws on Apple's 10-K filings, the Bureau of Labor Statistics, and peer-reviewed energy research.
The definition block at the bottom — lines starting with a label in brackets followed by a colon — does not render. It is invisible plumbing. The advantages are real: if a URL changes, you update one place. The body text stays readable at the source level. And you can reuse the same label multiple times in the document.
Shorthand reference links
If your label and your visible text would be the same, you can drop the label:
The [GitHub] docs explain it well. [GitHub]: https://docs.github.com
The GitHub docs explain it well.
Anchor links (jump within the same page)
Point at a heading elsewhere in the document by using a hash followed by the lowercase, dash-joined version of the heading text.
See [the methodology](#methodology) for how we gathered the data. Later in the same file... ## Methodology The data came from...
See the methodology for how we gathered the data.
Later in the same file:
Methodology
The data came from...
Most renderers (GitHub, GitBook, Docusaurus, Obsidian) auto-generate these IDs. The rule they use: lowercase, replace spaces with dashes, strip punctuation. # What We Found becomes #what-we-found. If the link is not working, view the rendered HTML to see what the renderer actually assigned.
Images
The syntax for an image is identical to a link, with a bang (!) in front. The bracketed text is alt text. The parens hold the path or URL to the image.
Alt text — why it matters
Alt text is three things at once: accessibility for blind readers, a fallback when the image fails to load, and — newly critical in 2026 — the only thing a text-only AI model has to work with. If you upload a Markdown document with an image to ChatGPT in a text-only context, or to an older LLM that cannot see images, the alt text is all the model sees. A blank alt tag means the model has no idea what was there.
Write alt text that describes the content and purpose of the image, not the filename. "chart.png" tells you nothing. "Revenue grew 38% year over year in Q3 2025, driven by enterprise customers" tells you what matters.
Bad:  Good: 
Bad alt text — describes the file, not the content.
Good alt text — tells you what the image shows, even if you cannot see it.
Optional title on images
Same rules as link titles: renders as a tooltip, rarely visible on mobile, mostly useful for source attribution.
Relative vs absolute paths
A path that starts with http:// or https:// is absolute — it works from anywhere. A path that starts with a slash (/images/logo.png) is absolute relative to the site root. A path with no leading slash (images/logo.png or ../assets/photo.jpg) is relative to the current file's location.
Absolute URL:  Site-relative:  Relative to this file: 
Absolute — works from any renderer that can reach the internet.
Site-relative — works on the site the file is deployed to.
File-relative — works when the images folder sits next to the .md file.
The practical rule: if the file will ever move around — get emailed, uploaded to Notion, pasted into ChatGPT — use absolute URLs. Relative paths break the moment the file changes context. The only place relative paths reliably win is inside a Git repository where the images live alongside the code, so the paths move together.
Where to host images
If you are writing a document that needs to travel — sharing notes with a team, uploading to an AI tool, publishing to a blog — the images need a public home. The options, in order of cost and effort:
- Your own website. Free if you already have hosting. Best for long-term reliability — you control the URLs.
- Cloud storage with public links. Dropbox, Google Drive, OneDrive all let you generate shareable URLs. Works, but link rot is real if you move or rename files.
- GitHub. If the file lives in a public GitHub repo, images in the repo have clean raw URLs (
raw.githubusercontent.com/...). Free and reliable. - Image hosts. Imgur, Cloudinary, and similar services give you persistent URLs without setup. Good for one-off documents.
- Base64 embedding. You can inline the entire image as base64 data inside the Markdown. The file gets huge, but nothing breaks.
Real example: a short section with links and an image
Here is how a paragraph from an earnings summary might look in Markdown, with inline links and a chart reference.
## Q3 2025 highlights Revenue reached $96.1B, up **6% YoY**, driven by services growth and stronger-than-expected demand for [the new iPhone lineup][iphone-launch]. Services hit an all-time high of $24.2B, continuing the trend outlined in [last year's 10-K](https://investor.apple.com/sec-filings).  Gross margin expanded to 46.2%, [see full table](#margin-breakdown) below. [iphone-launch]: https://apple.com/newsroom/2025/09/
Q3 2025 highlights
Revenue reached $96.1B, up 6% YoY, driven by services growth and stronger-than-expected demand for the new iPhone lineup. Services hit an all-time high of $24.2B, continuing the trend outlined in last year's 10-K.
Gross margin expanded to 46.2%, see full table below.
That's four different link techniques in a single paragraph — inline link, reference link, auto-link for the image path, and an anchor link. All of them are two-character patterns you will remember after using them once.
Going further
Open the free Markdown editor and try pasting a link from your browser with the syntax above — the live preview makes it obvious when something is off. To convert an existing document with images to Markdown, see the Word to Markdown or HTML to Markdown converters (both preserve image references). For the specific case of turning image-heavy content into AI-friendly Markdown, the guide on image to Markdown for ChatGPT walks through the full workflow.