wheelercj / stardown

Copy the web as markdown

Stardown

Copy the web as markdown

You can also install from the source code to get updates early.

• Click the extension's icon to copy a link for the current page.
• Press Alt+C to copy a selection or a page's link.
• Right-click part of a page to copy it as markdown. Select before right-clicking to copy multiple parts.
• Double-click the extension's icon or press Alt+CC to copy links for all tabs.
• Select tabs before double-clicking the icon to copy links for only those tabs.
• Use the options page to customize these features.

By default, the markdown created from a selection includes a link that navigates to the part of the page you selected, when possible. This is accomplished with text fragments and/or HTML element IDs. Firefox does not support text fragments yet, but the Firefox version of Stardown allows you to create links with text fragments.

Want to just copy markdown links for pages without installing an extension? You can use this bookmarklet instead: javascript: navigator.clipboard.writeText('[' + document.title + '](' + location.href + ')');

Privacy

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

Permissions

For why Stardown requests the permissions that it does, see ./docs/permissions.md.

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

See ./docs/troubleshooting.md

Feature requests

See ./docs/feature-requests.md

Install from source

See ./docs/install-from-source.md

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.

Text fragment generation timeout prevents write to clipboard, and the success indicator is still shown

Describe the bug
When using any of Stardown's options that creates a text fragment, if the text that a text fragment is being created for is repeated enough times in the page that the text fragment generator will time out, the green checkmark success indicator is shown before the text fragment generator times out, and when it does, nothing is written to the clipboard instead of all the other markdown without the text fragment.

To Reproduce
Steps to reproduce the behavior:

1. Open the extension's inspector console
2. Go to https://markdownguide.offshoot.io/basic-syntax/#blockquotes-1
3. Select the text "rendered output" (this phrase appears 32 times on this somewhat long page)
4. Right-click the selection and choose "Copy markdown of selection"
5. See the green checkmark on Stardown's icon
6. After many seconds, see the error message in the extension console: (Creating text fragment) Error: Fragment generation timed out after 16175 ms.
7. Paste and see that the clipboard was not written to

Expected behavior
The green checkmark should appear when the clipboard is written to or not at all. The clipboard should still be written to with all the other markdown besides a text fragment.

Options page modernization

Currently, Stardown's options page is very simple. I would like to keep it easy to use and lightweight, but there are many ways it could be improved.

For example, the options page could let users directly:

• report bugs
• request a feature
• donate

All without navigating to GitHub or another website.

Keep bold style when creating block quotes

Stardown's "Copy markdown of selection" option doesn't keep bold text bold with the setting "when creating markdown of a selection, create a block quote and a page title link".

For example, the selection shown in this photo:

results in this markdown:

I just love bold text.

— Basic Syntax | Markdown Guide

but should have this result:

I just love bold text.

— Basic Syntax | Markdown Guide

Firefox context menu item creation should only happen on installation

The Mozilla docs say browser.contextMenus.create should only be called when the extension is installed, such as:

browser.runtime.onInstalled.addListener(() => {
  browser.contextMenus.create({
    id: "sampleContextMenu",
    title: "Sample Context Menu",
    contexts: ["selection"],
  });
});

Currently, Stardown uses this code:

if (browserName === 'firefox') {
    browser.contextMenus.create(pageMenuItem);
    browser.contextMenus.create(selectionMenuItem);
    browser.contextMenus.create(linkMenuItem);
    browser.contextMenus.create(imageMenuItem);
    browser.contextMenus.create(videoMenuItem);
    browser.contextMenus.create(audioMenuItem);
}

Remove dependency on Turndown

Turndown is perfect for converting HTML to markdown when only relatively simple customization is needed, but Stardown has outgrown it. How Stardown converts HTML tables to other formats now almost completely bypasses Turndown, many of the default Turndown rules have been overridden, and #96 would require every Turndown rule to become complicated or duplicated.

Stardown should turn HTML into a syntax tree and work with the syntax tree directly instead of using a framework.

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 more markdown flavors and markup languages

Currently, Stardown focuses mostly on GitHub Flavored Markdown (GFM), but there are many flavors of markdown and many other markup languages.

Examples of markup languages:

• Comparison of features in various Markdown flavors
• Lightweight markup language - Wikipedia
• List of document markup languages - Wikipedia
• Markup lowdown: 4 markup languages every team should know | Opensource.com
• 18 Best markup languages as of 2024 - Slant

A setting could be added to let the user choose the markup language of Stardown's output.

This feature requires many changes to how Stardown converts HTML to other formats, so #105 should be completed first.

Table cells are duplicated sometimes

For most tables Stardown works as expected, but some tables end up with a duplicated cell when using Stardown to copy source-formatted markdown. For example, the table on this site selected as shown in this photo:

gives a result that includes what is shown in this photo:

Notice that besides the word "hide", the first table and the second table's first cell are the same.

That first table should not be there.

Something about the "hide" button's HTML button element is causing the problem. When I remove that node and try again, the problem is fixed.

Chromium duplicates messages sent from background.js to content.js

Using identical relevant code in Chromium and Firefox, and log statements where messages are sent and received, I have discovered that Chromium (and not Firefox) appears to be duplicating messages sent from background.js to content.js. Two messages are received for every one message sent. The second message is received immediately after the first.

Stardown has good enough performance that the computational cost of doing everything twice is not noticeable. However, some new changes that I will soon push and merge have been complicated slightly by the duplicate messages. Sometimes, the messages that are duplicates must be detected and ignored. Stardown does this by pseudorandomly generating a message ID for each message in the relevant categories of messages and ignoring any message with the same ID as the previous message.

To Reproduce

Steps to reproduce the behavior:

1. In Chrome, open the developer tools console and the website's console
2. Open a website with a table, such as one of these:
   • https://developer.mozilla.org/en-US/docs/Learn/HTML/Tables/Advanced#tables_for_visually_impaired_users
   • https://www.markdownguide.org/extended-syntax/#tables
3. Select the contents of the table
4. Right-click the selection and choose the "Copy TSV of table" option
5. See in the consoles that only one message was sent but two were received, and one was ignored

Expected behavior

Messages should not be duplicated. Stardown should not need the extra code to detect duplicate messages.

Screenshots

Other potential fixes I tried that didn't work

• Adding "all_frames": false, to manifest.json in the content_scripts array's first object had no effect. It appears content.js is only being injected once, especially because that is handled entirely by manifest.json.
• I looked through Stardown's code to make sure only one message is sent from background.js, and the message can only be received in one place in content.js. The message handler in content.js calls sendResponse only once.
• I made sure only one instance of Stardown is installed in Chrome. I uninstalled the extension, restarted the browser, reinstalled the extension, and got the same results.
• I looked at the code generated by Rollup to make sure it isn't duplicating anything.
• The relevant sendMessage calls in background.js are already specifying which frame to send the messages to. I tried temporarily changing it to not specify the frames, which had no effect.
• I tried this on multiple different tables and always got the same results.

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.

It would probably be good to rename the setting's code name from linkFormat to selectionFormat.

Existing HTML element ID removed from URL when copying link

To Reproduce
Steps to reproduce the behavior:

1. Go to https://go.dev/doc/faq#references
2. Click Stardown's icon
3. Paste
4. See that the link doesn't contain #references

Expected behavior
The link should contain #references.

Looks like removeIdAndTextFragment is being called when it shouldn't be.

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.

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

Keep selected block quotes when creating block quotes

Stardown's "Copy markdown of selection" option doesn't keep selected block quotes with the setting "when creating markdown of a selection, create a block quote and a page title link".

For example, the selection shown in this photo:

results in this markdown:

The rendered output looks like this:

Dorothy followed her through many of the beautiful rooms in her castle.

— Basic Syntax | Markdown Guide

but should give this result:

The rendered output looks like this:

Dorothy followed her through many of the beautiful rooms in her castle.

— Basic Syntax | Markdown Guide

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.

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

Add settings for mirroring copied images to Stardown's server

Related: #79 and #81

When copying an image to be pasted into a remote editor like GitHub, Stardown only gets the image's URL, not the image itself. This works, but will eventually stop working when the image is no longer served by that URL.

Those using remote editors like GitHub may want Stardown to automatically mirror images and use the mirrored image URLs in image markdown so that image markdown continues working longer.

Most people won't want to set up a mirroring service themselves, but we could provide one for them. However, this could require a lot of time and effort spent moderating the images. Requiring users to create accounts could help. We should discuss this and maybe do some research.

Copy tables as JSON arrays

Being able to copy tables as valid JSON could be very helpful. This issue covers creating JSON of 2D arrays, but a future issue may cover creating JSON of an object of arrays when the table has a header row and/or a header column (if and when implementing converting tables to JSON objects, note that JSON objects must not have duplicate property names, so any duplicates will need to be made unique somehow).

RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format

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.

Embedded YouTube video gives wrong URL when copied

At Engage your audience by getting to the point, using story structure, and forcing specificity – Ian Daniel Stewart, when I make the video load by clicking its play button and then pausing it, and then double-right-click the video and choose "Copy markdown of video", the resulting link's URL is not for a video:

![video](https://iandanielstewart.com/2024/06/09/engage-your-audience-by-getting-to-the-point-using-story-structure-and-forcing-specificity/)

That's just the URL for the current page.

There's a small chance this bug is caused by #52, which is also present on the linked site, however, this bug appears in both Firefox and Chrome unlike #52.

Expected behavior

If possible, the video's URL should be in the link or an error should be shown if there is no video URL available.

Environment

• OS: Windows
• Browser: both Chrome and Firefox
• Device: desktop

Use more smaller files and imports

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

In particular, some of the functions are defined multiple times for each browser extension, such as getSetting which is defined 5 times total.

"Copy markdown link to here" is confusing

Exactly what the "Copy markdown link to here" context menu option does is not entirely clear to users. The description should be changed to make it more obvious that it creates a markdown link not to the entire page, but to where the user right-clicked.

Here are some ideas:

• Copy markdown link to this spot
• Copy markdown link to this element
• Copy markdown link to this part
• Copy markdown link to this part of the page

I feel like starting the option with "Copy markdown link" is a good idea because:

• "Copy" is the most important part of the sentence since the option writes something to the clipboard.
• "markdown link" is the second most important part of the sentence because it answers the question of what is being copied and is literally true.
• The user could stop reading at any time, so it's good to put the most important info first. If they only read the first few words, they might still understand what the option does.

I'm also considering changing middle words. Maybe instead of

Copy markdown link to ___

it could be

Copy markdown link for ___

I will leave this issue open for a while to let others share ideas and give feedback.

Add settings for mirroring copied images to the user's server

Related: #79 and #80

When copying an image to be pasted into a remote editor like GitHub, Stardown only gets the image's URL, not the image itself. This works, but will eventually stop working when the image is no longer served by that URL.

Those using remote editors like GitHub may want Stardown to automatically mirror images and use the mirrored image URLs in image markdown so that image markdown continues working longer.

Some users may want to use an image mirroring service that's external to Stardown but can integrate with Stardown. This way, we would not have to moderate the images.

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.

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

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

Source formatting copies links without titles

If I select part of a page such as the part of Stardown's readme shown in this image:

and, as in this example, any of the section headings has a link next to it that has an empty title or a title that contains only content that Stardown cannot copy (in this case, it's an inline SVG that is only visible when the cursor hovers over it), Stardown still tries to copy the link and ends up with a markdown link without a title when using Stardown's copy option that tries to keep the source formatting. Here is Stardown's current output for the selection in the image:

> [!note]
> from [wheelercj/Stardown: A browser extension that copies a markdown link for the current page.](https://github.com/wheelercj/Stardown#repo-content-pjax-container:~:text=signed%2Din%20devices%22.-,settings,-To%20open%20Stardown's)

## 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

[](https://github.com/wheelercj/Stardown#how-to-change-the-keyboard-shortcut)

-   [Firefox](https://support.mozilla.org/en-US/kb/manage-extension-shortcuts-firefox)
-   Chrome: `chrome://extensions/shortcuts`
-   Edge: `edge://extensions/shortcuts`

Notice the link with no title under the heading "How to change the keyboard shortcut".

Expected behavior

Although this markdown still renders well in GitHub, it does not render well in Obsidian. Links with empty titles should not be in the output, unless they can be moved to use the section heading as the link title.

Markdown images without alt text should be kept.

Update the Firefox version of Stardown to manifest v3

With the release of Firefox v129 on 2024/8/6, Firefox's manifest v3 blue dot bug will be fixed.

After a little while (since there might be a bunch of Firefox users that won't update right away), it would be good to change Stardown's Firefox version to use manifest v3. This will make it more similar to the Chromium version.

Note that Firefox does not support service_worker in manifest v3, so Stardown's use of a background script will not need to--or be able to--change.

Add option for downloading JSON as a file instead of writing to the clipboard

Although Stardown is mainly focused on writing to the clipboard and probably always will be, JSON often needs to be put into a file. There could be a new setting on the options page: "Save JSON output to [the clipboard | a file]". This will require the downloads permission which, when requested, displays the warning message "Manage your downloads" or "Download files and read and modify the browser’s download history", but the permission can be optional and only requested if and when the user changes the setting from its default.

• Permissions | Chrome for Developers
• Request the right permissions | Firefox Extension Workshop

Depending on how this file downloading feature works, there's a chance another setting will be needed or would be helpful: where to download files to.

Keep emphasis when creating block quotes

Stardown's "Copy markdown of selection" option doesn't keep italicization/emphasis with the setting "when creating markdown of a selection, create a block quote and a page title link".

For example, the selection shown in this photo:

results in this markdown:

Italicized text is the cat’s meow.

— Basic Syntax | Markdown Guide

It should result in this markdown:

Italicized text is the cat’s meow.

— Basic Syntax | Markdown Guide

Further nesting of block quotes should also work.

Omit headers, footers, sidebars, etc. when copying entire pages

When I copy a website by pressing Ctrl+A to select everything and use Stardown's selection copy option that tries to keep source formatting, if the page has headers, footers, sidebars, etc., those get copied too. The result looks messy for some sites including all Wikipedia pages. Other browser extensions like MarkDownload omit those parts of sites, and their output looks good. It doesn't make sense for Stardown to omit those in all cases since Stardown also allows copying just part of the page, but if there is a way to detect when the entire page is selected, then all parts of the page that are not highly relevant to that particular page's content should be omitted.

Copy tables as JSON objects

Stardown's latest commits already support copying tables as 2D JSON arrays, but sometimes it might be more helpful to copy tables as JSON objects instead.

However, there are several formats possible. I'm not sure which one(s) to add support for yet and would like feedback from others.

1. For the table below, which of the following JSON format(s) should Stardown be able to create?

a	b	c
d	e	f
g	h	i

• {"a": ["d", "g"], "b": ["e", "h"], "c": ["f", "i"]} (columns)
• {"a": ["b", "c"], "d": ["e", "f"], "g": ["h", "i"]} (rows)
• other

2. What JSON options should appear in the right-click menu?

• Only Copy JSON of table, which creates a 2D array unless the table has a header row (created with <th> elements) and/or a header column, in which case the option creates an object. If there is both a header row and a header column, the header row is used as the property names.
• Both Copy JSON arrays of table and Copy JSON object of table. The object option looks for a header row or header column for the property names, preferring a header row and using the top row if there are no <th> elements.
• All of Copy JSON arrays of table, Copy JSON columns object of table, and Copy JSON rows object of table. Whether there are <th> elements does not matter.
• other

Note that some tables have cells that span multiple rows, such as this one: HTML table advanced features and accessibility - Learn web development | MDN. That table also has multiple header rows and multiple header columns.

3. JSON objects must not have duplicate property names, so some duplicate table cells will need to be made unique somehow. When Stardown is about to create a duplicate property name, should it just append (1), or whatever the next unique number is, to its contents?

For example:

a	a	a	b
c	d	e	f

{"a": ["c"], "a (1)": ["d"], "a (2)": ["e"], "b": ["f"]}

4. Note that since JSON property names must be strings, some data that normally would not be quoted will need to be quoted. For example:

59	true
35	false
11	true	orange

{"59": [35, 11], "true": [false, true], "null": [null, "orange"]}

related

• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format
• #97

Markdown of YouTube videos from Chrome doesn't render well in Obsidian

Double-right-clicking a youtube video shows the "Copy markdown of video" option, but the markdown it creates doesn't show a video, an image, nor a clickable link. It doesn't do anything helpful.

To Reproduce
Steps to reproduce the behavior:

1. In Chrome, go to https://www.youtube.com/watch?v=jfKfPfyJRdk
2. Right-click the video twice
3. Choose "Copy markdown of video"
4. Paste the markdown into Obsidian
5. See that it's just the link [video](blob:https://www.youtube.com/05302dd9-f809-4ba5-9431-c26539b61bc6), and that clicking it doesn't open the website

Expected behavior
A video player should appear in Obsidian. Here's a screenshot of the video player created in Obsidian when I do all of the above but with Firefox:

Environment

• OS: Windows
• Browser: Chrome
• Device: desktop

Copy SQL of table

Users may find it helpful to be able to select a table on a website, right-click, and choose "Copy SQL of table" to copy the table as all the SQL statements necessary to create the same table in a database so that they can run SQL queries on the data. Most tables on websites don't let you filter, sort, group, or do much of anything with the data. This feature would make all of that possible in seconds for anyone already familiar with SQLite. Although Stardown already supports this kind of workflow with "Copy JSON of table" and then using a tool like jqlang/jq: Command-line JSON processor, some users might prefer to use SQL queries.

This feature will target SQLite statements because they are mostly (completely?) compatible with other SQL languages, and SQLite is perfect for creating a temporary table to quickly crunch some data.

For example, the table below could become the following SQL statements.

#	Country	Population
1	India	1,428,627,663
2	China	1,425,671,352
3	United States	339,996,563
4	Indonesia	277,534,122
5	Pakistan	240,485,658

CREATE TABLE temp (
    number INT,
    country TEXT,
    population INT
);

INSERT INTO temp
(number, country, population)
VALUES
    (1, "India", 1428627663),
    (2, "China", 1425671352),
    (3, "United States", 339996563),
    (4, "Indonesia", 277534122),
    (5, "Pakistan", 240485658);

Table name

If the HTML table has a caption, the SQL table's name can be derived from it. Otherwise, the SQL table name can be temp or something else easy to type and easy to replace if needed.

Column names

Some HTML tables have a header row like the one above, but others don't and instead have a header column. Others have both. Stardown will need to detect which exist, choose between them, and possibly make adjustments like changing # to number. Some HTML tables have neither a header row nor a header column, in which case the SQL column names can be a, b, c, . . ., z, aa, ab, etc. similarly to in Excel.

Column types

Determining the type of each column will probably require iterating through all the cells in the column to make sure they all match a certain datatype.

IDs and Constraints

Adding IDs or constraints like NOT NULL when they might apply is probably unnecessary because this feature is mostly useful for quick data querying and manipulation where there is not as much need to be careful with the data.

Downloading a file

After adding this feature, another that may naturally follow is for Stardown to directly create and download a SQLite file if the user chose that in the settings. Stardown should probably not do this by default since the file downloading permission can be optional and some users might not want to grant that permission.

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

Copy tables as CSV

Users may want to be able to copy tables in the CSV format. A new setting in the options page could be created for which table format to use.

Customize selection output with a template

Users may want to be able to customize the formatting of what appears around copied selections. Here are Stardown's current options for selections:

The default option ("try to keep the same formatting and link to the source") includes a note alert that contains a link to the selection's source and the date it was copied. Alerts render well in GitHub and Obsidian, but not in all markdown editors. Even where they do render well, users might want source links without alerts.

There could be another option, maybe "try to keep the same formatting and apply a custom template", that allows the user to provide a template to customize what appears around the selection and/or to change the selection markdown itself.

This change will probably require adding a large text box to the options page.

Tables with inconsistent row widths don't render in GitHub

Many tables have only one cell in their header row and more than one cell in their body rows. This works well in HTML, but is not allowed in markdown. Obsidian automatically detects tables poorly formatted in this way and fixes them, but GitHub doesn't. Stardown's source format copy options currently don't create the extra empty cells necessary in the header row for tables to render well in GitHub, but should if possible.

To Reproduce
Steps to reproduce the behavior:

1. Go to https://en.wikipedia.org/wiki/Roopnagar
2. Select the table
3. Use Stardown's copy option
4. Paste into GitHub
5. See that the table does not render
6. Add a space and a pipe symbol to the table's first row
7. See that the table now renders

Stardown should count the cells in the table's second row, if one exists, when deciding how many cells to have in the first row.

Table rowspans are ignored

HTML table cells (th and td elements) can have attributes colspan and rowspan that allow the cell to span multiple columns and/or rows. Stardown handles colspans well by creating empty cells as needed, but currently ignores rowspans.

To Reproduce
Steps to reproduce the behavior:

1. Go to https://developer.mozilla.org/en-US/docs/Learn/HTML/Tables/Advanced#tables_for_visually_impaired_users
2. Select the contents of the table
3. Use Stardown to copy the table
4. Paste into an editor
5. See that the first row is correct but the second one is incorrect because the rowspan in the first row was ignored

Expected behavior
Empty cells should be added as needed to imitate the rowspans.

Screenshots
Here's a screenshot of the selection described above:

Between the two horizontal rules below is Stardown's current output for the selection.

---

Note

from HTML table advanced features and accessibility - Learn web development | MDN

Items Sold August 2016

		Clothes			Accessories
Trousers	Skirts	Dresses	Bracelets	Rings
Belgium	Antwerp	56	22	43	72	23
Gent	46	18	50	61	15
Brussels	51	27	38	69	28
The Netherlands	Amsterdam	89	34	69	85	38
Utrecht	80	12	43	36	19

---

Additional context
Note that a single cell can use both the rowspan and colspan attributes. The relevant part of the code to change is in src/tables.js (and there are no tests for this yet, so also test/tables.js). The three cells with rowspans in the example table may be relatively easy to handle since they're on the table's left edge, but Stardown ideally should be able to handle rowspans elsewhere as well.

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. Change the value of the "Double-click interval (milliseconds)" setting to a very low or very high number.
2. Save the settings.
3. Double-click Stardown's icon.
4. See that the interval you chose was not applied.
5. Double-click the icon again.
6. See that the interval you chose is now applied.

Expected behavior
All settings should apply immediately on their save.

Additional context
This bug is currently present only for the doubleClickInterval setting, because that is the only one that relates to an optional permission (the tabs permission).

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
// doubleClickInterval setting is retrieved later.
havePerm = await browser.permissions.request({ permissions: ['tabs'] });

...

doubleClickInterval = await getSetting('doubleClickInterval', 500);

I'm not sure how to fix this right now. Maybe we can send a message with the updated doubleClickInterval from the saveOptions function in options.js to background.js? The permission request should probably stay where it is.

Add settings for downloading copied images

Related: #80 and #81

When copying an image, Stardown only gets the image's URL, not the image itself. This works, but will eventually stop working when the image is no longer served by that URL. Those using local editors like Obsidian may want Stardown to download images, automatically put them in a folder of their choice, and include the file path to the downloaded image in the image markdown.

This will require another browser extension permission, but the permission can be optional and only requested if and when the user turns on image downloading in Stardown's settings.

This feature will require two new settings:

• whether to download images (default to not downloading)
• where to download images to

Copying Microsoft devblogs code blocks loses formatting

Using Stardown to copy the code blocks in Microsoft's devblogs results in markdown that does not have the same formatting as what's on the website. All newline characters are removed, the code blocks are inline instead of fenced, and selecting only the contents of the code block results in markdown with no code block of any kind.

To Reproduce
Steps to reproduce the behavior:

1. Go to C# 13: Explore the latest preview features - .NET Blog
2. Select only all the contents of a code block
3. Copy with Stardown and paste
4. See that there is no code block, and that all newlines were removed
5. On the website, select a code block including some text before it
6. Copy with Stardown and paste
7. See that there is a code block, but it's only an inline one instead of a fenced one, and still all newlines were removed

Expected behavior
A fenced code block with any newlines in the selection, even when only the contents of the site's code block were selected.

Markdown of videos

When Stardown creates a markdown of a video, it would be nice if it would facilitate the creation of an image of the video & player, then create a markdown for that image as a clickable link to the video.

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        |

"Clipboard write is not allowed" error from some sites in Firefox

On some sites in Firefox, clicking Stardown's icon successfully writes to the clipboard but also shows a red X on the icon and a notification with the error message "Clipboard write is not allowed".

I saw this happen on these Wordpress sites:

• Engage your audience by getting to the point, using story structure, and forcing specificity – Ian Daniel Stewart
• Houston Zoo - See them. Save them.
• Home - Grette
• SeedProd - Best Drag & Drop WordPress Website Builder & Landing Page Builder
• WPForms - The World's Best Drag & Drop WordPress Forms Plugin
• Sony Music - Official Website
• Radiant Energy Deliciously Delivered (R.E.D.D.) Whole Food Nutrition
• Nalgene – The original water bottle. BPA Free.
• Unconquered: Creative advertising agency - strategy & content production
• Home - Melyssa Griffin

Also on theses site that might not be Wordpress sites:

• Kamal — Deploy web apps anywhere
• CapRover · Scalable, Free and Self-hosted PaaS!

I also saw this bug on some sites until I refreshed the page and tried again, but other sites keep having the bug even after refreshes.

Some Wordpress sites don't show any error (and still write to the clipboard successfully):

• Awesome Motive - Helping Small Businesses Grow & Compete with the Big Guys
• WPBeginner - Beginner's Guide for WordPress
• Blog Tyrant - #1 Resource to Help You Build a Better Blog
• The New York Times - Breaking News, US News, World News and Videos
• TNW | The heart of tech
• Front page | Angry Birds
• NOVE: Public Affairs and Communication | Nove
• Sean O'Brien, Pro Windsurfer - seanobrien.com.au™
• 99% Invisible

Expected behavior
Since the clipboard is being written to successfully, the error indicators should not be shown.

Environment

• OS: Windows
• Browser: Firefox
• Device: desktop

Additional context
I tried many of the sites listed above in Chrome, and none of them showed any error indicators.

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