docs: write initial documentation (#21)

Author: doc-han

.github/workflows/publish_docs.yml

@@ -0,0 +1,38 @@
+name: Publish xtensio docs
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+
+      - run: pip install mkdocs-material
+
+      - run: mkdocs gh-deploy --force

.gitignore

@@ -1,4 +1,8 @@
 .build
 node_modules
 yarn-error.log
-.DS_Store
+.DS_Store
+.vscode
+**/xtensio-docs/site
+.env
+*.env

package.json

@@ -9,7 +9,8 @@
     "build": "yarn workspaces run build",
     "push": "yarn workspaces run push",
     "lint": "yarn workspaces run lint",
-    "lint:fix": "yarn workspaces run lint:fix"
+    "lint:fix": "yarn workspaces run lint:fix",
+    "docs:serve": "yarn workspace xtensio-docs run serve"
   },
   "workspaces": [
     "packages/*"
@@ -18,4 +19,4 @@
   "devDependencies": {
     "husky": "^8.0.3"
   }
-}
+}

packages/xtensio-docs/Dockerfile

@@ -0,0 +1,2 @@
+FROM squidfunk/mkdocs-material
+RUN pip install mkdocs-git-committers-plugin-2

packages/xtensio-docs/docs/assets/extension-popup-image.png

@@ -0,0 +1,16 @@
+---
+hide:
+  - footer
+---
+
+<h1 align="center">
+        <img style="margin: 50px 0px" width="400px" src="https://raw.githubusercontent.com/doc-han/xtensio/master/statics/xtensio.png" />
+</h1>
+
+## What is xtensio?
+
+**xtensio** (pronounced /**ɛkˈtɛn.ʃoʊ**/, like **"ex-TEN-see-oh"**) is javascript framework for building browser extensions. It leverages [React.js](https://reactjs.org) to provide a well-organized folder structure that supports a declarative approach, simplifying and accelerating extension development.
+
+## How does it work?
+
+**xtensio** provides you with a folder structure that comes with configurations already baked in. Hence, no configuration is needed to get started with your new extension project. Currently, it mainly supports React for development.

packages/xtensio-docs/docs/assets/folder-structure.png

@@ -0,0 +1,25 @@
+To change icons for your extension. You just need to have them in the `public` directory and then import them into your `manifest.js` file.
+
+> How to import extension icons of several dimensions
+
+```ts title="manifest.js" linenums="1" hl_lines="2 3 4 5 11 12 13 14 15 16"
+import packageJson from "./package.json";
+import icon16 from "@public/icons/icon16.png";
+import icon32 from "@public/icons/icon32.png";
+import icon48 from "@public/icons/icon48.png";
+import icon128 from "@public/icons/icon128.png";
+
+export default {
+  name: "simple-extension", // extension name
+  manifest_version: 3,
+  version: packageJson.version,
+  icons: {
+    16: icon16,
+    32: icon32,
+    48: icon48,
+    128: icon128,
+  },
+};
+```
+
+And that's it! your extension icons have been updated.

packages/xtensio-docs/docs/assets/logo-black.png

@@ -0,0 +1,34 @@
+The extension popup is the small UI that shows up when you click an extension icon. [see what it looks like](#popup_image)
+
+Inside the popup folder is a file :material-language-javascript: `popup.jsx` (or :material-language-typescript: `popup.tsx` depending on what you're using) which exports a React component. This is the single entry point for your extension popup.
+
+=== ":material-language-typescript: Javascript"
+
+    ```js title="/popup/popup.jsx" linenums="1"
+    const PopupPage = () => {
+      return <div>This is the extension popup</div>;
+    };
+
+    export default PopupPage;
+    ```
+
+=== ":material-language-typescript: Typescript"
+
+    ```ts title="/popup/popup.tsx" linenums="1"
+    const PopupPage: React.FC = () => {
+      return <div>This is the extension popup</div>;
+    };
+
+    export default PopupPage;
+    ```
+
+There's no limit to what you can do here. you can import other components and do awesome stuff.
+
+## What does it look like?
+
+like this!
+
+<figure markdown="span" id="popup_image">
+  ![A browser extension popup](/assets/extension-popup-image.png){ width="80%" }
+  <figcaption>A browser extension popup</figcaption>
+</figure>

packages/xtensio-docs/docs/assets/logo-long.png

@@ -0,0 +1,78 @@
+## What are Extension Pages?
+
+Think of extension pages as webpages that are hosted by your extension. Hence, these pages are only available once a user has your extension installed.
+
+## What are they for?
+
+Extension Pages can be used to create configuration or settings pages, Terms of Service pages, and similar things you'll like to dedicate a page for.
+
+## How to create an Extension Page
+
+1. Create a `.jsx` or `.tsx` file in the `pages` directory.
+2. Write a React component
+3. Export this component as the default export
+
+> An example settings page
+
+=== ":material-language-javascript: Javascript"
+
+    ```ts title="/pages/settings.jsx" linenums="1" hl_lines="18"
+    import { useState } from "react"
+
+    const SettingsPage = () => {
+      const [theme, setTheme] = useState("light");
+
+      const themeChangeHandler = (e)=> {
+        setTheme(e.target.name);
+      }
+
+      return <>
+        <div>Select theme:</div>
+        <input value={theme} type="radio" name="light" onChange={themeChangeHandler} />
+        <input value={theme} type="radio" name="dark" onChange={themeChangeHandler} />
+      </>
+    };
+
+    // default export a react component to have a page
+    export default SettingsPage;
+    ```
+
+=== ":material-language-typescript: Typescript"
+
+    ```ts title="/pages/settings.tsx" linenums="1" hl_lines="18"
+    import { useState } from "react"
+
+    const SettingsPage: React.FC = () => {
+      const [theme, setTheme] = useState("light");
+
+      const themeChangeHandler = (e: React.ChangeEvent<HTMLInputElement>)=> {
+        setTheme(e.target.name);
+      }
+
+      return <>
+        <div>Select theme:</div>
+        <input value={theme} type="radio" name="light" onChange={themeChangeHandler} />
+        <input value={theme} type="radio" name="dark" onChange={themeChangeHandler} />
+      </>
+    };
+
+    // default export a react component to have a page
+    export default SettingsPage;
+    ```
+
+## How to navigate to an Extension Page
+
+After creating an extension page, you should be able to navigate to it from anywhere in the extension. xtensio provides a utility function `visitPage` for that.
+
+To visit a page, just call `visitPage` with the name of the page without the file extension.
+
+> How to visit a page that was created at `/pages/settings.tsx`
+
+```ts title="somewhere-in-your-extension" linenums="1"
+import { visitPage } from "xtensio"
+...
+visitPage("settings");
+...
+```
+
+That's all you need to navigate to an Extension Page you've created in your extension.

packages/xtensio-docs/docs/assets/logo-no-black.png

@@ -0,0 +1,13 @@
+Xtensio does support environment variables out of the box.
+
+Create any of the below env files at the root of your project and keep some environment variables in them.
+
+| Type        | Filename                      | Description                                         |
+| ----------- | ----------------------------- | --------------------------------------------------- |
+| Global      | `.env`                        | used for **both development and production builds** |
+| Development | `.dev.env` `.development.env` | used for **only development**                       |
+| Production  | `.prod.env` `.production.env` | used for **only production builds**                 |
+
+Hence, you can have the development version of a variable in `.dev.env` and the production version of it in `.prod.env` and xtensio will know what to use when.
+
+> Note: Development is when you run `yarn dev` or `npm run dev` and Production is when you run `yarn build` or `npm run build`

packages/xtensio-docs/docs/assets/logo-no.png

@@ -0,0 +1 @@
+welcome

packages/xtensio-docs/docs/assets/logo-slim.png

@@ -0,0 +1,3 @@
+Inside the background folder is an `index.ts` or `index.js` file which serves as your single entry point for your extension's service worker or background script.
+
+> You can freely create other files in the background directory and use them or import them into the `index.ts` file.

packages/xtensio-docs/docs/assets/logo.png

@@ -0,0 +1,121 @@
+This is the heart ❤️ of browser extension development where most of the real magic happens.
+
+The primary goal of a browser extension is to change the user experience of website or to supercharge the browser. This could mean changing the looks or adding some functionalities to websites. This type of manipulation is handled by content files in xtensio.
+
+## How to use contents in xtensio
+
+Every content file has two parts.
+
+| Part                                                  | What it does                                                       |
+| ----------------------------------------------------- | ------------------------------------------------------------------ |
+| [:link:**`config`**](#how-to-define-a-content-config) | Defines where & how a specific code should be executed             |
+| [:link:**`code`**](#how-to-define-code)               | Some code that is to be executed when conditions in config are met |
+
+## How to define a content config
+
+A content config is defined as an exported function with the name `getConfig` that returns an object.
+
+> Below is an an example content config that runs only on google.com domains
+
+=== ":material-language-javascript: Javascript"
+
+    ```js title="/contents/google.jsx" linenums="1"
+    export function getConfig() {
+        return {
+            matches: ["*://*.google.com/*"],
+        };
+    }
+    ```
+
+=== ":material-language-typescript: Typescript"
+
+    ```ts title="/contents/google.tsx" linenums="1"
+    import { ContentConfig } from "xtensio"
+
+    export function getConfig(): ContentConfig {
+        return {
+            matches: ["*://*.google.com/*"],
+        };
+    }
+    ```
+
+## How to define code
+
+The code to be executed when a content config is matched can be any form of javascript. DOM manipulation, or any kind of web acceptable javascript/typescript.
+
+> Below is an example content file that print "This is google" whenever you're on google.
+
+=== ":material-language-javascript: Javascript"
+
+    ```js title="/contents/google.jsx" linenums="1" hl_lines="7"
+    export function getConfig() {
+        return {
+            matches: ["*://*.google.com/*"],
+        };
+    }
+
+    console.log("This is google")
+    // you can have complex scripts here. even DOM manipulation
+    ```
+
+=== ":material-language-typescript: Typescript"
+
+    ```ts title="/contents/google.tsx" linenums="1" hl_lines="9"
+    import { ContentConfig } from "xtensio"
+
+    export function getConfig(): ContentConfig {
+        return {
+            matches: ["*://*.google.com/*"],
+        };
+    }
+
+    console.log("This is google")
+    // you can have complex scripts here. even DOM manipulation
+    ```
+
+## Mounting UI into websites using React
+
+With the use of [React.js](https://react.dev) you can mount React components on any website by just making the component the default export in the content file.
+
+> An example content file that mounts UI into amazon.com using React
+
+=== ":material-language-javascript: Javascript"
+
+    ```js title="/contents/amazon.jsx" linenums="1" hl_lines="9 10 11 12 13 14"
+    import { useState } from "react"
+
+    export function getConfig() {
+        return {
+            matches: ["*://*.amazon.com/*"],
+        };
+    }
+
+    const SomeComponent = () => {
+        const [count, setCount] = useState(0);
+        return <div onClick={()=> setCount(count+1)}>click to change {count}</div>
+    }
+
+    export default SomeComponent;
+    ```
+
+=== ":material-language-typescript: Typescript"
+
+    ```ts title="/contents/amazon.tsx" linenums="1" hl_lines="10 11 12 13 14 15"
+    import { useState } from "react"
+    import { ContentConfig } from "xtensio"
+
+    export function getConfig(): ContentConfig {
+        return {
+            matches: ["*://*.amazon.com/*"],
+        };
+    }
+
+    const SomeComponent: React.FC = () => {
+        const [count, setCount] = useState(0);
+        return <div onClick={()=> setCount(count+1)}>click to change {count}</div>
+    }
+
+    export default SomeComponent;
+    ```
+
+You can now build awesome extensions that manipulate websites and provide tailored experiences for users ❤️.