added a more realistic starting point for docs

Author: Shane Osbourne

packages/special-pages/index.js

@@ -7,6 +7,9 @@
  * A collection of HTML/CSS/JS pages that can be loaded into privileged environments, like `about: pages`
  *
  * - {@link "Example Page"}
+ *
+ * [[include:packages/special-pages/readme.md]]
+ *
  */
 import { join } from 'node:path'
 import { existsSync, cpSync, rmSync } from 'node:fs'

packages/special-pages/pages/example/readme.md

@@ -1,2 +1,34 @@
-This is an example 'special' page. It contains a `public` folder which will be the output
-that native platforms will refer to
+This is an example 'special' page. It's designed to be a template for future pages.
+
+### Integration
+
+Serve the entire folder found under `build/<PLATFORM>/pages/example`
+
+### Platform Integration
+
+- On Windows, do x, y, z
+- On Android, do a, b, c
+
+---
+
+## Contributing
+
+### HTML
+The main HTML file is located at `public/index.html`. You can edit this file directly
+
+### CSS
+The main stylesheet is located at `public/style.css`. You can edit this file directly
+
+### Javascript
+JavaScript source files are located in the `src` directory. The build process will create a bundle and place it inside `public/generated`. 
+
+This is why the `index.html` file has the following `<script>` tag.
+
+```html
+<script type="module" src="generated/js/index.js"></script>
+```
+
+Don't edit the generated files directly - any changes you make will not be reflected in the final build output. 
+
+Instead, make your changes in `src/' and then run `npm run build.pages` from the `packages/special-pages` folder
+

packages/special-pages/readme.md

@@ -0,0 +1,15 @@
+## Architecture
+
+Special Pages gives us a single place to implement isolated HTML/CSS/Javascript projects that can be loaded into a web context that has privileged access to API.
+
+- `packages/special-pages/pages/example`
+- `packages/special-pages/pages/duckplayer`
+
+Would translate into the following build output
+
+- `build/apple/pages/example`
+- `build/apple/pages/duckplayer`
+- `build/windows/pages/example`
+- `build/windows/pages/duckplayer`
+
+This allows each respective platform to configure their integrations to use the known page.

typedoc.json

@@ -7,6 +7,7 @@
         "inject/mozilla.js",
         "inject/windows.js",
         "packages/messaging",
+        "packages/special-pages",
         "packages/special-pages/pages/example/src/index.js"
     ],
     "categoryOrder": [