Skip to Content
webext-notionish

πŸ”§ Development

Running Notionish from source, probing Google's markup, and how releases are built and signed.

Notionish is plain JavaScript and hand-written CSS under Manifest V2, with web-ext (pinned at 10.6.0) doing the running, linting, building and signing. It needs Node 20 or later.

Running it

git clone https://github.com/kud/webext-notionish.git
cd webext-notionish
npm install
npm run dev

npm run dev launches Firefox Nightly with the extension loaded and reloaded on every file change, using a persistent profile at ~/.cache/notionish-dev-profile. Sign into Google there once; the profile is kept between runs, and there is nothing to test against without a real session. npm run dev:clean uses a throwaway profile instead, for a first-install view.

To load it by hand, open about:debugging#/runtime/this-firefox, choose Load Temporary Add-on and pick manifest.json. Temporary add-ons need an explicit Reload after each change and are dropped when Firefox restarts.

Scripts

ScriptWhat it does
npm run devFirefox Nightly on the persistent dev profile, extension loaded and watched
npm run dev:cleanThe same on a fresh temporary profile
npm run lintweb-ext lint
npm run buildBuilds the package into web-ext-artifacts/
npm run versionCopies the package.json version into manifest.json
npm run publishBuilds, then opens the AMO Developer Hub for a first manual submission

publish.sh, tools/, package-lock.json and .github/ are left out of every built and signed package.

How it fits together

src/content.js runs at document_start, works out the surface from the URL, reads the settings and, if that surface is enabled, sets data-notionish-surface and data-notionish-focus on the page's root element. Every hiding and restyling rule in src/content/shared.css, docs.css and sheets.css is gated on those attributes, so if the script never runs the stylesheets do nothing and Google's normal interface shows.

JavaScript reaches past the stylesheets in only three places, all because canvas text is out of a stylesheet's reach: the injected @font-face for the UI typeface, the optional document font swap, and the Docs zoom. src/background.js performs the zoom with tabs.setZoom, which a content script cannot call, and relays the keyboard shortcut to the active tab.

src/settings.js is the single declaration of the stored preferences, loaded as a classic script by the content script, popup and options page alike.

Probing Google's markup

Google changes Docs and Sheets markup without notice. Every selector the stylesheets depend on is tracked in SELECTORS.md, tiered by evidence: confirmed on a live document, confirmed absent, or unverified. When something reappears, probe rather than guess.

Each probe script copies a snippet to the clipboard (macOS, via pbcopy). Paste it into the page console on a real Doc or Sheet (Cmd+Opt+K, not the Browser Console):

ScriptFileAnswers
npm run probe:selectorsselector-probe.jsWhich elements exist, and which are visible despite a rule
npm run probe:spacingspacing-probe.jsWhich element owns each vertical gap, and the page's box geometry
npm run probe:headerheader-probe.jsThe same question along the header row
npm run probe:modelmodel-probe.jsWhat Docs' own document model contains
npm run probe:titletitle-query.jsMeasures the title field once you click into it to rename

Releasing

CI runs npm run build and npm run lint on every push to main and on pull requests.

Pushing a v* tag runs the release workflow, which signs the package and uploads it to addons.mozilla.org. The very first submission of a new add-on has to go through the Developer Hub by hand, which is what npm run publish sets up.