Deep Linking Guide

What is Deep Linking?

Deep linking allows you to share a link that points to a specific passage within a note, not just the note itself. When someone opens your link, their browser automatically:

Scrolls to the exact text you selected
Highlights that text with a colored background
Provides visual context for what you wanted to share

How to Create a Deep Link

Method 1: Keyboard Shortcut (Fastest)

Select the text you want to link to
Press Cmd + Shift + L (Mac) or Ctrl + Shift + L (Windows/Linux)
The link is automatically copied to your clipboard
Paste and share!

Method 2: Command Palette

Select the text you want to link to
Open the Gate (press :: or Cmd/Ctrl + K)
Type ::highlight
Press Enter
The link is copied to your clipboard

Method 3: Share Button

If your note has a share button with text selection support:

Select the text
Click “Copy Link to Highlight”
Done!

Example Usage

Before

“Check out my note about typography:”
https://standard.garden/@alice/typography-basics

→ Reader has to find the relevant section

After

“Check out this key insight about kerning:”
https://standard.garden/@alice/typography-basics#:~:text=Kerning%20is%20the%20space

→ Browser scrolls directly to the sentence and highlights it

What URLs Look Like

Regular Link

https://standard.garden/@username/note-slug

Deep Link (Short Selection)

https://standard.garden/@username/note-slug#:~:text=selected%20text

Deep Link (Long Selection)

https://standard.garden/@username/note-slug#:~:text=beginning%20text,ending%20text

When to Use Deep Links

✅ Great for:

Academic citations
Referencing specific arguments
Sharing key insights
Directing readers to important passages
Code snippets or examples
Definitions or explanations

❌ Not ideal for:

Very long selections (use a summary instead)
Text that might change frequently
When you want readers to see full context first

Browser Support

Browser	Support	Notes
Chrome	✅ Full	Version 89+
Edge	✅ Full	Version 89+
Safari	✅ Full	Version 16.1+
Firefox	⚠️ Limited	Requires flag in about:config
Mobile Safari	✅ Full	iOS 16.1+
Mobile Chrome	✅ Full	Android Chrome 89+

Note: On unsupported browsers, the link still works—it just won’t highlight the text.

Tips & Tricks

1. Keep Selections Moderate

Select complete sentences or short paragraphs for best results. Very short selections (1-2 words) might match multiple places in the document.

2. Include Context

If your selection is part of a larger argument, consider selecting a slightly longer passage that provides context.

3. Test Your Links

Before sharing important deep links, test them in a different browser or incognito window to ensure they work as expected.

4. Use Descriptive Text

When sharing, provide context about what the link points to:

Good: “Here’s the section on color theory: [link]”
Better: “Check out the explanation of OKLCH color space: [link]”

Privacy & Security

✅ Safe to use:

Text fragments are read-only
They cannot modify page content
They cannot execute code
URLs are properly encoded

✅ Privacy-friendly:

The fragment is removed from the URL bar after highlighting
No tracking or analytics on fragment usage
Works without server-side processing

Technical Details

How It Works

Client-side only: Your browser handles everything
Native API: Uses the Text Fragments API
No overhead: Zero impact on page load performance
Future-proof: W3C standard, supported by major browsers

URL Structure

https://example.com/page#:~:text=[prefix-,]start[,end][,-suffix]

#:~:text= – Fragment directive (signals this is a text fragment)
start – Required: beginning of text to find
end – Optional: ending of text (for longer selections)
prefix – Optional: text before the selection (for disambiguation)
suffix – Optional: text after the selection (for disambiguation)

Accessibility

✅ Keyboard accessible: Full keyboard support via shortcuts
✅ Screen reader friendly: Toast notifications are announced
✅ High contrast: Highlights adapt to theme colors
✅ Reduced motion: Respects user preferences for animations

Troubleshooting

“Link doesn’t highlight anything”

Browser might not support Text Fragments (check browser version)
Text might have changed since the link was created
Try selecting more specific text

“Can’t copy link”

Browser might not support Clipboard API
Check browser permissions for clipboard access
Try using the Gate command instead of keyboard shortcut

“Selection is gone after pressing shortcut”

This is normal—the link is still copied correctly
The selection is cleared as part of the copy process