docs: Add links to symbols

docs/.vitepress/config.ts

@@ -1,5 +1,5 @@
 import { defineConfig } from 'vitepress';
-import { typescriptDocs } from './plugins/typescript-docs';
+import { defineTypescriptDocs } from './plugins/typescript-docs';
 
 const ogDescription = 'Next Generation Frontend Tooling';
 const ogTitle = 'Web Ext Core';
@@ -93,18 +93,11 @@ const apiItemGroup = {
 };
 
 export default defineConfig({
+ ...defineTypescriptDocs(packageDirnames),
+
  title: `Web Ext Core`,
  description: 'Web Extension Development Made Easy',
 
- ignoreDeadLinks: [/^\/api\/.*/],
-
- vite: {
- plugins: [typescriptDocs()],
- define: {
- __PACKAGES__: JSON.stringify(packageDirnames),
- },
- },
-
  head: [
  ['link', { rel: 'icon', type: 'image/svg+xml', href: '/logo.svg' }],
  ['meta', { property: 'og:type', content: 'website' }],

docs/.vitepress/plugins/typescript-docs.ts

@@ -5,6 +5,104 @@ import { Listr, ListrTask, ListrTaskWrapper } from 'listr2';
 import { Project, Symbol, SourceFile, Node, ts, JSDocableNode, JSDoc } from 'ts-morph';
 import * as prettier from 'prettier';
 import chokidar from 'chokidar';
+import { defineConfig } from 'vitepress';
+import { parseHTML } from 'linkedom';
+
+export function defineTypescriptDocs(packageDirnames: string[]) {
+ const ctx: Ctx = {
+ watchers: [],
+ symbolMap: {},
+ };
+
+ function plugin(): Plugin {
+ let mode: 'build' | 'serve';
+ let hasGenerated = false;
+
+ return {
+ name: 'generate-ts-docs',
+ configResolved(config) {
+ mode = config.command;
+ },
+ async buildStart() {
+ if (hasGenerated) return;
+ hasGenerated = true;
+
+ const allPackages = await getPackages();
+ await generateAll(ctx, allPackages, mode, mode === 'serve');
+ },
+ async buildEnd() {
+ removeWatchListeners(ctx);
+ },
+ };
+ }
+
+ return defineConfig({
+ ignoreDeadLinks: [/^\/api\/.*/],
+
+ vite: {
+ plugins: [plugin()],
+ define: {
+ __PACKAGES__: JSON.stringify(packageDirnames),
+ },
+ },
+
+ transformHtml(code, id) {
+ const [_, thisPkg] = id.match(/\/api\/(.*)\.html$/) ?? [];
+ if (!thisPkg) return;
+
+ const { document } = parseHTML(code);
+ /**
+ * Creates an anchor element to a symbol's package.
+ */
+ const createLink = (
+ symbolName: string,
+ thisPkg: string,
+ packages: string[],
+ ): HTMLAnchorElement => {
+ const a = document.createElement('a');
+ a.textContent = symbolName;
+ if (packages.includes(thisPkg)) {
+ a.href = '#' + symbolName.toLowerCase();
+ } else {
+ a.href = `/api/${packages[0]}#${symbolName.toLowerCase()}`;
+ }
+ return a;
+ };
+
+ // Code blocks - same text color, underlined
+ document.querySelectorAll('pre span').forEach(span => {
+ Object.entries(ctx.symbolMap).forEach(([symbolName, packages]) => {
+ if (span.textContent !== symbolName) return;
+
+ const a = createLink(symbolName, thisPkg, packages);
+ a.style.color = 'inherit';
+ a.style.textDecoration = 'underline';
+ span.replaceChildren(a);
+ });
+ });
+
+ // Inline code - primary color, underlined links
+ document.querySelectorAll('p code, li code').forEach(block =>
+ Object.entries(ctx.symbolMap).forEach(([symbolName, packages]) => {
+ // Look for matching full word
+ if (
+ !block.textContent
+ ?.replace(/[.,\/#!$%\^&\*;:{}=\-_`~()]/g, '')
+ .split(/\s+/)
+ .includes(symbolName)
+ )
+ return;
+
+ const a = createLink(symbolName, thisPkg, packages);
+ a.style.textDecoration = 'underline';
+ block.innerHTML = block.innerHTML.replace(symbolName, a.outerHTML);
+ }),
+ );
+
+ return document.toString();
+ },
+ });
+}
 
 type Plugin = NonNullable<NonNullable<UserConfig['vite']>['plugins']>[0];
 type SymbolLinks = { [symbolName: string]: string };
@@ -26,28 +124,6 @@ const EXCLUDED_SYMBOLS = [
  'TReturn',
 ];
 
-export function typescriptDocs(): Plugin {
- const ctx: Ctx = {
- watchers: [],
- symbolMap: {},
- };
- let mode: 'build' | 'serve';
-
- return {
- name: 'typescript-docs',
- configResolved(config) {
- mode = config.command;
- },
- async buildStart() {
- const allPackages = await getPackages();
- await generateAll(ctx, allPackages, mode, mode === 'serve');
- },
- async buildEnd() {
- removeWatchListeners(ctx);
- },
- };
-}
-
 /**
  * context passed into each task
  */

docs/api/job-scheduler.md

@@ -75,7 +75,7 @@ interface IntervalJob {
 }
 ```
 
-A job that executes on a set interval, starting when the job is scheduled.
+A job that executes on a set interval, starting when the job is scheduled for the first time.
 
 ### Properties 
 
@@ -84,11 +84,10 @@ A job that executes on a set interval, starting when the job is scheduled.
 - ***`type: 'interval'`***
 
 - ***`duration: number`***<br/>Interval in milliseconds. Due to limitations of the alarms API, it must be greater than 1
-minute and it will be rounded to the nearest minute.
+minute.
 
 - ***`immediate?: boolean`*** (default: `false`)<br/>Execute the job immediately when it is scheduled for the first time. If `false`, it will
-execute for the first time after `durationInMs`. This has no effect when updating an existing
-job.
+execute for the first time after `duration`. This has no effect when updating an existing job.
 
 - ***`execute: ExecuteFn`***
 
@@ -123,7 +122,7 @@ interface JobSchedulerConfig {
 }
 ```
 
-Cofnigure how the messenger behaves.
+Configures how the job scheduler behaves.
 
 ### Properties 
 

docs/api/messaging.md

@@ -32,7 +32,7 @@ interface ExtensionMessagingConfig {
 }
 ```
 
-Cofnigure how the messenger behaves.
+Configure how the messenger behaves.
 
 ### Properties 
 
@@ -110,7 +110,7 @@ Unlike the regular `chrome.runtime` messaging APIs, there are no limitations to
 ## `ProtocolWithReturn`
 
 :::danger Deprecated
-Use the function syntax instead: <https://webext-core.aklinker1.io/messaging/protocol-maps.html#syntax>
+Use the function syntax instead: <https://webext-core.aklinker1.io/guide/messaging/protocol-maps.html#syntax>
 :::
 
 ```ts

package.json

@@ -8,7 +8,6 @@
  "docs:build": "vitepress build docs",
  "docs:serve": "vitepress serve docs",
  "docs:test": "vitest -r docs",
- "docs:generate": "typedoc --plugin typedoc-plugin-markdown",
  "build": "turbo run build",
  "prepare": "husky install"
  },
@@ -28,5 +27,8 @@
  "vitepress": "1.0.0-alpha.75",
  "vitest": "^0.29.2",
  "webextension-polyfill": "^0.10.0"
+ },
+ "dependencies": {
+ "linkedom": "^0.14.26"
  }
 }

packages/messaging/src/index.ts

@@ -27,7 +27,7 @@ export interface ExtensionMessagingConfig {
  *
  * > Internally, this is just an object with random keys for the data and return types.
  *
- * @deprecated Use the function syntax instead: <https://webext-core.aklinker1.io/messaging/protocol-maps.html#syntax>
+ * @deprecated Use the function syntax instead: <https://webext-core.aklinker1.io/guide/messaging/protocol-maps.html#syntax>
  *
  * @example
  * interface ProtocolMap {