Skip to content

Latest commit

 

History

History
113 lines (74 loc) · 10.7 KB

develop.md

File metadata and controls

113 lines (74 loc) · 10.7 KB

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 GitHub and Obsidian, if not also other markdown renderers and converters.

Tests

Run the tests with npm 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.

This project uses Prettier to format code. The formatting is enforced on each pull request, so you might want to install Prettier into your editor and as a Git hook.

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's tree-shaking doesn't seem to always work, so 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 might 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.

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

Releasing

Here's what I do when creating a new release:

  1. Make sure the tests pass with npm test.
  2. Make sure the privacy notice is up to date and accurate.
  3. Update the VERSION variable in ../src/version.js.
  4. Run npm run check-version to make sure the new version is correctly formatted.
  5. If the new version is a stable release:
    1. Update the "version" properties in the manifests.
    2. If the new version includes some interesting changes and is not just bug fixes:
      1. Create a new HTML file in the ../src/upboard/ folder.
  6. Commit, push, make a pull request into the main branch, merge, and pull.
  7. Tag the merge commit with the same value as the VERSION variable in version.js.
  8. Push the tag. This will trigger a GitHub Actions workflow that will build the extension and create a release.
  9. Run gh workflow run pages.yaml to rebuild the instructions page. I tried to make this step run automatically on new release tags, but for some reason the deploy job would always ignore the artifact most recently uploaded by the build job and use the previous one instead.
  10. If the new version is a stable release:
  11. Update the extension marketplace pages including adding the release notes. Make sure everything is up to date and accurate.
  12. Submit the changes for review.