Skip to content

Latest commit

 

History

History
89 lines (54 loc) · 8.86 KB

develop.md

File metadata and controls

89 lines (54 loc) · 8.86 KB
Raw

Stardown development

I wrote some general extension development tips in Making browser extensions. For more context about markdown itself, see CommonMark: A Formal Specification For Markdown — Smashing Magazine.

Goals

Stardown's main goal is to be so simple, fast, reliable, and flexible that people think of it as "it's like Ctrl+C but it keeps formatting". The settings page can have many settings as long as they are well organized, useful, and not so important that many users will be constantly changing them. Stardown's output should render well in at least Obsidian and GitHub, if not also other markdown renderers and converters.

Tests

Run the tests with npm run test.

If a certain test fails, its error message will tell you to run npm run md-diff. See ../src/converters/README.md#testing for more details.

Manual testing is often helpful too. When testing manually, see ./manual-testing.md.

Git workflow

Let's create feature branches with descriptive names and make pull requests as described in Getting started with Git and GitHub.

Writing import statements

Stardown uses several different execution contexts as described in ./execution-contexts.md, and development of Stardown uses the Rollup bundler to combine the files for each context. Rollup copies an entire file's content (and the content of all files that file imports) into another file even if the import statement only asks for specific things. For this reason, try to avoid putting functions and imports for one execution context in a file that is only for a different execution context, or else the resulting bundled code will have a lot of duplicate unused code that might go unnoticed except by extension reviewers.

Writing documentation

This project uses JSDoc to annotate types. In VS Code you can type /** above a function and press enter to auto-generate part of its JSDoc comment (this might require the ESLint extension).

Improving Stardown's output

If changes to improve the output can apply to:

  • all/many sites:
  • specific sites:
    • both selections and entire pages: the changes should probably be made in the improveConvertibility function
    • only entire pages: the changes should probably be made in ../src/extractMainContent.js

How Stardown works

If you want to read a broad overview of Stardown's components and how they communicate with each other, see ./execution-contexts.md.

Stardown converts HTML to other formats using custom code explained in ../src/converters/README.md.

Some differences between Chromium and Firefox

Performance

Stardown currently does not cause any noticeable performance problems, but the articles linked below might be helpful in the future. Stardown's main performance impact is probably from injecting content scripts; the code is injected eagerly and none of it is minified. Also, only the primary browser thread is used (no worker threads).

Text fragments

Text fragments and how to generate them is explained in Text fragments | MDN and in Boldly link where no one has linked before: Text Fragments | web.dev. The second article mentions a minified version of the text fragment generation code, but Stardown doesn't use the minified version because extension stores need to be able to review the code and minifying code doesn't really help extensions.

Stardown's text fragment generation code, which was almost entirely written by Google, is in the files named text-fragment-utils.js and fragment-generation-utils.js. They probably should not be changed for anything except fixing bugs or updating to new versions of text fragments.

Stardown also tries to find HTML element IDs to put in links alongside text fragments because if the website ever changes and makes the text fragment outdated, the browser will use the HTML element ID as a fallback.

Tables

HTML tables have more features than markdown and other plaintext tables, but Stardown's custom code for converting tables from HTML to markdown or another plaintext format should still always create valid tables that are as similar to the HTML as possible.

Some HTML tables have cells that span multiple rows and/or columns, such as this one. Markdown and other plaintext formats don't allow that, so they must have extra cells to match the spans.

From my experience so far, markdown renderers tend to require every markdown table to have one header row followed by one table divider, then zero or more body rows. The number of cells in the header row must be equal to that of the table divider and to that of whichever row has the most cells. Body rows may have varying numbers of cells.

Sample markdown tables for testing markdown renderers can be found in ./sample-tables.md.

HTML table definition

In this order: optionally a caption element, followed by zero or more colgroup elements, followed optionally by a thead element, followed by either zero or more tbody elements or one or more tr elements, followed optionally by a tfoot element, optionally intermixed with one or more script-supporting elements.

— the HTML Standard