wheelercj/stardown

A browser extension that copies a markdown link for the current page.

Stardown

A browser extension that copies a markdown link for the current page.

After installing, there are multiple ways you can copy markdown:

• click the extension's icon to copy a link for the current page, or press Ctrl+Shift+U (Mac: Cmd+Shift+U) or whichever keyboard shortcut you prefer in your browser's settings
• double-click the extension's icon to copy links for all tabs, or press Ctrl+Shift+UU (Mac: Cmd+Shift+UU)
• select tabs before double-clicking the icon to copy links for only those tabs
• right-click the page and choose Stardown's copy option that changes depending on what you right-clicked
• select text before right-clicking to create a link with a text fragment

Stardown's "Copy markdown link to here" right-click option tries to find an id attribute in the HTML elements you right-clicked so you can still link to specific parts of pages even without text fragments. Firefox does not support text fragments yet, but the Firefox version of Stardown allows you to create links with text fragments.

How I use Stardown

Privacy

Stardown will never sell any data to anyone, and does not collect nor send any of your data anywhere besides putting markdown text into your clipboard.

In Chrome and Edge, if you use Stardown's feature that copies links for multiple tabs simultaneously, the first time you do, Stardown will request to "read your browsing history" because that's the only way for Chrome and Edge extensions to see the titles and URLs of all tabs (source). Granting this permission does NOT give access to existing browsing history; the request message only sounds like it does because malicious extensions that can see the titles and URLs of all tabs could start manually gathering your browsing activity. The permission can be revoked at any time. The Firefox version of Stardown requests the exact same permission but has a less misleading request message. Other Chrome and Edge browser extensions that request immediate and complete access to browsing history, unlike Stardown, use the request message "read and change your browsing history on all signed-in devices".

Settings

To open Stardown's options page, right-click the extension's icon and choose:

• Firefox: "Manange extension" and then "Options"
• Chrome: "Options"
• Edge: "Extension options"

How to change the keyboard shortcut

• Firefox
• Chrome: chrome://extensions/shortcuts
• Edge: edge://extensions/shortcuts

Troubleshooting

The right-click option copied a link for the entire page, not a specific part

Stardown looks for an HTML element ID where you right-clicked, but some parts of websites don't have any IDs. If there is no HTML element ID where you right-click and you don't select text before right-clicking, the link Stardown creates will be for the entire page, not for the part of the page where you right-clicked. Most websites assign an ID to each section title.

It's also not possible to link to text within HTML iframes because text fragments don't support iframes.

Lastly, a small number of sites allow creating text fragment links but don't allow using them.

The right-click options disappeared

Due to browser limitations, Stardown's context menu options cannot appear for certain kinds of images and links. Specifically, they cannot appear for canvases, background images, inline SVGs, and for HTML anchors that contain both text and image(s).

Besides those possibilities, browsers have an occasionally reoccuring bug that makes the context menu options disappear. Reinstalling Stardown should fix this.

Stardown displayed a red X and didn't do anything

This may happen if the current website is not focused, such as if you just clicked the address bar. In this case, click the page and try again.

Another possibility is that some websites limit what extensions can do and may prevent Stardown from working. A few examples are the Chrome Web Store and Chrome pages that start with chrome://. Fortunately, very few websites do this and it doesn't prevent Stardown from copying links for multiple tabs simultaneously if the current tab is not one of those limiting websites.

Something else is wrong

If reinstalling Stardown doesn't fix it and the issues page doesn't have an issue for it yet, please make a new issue.

Feature requests

You're welcome to make a feature request, and there may already be another browser extension that meets all your needs. I am not affiliated with any of the below extensions and have not tried all of them. Use them at your own risk.

Copy links in other formats besides markdown

• url2clipboard supports HTML, Markdown, BBCode, Textile, AsciiDoc, MediaWiki, Jira, reStructuredText, LaTeX, Org Mode, and text.
• TabCopy might only be on the Chrome Web Store, but supports many formats including HTML, Markdown, BBCode, CSV, and JSON, and lets you create custom link formats.

Copy just the titles or just the URLs of all tabs

• copy-as-markdown

Copy a website's content as markdown

• MarkDownload was developed by an Obsidian community moderator.
• Obsidian Web Clipper Bookmarklet is a bookmarklet for saving articles and pages from the web to Obsidian.
• copy-selection-as-markdown is only available for Firefox but may work manually installed in Chromium browsers.

Copy just a URL with a text fragment

• link-to-text-fragment was made by Google itself but is cross-browser.

Save a page for research

• Zotero

Why use Stardown?

Unlike the extensions linked above, Stardown:

• can create markdown links for specific parts of pages (using text fragments and/or HTML element IDs)
• requires only one click to create a markdown link for the current page
• is focused on just the most important features so it's more likely to be maintained and bug-free

Development

Contributions are welcome! Let me know (such as in an issue or a discussion) what you have in mind ahead of time if you think there's a chance it won't be approved.

Also, please read docs/develop.md.

stardown's Issues

Block quote output should contain any selected images

Currently, Stardown's "Copy markdown of selection" option cannot copy images with the setting "when creating markdown of a selection, create a block quote and a page title link".

Selecting text and an image, right-clicking the text, and choosing the copy option puts into the clipboard a markdown block quote containing the selected text and the image's alt text, but not the image.

Below is an example showing what was selected and then the markdown it resulted in.

Math Empathy Checklist

I use the ADEPT method to remind me of what helps me learn: an Analogy, Diagram, Example, Plain English, Technical Definition.

adept method

But when sharing a math idea, I have a different mental checklist.

— Empathy-Driven Mathematics – BetterExplained

The image is gone but its alt text remains.

It would be better to have a link to the image rather than just its alt text. The result should be:

Math Empathy Checklist

I use the ADEPT method to remind me of what helps me learn: an Analogy, Diagram, Example, Plain English, Technical Definition.

But when sharing a math idea, I have a different mental checklist.

— Empathy-Driven Mathematics – BetterExplained

Which contains the markdown image ![adept-method.png.webp](https://betterexplained.com/wp-content/webp-express/webp-images/uploads/adept/adept-method.png.webp).

Stardown gets selected content using the window.getSelection function, which returns a selection object. This object can probably also be used to get the URLs and alt texts of images. To implement this feature, Stardown will need to traverse the HTML of the selection, find all images, and get their URLs and alt texts.

Deduplicate code

So far, Stardown's code is organized so that as much as possible is in the background files and the remaining code is in the content files. The exceptions to this are the text fragment generation code and the options page code.

The background and content scripts should be split into multiple files to improve organization and to reuse some duplicate code.

In particular:

• The replaceBrackets function is defined in two places for the Chromium version of Stardown. The function should be defined in one file that is imported/required into other files.
• The getSetting function is defined in 5 places total. It should be defined in one place for each of the Firefox and Chromium versions of Stardown.

The right-click option naively appends HTML element IDs and/or text fragments to the URL

URLs must have, at most, one HTML element ID and/or one text fragment. However, the context menu option in Stardown v1.0.0 appends these without checking if the page's URL already has them. A URL with more than one of either or both of these will ignore all of them, breaking those features.

To Reproduce
Steps to reproduce the behavior:

1. Go to https://chriswheeler.dev/posts/getting-started-with-git-and-github/
2. Click on the hashtag (#) next to the "Git workflows" header so that the page's URL is now ends with /#git-workflows
3. Right-click the header and use Stardown's context menu option
4. Paste the text and see that the URL ends with /#git-workflows#git-workflows.
5. Navigate to the URL and see that the top of the page is loaded instead of the "Git workflows" header.

Essentially the same thing happens with text fragments.

Expected behavior
Stardown should check whether the URL has an HTML element ID and a text fragment before replacing either or both of them.

Environment

• Stardown's version (in the options page): v1.0.0
• OS: Windows
• Browser: Chrome and Firefox
• Device: desktop

Attempt to combine the Firefox and Chromium versions

Although the Firefox and Chromium versions definitely need different manifest files, it may be possible to combine the rest of their code into one folder. This will speed up future development.

The changes required can be made gradually.

In the Firefox version:

1. move code that calls the clipboard API from the background into content script(s)
2. update to manifest v3
3. use this CSS to fix the blue dot bug

Of course, thorough testing will still need to be done on each officially supported browser.

Newline characters in selections can appear in link titles

Describe the bug
With the "When creating markdown of a selection, create a link with the selected text as the title" setting, if multiple unordered list items of text are selected and the "Copy markdown of selection" context menu option is used, the resulting markdown link will have a newline character in it, which breaks the markdown syntax of the link.

To Reproduce
Steps to reproduce the behavior:

1. Go to https://en.wikipedia.org/wiki/Main_Page
2. Select multiple items in an unordered list
3. Right-click the selection and choose "Copy markdown of selection"
4. Paste the markdown
5. See that the pasted markdown spans multiple lines, and so is not a valid markdown link.

Expected behavior
The newline characters should be removed, maybe replaced with spaces.

Environment

• Browser: all

Show a different context menu option depending on the context

Stardown's current context menu option creates a markdown link or a markdown block quote containing a markdown link regardless of what type of website content the user right-clicked on. However, it's possible to have a different context menu option appear depending on what the user right-clicked while still having only one context menu option shown at any time. For example, right-clicking selected text could show an option that creates a markdown block quote (with a markdown link), while right-clicking an unselected image could show an option that creates the markdown equivalent of that image, and right-clicking the "background" of a page could show an option that creates a markdown link.

This is possible with context types. Here are the context type docs:

• Chrome
• Firefox

To the browser.contextMenus.create function, we can pass an object with a contexts property with a value of an array of strings of context types. We can call this create function multiple times.

context types

We should probably not use the all type anymore because we generally want to have only one context menu option visible at a time.

The page type is useful for when the user right-clicks the "background" of the page. This option should create a markdown link that contains any HTML element ID where the user right-clicked. When Firefox adds support for text fragments, the link should also contain a text fragment.

The selection type can be used to make a markdown block quote containing all the selected text, images, etc. as well as a markdown link with any HTML element ID and a text fragment.

The link, image, video, and audio types can be used to create the markdown equivalents of those. However, many images are also links, so the link and image types often overlap.

The frame type doesn't look particularly useful in our case because other context types like selection and page still apply within iframes, and we might not need special behavior just for iframes.

For the editable type, there's probably no use for whatever its markdown equivalent could be, so giving this type the same behavior as the page type would be good.

The browser_action, page_action, and action types do not appear to be relevant.

Firefox's context types are a proper superset of Chrome's context types, but since Stardown should be compatible with both, let's focus on the types both support, at least to begin with.

We can add these options gradually by replacing the all context with the page, editable, selection, video, and audio contexts, and creating a new context menu option with only the image context. As we add more context menu options, we can remove their contexts from the one with multiple contexts.

overlapping contexts

If there are separate context menu options for the selection and image types and the user selects an image and right-clicks it, two context menu options will appear. Although it would be good to generally avoid having more than one context menu option visible at a time, there isn't much reason to select an image before right-clicking it, so maybe we should allow this at least temporarily. (The same applies to the other media types.)

In the future, we may be able to use the update and/or remove functions to choose one of the overlapping contexts so only one option will be visible.

Add a setting for selection copying to result in markdown that tries to keep the same format

The setting "when creating markdown of a selection, ____" should have an option called "try to keep the same format". This will allow us to eventually add support for copying tables as markdown. Markdown renderers typically do not allow tables to be in block quotes.

For context, that setting's current options are "create a block quote and a page title link", "create a link with the selected text as the title", and "create a link with the page title as the link title".

Something to think about: should the copied markdown also have a page title link at the end? Maybe there should be two new settings so the user can choose.

Create markdown when hovering over image

Currently, there is not solution that converts an image in the page and turns it into markdown syntax for images. It would be a nice feature to have a simple "copy & paste" solution in markdown format when using Stardown.

Add support for Safari

Stardown is available for Firefox, Chrome, and Edge. It can also be installed on all other Chromium browsers that use Chrome's web store such as Brave, Vivaldi, and Opera.

However, Stardown is currently not available for Safari. I would like to create and release a version of Stardown for Safari, but there are some roadblocks:

1. I don't have a Mac. As far as I can tell, creating Safari extensions requires using a Mac.
2. I'm not in the Apple Developer Program which also appears to be required for publishing Safari extensions. The Apple Developer Program normally costs $99 USD per year in the United States. According to this Stack Overflow discussion, when one's program membership expires, everything they published is removed from the app store.

Since Stardown is free and doesn't display ads nor harvest data, it doesn't make much sense for me to pay to support one browser that is not the most widely used.

I'm not sure what to do yet because there might be legal issues with allowing someone else to release Stardown in Apple's app store. When I have time, I'll look into this more and think about it. There's a chance I could borrow a relative's Mac and, if there is enough interest in Stardown, maybe I could get some donations to cover the fee. I'm quite confident that I would not be able to get the Apple Developer Program fee waived in the foreseeable future.

Add a copy option to site context menus

It would be great if Stardown could help with copying not just links to entire pages, but also links to specific parts of pages.

With the context menus API, it's probably possible to get the HTML of the right-clicked element. From that, a link could be created in either of two ways:

If the right-clicked element or a nearby one has . . .

• an id attribute, it can be linked to with [${title}](${url}#${id})
• selected text, it can be linked to in some browsers (currently not yet including Firefox) with Text Fragments

pseudocode

get the page's title
get the page's URL

if the right-clicked element is selected text:
    get the selected text
    create a Text Fragment
    create markdown link: `[${title}](${url}${textFragment})`
else if the right-clicked element has an ID attribute:
    get the right-clicked element's ID
    create markdown link: `[${title}](${url}#${id})`
else:
    create markdown link: `[${title}](${url})`

I discovered after writing the pseudocode above that text fragments and element IDs can be used together. Browsers that support text fragments will try to use them first, and only use the ID as a fallback if the text fragment doesn't match the page anywhere. When I tried using a link with both a text fragment and an ID in Firefox (which currently does not support text fragments), not only did the text fragment not work, but it also prevented the ID from working.

further reading

• Boldly link where no one has linked before: Text Fragments | Articles | web.dev
• URL Fragment Text Directives
• Scroll to text fragments | Simon Willison’s TILs
• Bugzilla 1753933 - Implement Text Fragments (formerly Scroll to Text Fragment)
• text-fragments-polyfill - npm
• createTextFragment and doGenerateFragment in github.com/GoogleChromeLabs/link-to-text-fragment

Settings that require permissions have a delay

Describe the bug
When a setting is changed to any state and at least one of the setting's states requires an optional permission, the setting's change does not change Stardown's behavior the first time it should (but does from then on).

To Reproduce
Steps to reproduce the behavior:

1. Toggle the "Show a notification when a context menu option succeeds" setting.
2. Save the settings.
3. Use a context menu option.
4. See that the setting you chose was not applied.
5. Use a context menu option again.
6. See that the setting you chose is now applied.

Expected behavior
All settings should apply immediately on their save.

Additional context
This bug is present for the notify and the doubleClickInterval settings.

The bug is caused by what is described in this comment from the code:

// The permissions request must be the first async function call in the
// event handler or it will throw an error. That's why the value for the
// notify setting is retrieved later.
havePerm = await browser.permissions.request({ permissions: ['notifications'] });

...

notify = await getSetting('notify', false);

I'm not sure how to fix this right now. Maybe by sending a message from options.js to background.js, if possible?

Copy tables as markdown

Depends on #19.

With the setting "when creating markdown of a selection, try to keep the same format", copying a table should result in a markdown table.

For example, copying the selection in this image:

should give this markdown:

| Syntax | Description |
| --- | --- |
| Header | Title |
| Paragraph | Text |

which renders as:

Syntax	Description
Header	Title
Paragraph	Text

It's fine if the resulting markdown has consistent cell widths like this:

| Syntax      | Description |
| ----------- | ----------- |
| Header      | Title       |
| Paragraph   | Text        |

Generalize messaging from background scripts to content scripts

Currently, Stardown has only one message it can easily send from background.js to content.js to initiate copying markdown. Making the relevant code more general will enable future development towards different copying behavior depending on what the user is interacting with.

Specifically, the sendCopyMessage function in background.js (in both the Firefox and Chromium folders) should accept a string input that replaces the string literal "getClickedElementId" so that the browser.runtime.onMessage.addListener calls in the content.js files can receive different messages.

Later, we will be able to more easily get info about what the user is interacting with (which could be selected content, an image, a video, etc.) by changing contexts: ['all'], in browser.contextMenus.create in background.js to a more specific context type. This way, Stardown will be able to copy the markdown equivalent of a wide variety of website contents while having only one context menu option that automatically changes depending on what the user is interacting with.

Context type docs:

• Chrome
• Firefox

Show a notification when copying fails

For various reasons, Stardown is sometimes unable to read site data or write to the clipboard. A red X appears on Stardown's icon when this happens, but users may not notice this tiny error indicator. Even if they do, it's better to show a description of what went wrong. Displaying a notification solves these problems.

With this change, the readme section titled "Stardown displayed a red X and didn't do anything" can be deleted. Before deleting it, refer to it when writing the new error messages.

In the options page, next to the setting "Show a notification when a context menu option succeeds", there should be a new setting titled "Show a notification when copying fails" which should be on by default, unlike the former. They are not exact opposites as the former is for context menu options only, whereas the latter is for any copying method.

Stardown cannot create links for text within iframes

Describe the bug
Stardown can create text fragment links to almost any text anywhere but not text within iframes for some reason. Maybe Stardown's content scripts only go into the root web page.

To Reproduce
Steps to reproduce the behavior:

1. Go to HTML Iframes
2. Select text within the sample iframe
3. Right-click the selected text and choose Stardown's copy option
4. Paste into a text editor
5. See that the link is the same as the one above; it's for the entire page instead of the selected text.

Expected behavior
If it's possible to create a text fragment for text within an iframe (it might not be possible), then with Stardown's default settings, the result should be a markdown blockquote similar to this if "HTML Tutorial" was selected:

HTML Tutorial

— HTML Iframes

Environment

• Stardown's version (in the options page): v1.0.0
• OS: Windows
• Browser: Firefox
• Device: desktop