docs: key concepts

.vitepress/config.js

@@ -78,36 +78,40 @@ export default defineConfig({
             ],
             "/docs": [
                 {
-                    text: "Guide",
+                    text: "Quick Start Guide",
                     items: [
                         {
-                            text: "Tutorial - Publisher",
+                            text: "For Publisher",
                             link: "/docs/tutorial/publisher.md"
                         },
                         {
-                            text: "Tutorial - Creative",
+                            text: "For Creative",
                             link: "/docs/tutorial/creative.md"
                         }
                     ]
                 },
                 {
-                    text: "Formats",
+                    text: "Key Concepts",
                     items: [
                         {
-                            text: "Topscroll",
-                            link: "/docs/formats/topscroll.md"
+                            text: "Formats",
+                            link: "/docs/concepts/formats.md"
                         },
                         {
-                            text: "Midscroll",
-                            link: "/docs/formats/midscroll.md"
+                            text: "Integration",
+                            link: "/docs/concepts/integration.md"
                         },
                         {
-                            text: "Double Midscroll",
-                            link: "/docs/formats/double_midscroll.md"
+                            text: "Wrapper",
+                            link: "/docs/concepts/wrapper.md"
                         },
                         {
-                            text: "Welcome Page",
-                            link: "/docs/formats/welcome_page.md"
+                            text: "UI Layer",
+                            link: "/docs/concepts/ui-layer.md"
+                        },
+                        {
+                            text: "Creative",
+                            link: "/docs/concepts/creative.md"
                         }
                     ]
                 },

.vitepress/theme/custom.css

@@ -73,4 +73,20 @@ code.nav {
 
 .docs .VPDoc {
     padding-top: 0;
+}
+
+img[alt="light"] {
+    display: block;
+}
+
+img[alt="dark"] {
+    display: none;
+}
+
+html.dark img[alt="light"] {
+    display: none;
+}
+
+html.dark img[alt="dark"] {
+    display: block;
 }

README.md

@@ -22,9 +22,9 @@
 <p align="center">
     <a href="" target="blank">View Demo</a>
     ·
-    <a href="./issues/new/choose">Report Bug</a>
+    <a href="https://github.com/madington/advantage/issues/new/choose">Report Bug</a>
     ·
-    <a href="./issues/new/choose">Request Feature</a>
+    <a href="https://github.com/madington/advantage/issues/new/choose">Request Feature</a>
 </p>
 
 `Advantage` revolutionizes the way site owners integrate with high impact formats by providing a flexible, customizable unified API. Unlike traditional integrations that offer a one-size-fits-all solution, AdVantage empowers you to tailor the interaction between you site and high impact formats, ensuring a perfect fit for your specific needs.

www/about/faq.md

@@ -0,0 +1,17 @@
+# FAQ
+
+<details>
+<summary>Why open source?</summary>
+
+The idea behind this is to give you ownership and control over the code, allowing you to decide how the integration are built and styled.
+
+Start with some sensible defaults, then customize the integration to your needs.
+
+One of the drawback is that the style is coupled with the implementation. The design of your formats should be separate from their implementation.
+
+</details>
+
+<details>
+<summary>Which frameworks are supported?</summary>
+AdVantage components are self-maintaining, they work with any other framework or components library. Or none at all!
+</details>

www/docs/concepts/creative.md

@@ -0,0 +1,19 @@
+---
+pageClass: docs
+---
+
+<p class="text-sm text-slate-500"><code>Docs > Key Concepts</code></p>
+
+# Creative
+
+The interaction between a creative (the advertisement content itself) and an [Format](formats.md) on publisher sites, is a nuanced process that enables dynamic, efficient, and standardize process.
+
+AdVantage utilize a messaging protocol for managing ad interactions in a secure container. AdVantage and the creative communicate by excanging asynchronous signals that maintain a custom messaging protocol. In the most simplistic overview of how it works, the steps are as follows:
+
+1. <code>[pre-AdVantage]</code> an ad is matched and delivered to a webpages placement.
+2. Once in a state to receive information, the creative informs AdVantage that it is ready to receive initialization information.
+3. AdVantage initializes and provides the creative with a `init` message.
+4. Creative executes, using messaging protocol to request and resive data and event about resize, close event, scroll event etc.
+
+![dark](/message-dark.png)
+![light](/message-light.png)

www/docs/concepts/formats.md

@@ -0,0 +1,41 @@
+---
+pageClass: docs
+---
+
+<p class="text-sm text-slate-500"><code>Docs > Key Concepts</code></p>
+
+# Formats
+
+Formats are predefined templates or structures that describe the visual and functional aspects of an advertisement.
+
+Formats focus on:
+
+-   **Visual Presentation:** Outline the aesthetic aspects, such as dimensions, animations, and interactive elements.
+-   **Behavioral Functionality**: Describe how the ad behaves in different contexts, like animation on scroll or responsiveness to user interactions.
+-   **Content Structure:** Define how content is organized and displayed within the format, ensuring consistency across different implementations.
+
+Formats in Advantage are essentially a definition of how an ad looks and behaves; Such as animation on scroll. The format offer a standardized interface that allows it to be initialized, displayed, and otherwise manipulated by the integration code.
+
+## Welcome Page
+
+An impactful format that welcomes users with swift and wide reach. Positioned on top of the site content with a close button to continue to the site offers ample creative freedom, allowing for work with high-resolution materials to ensure a high-quality experience and excellent outcomes.
+
+<span class="inline-flex items-center rounded-md bg-gray-50 px-2 py-1 text-xs font-medium text-gray-600 ring-1 ring-inset ring-gray-500/10">Width 100%</span> <span class="inline-flex items-center rounded-md bg-gray-50 px-2 py-1 text-xs font-medium text-gray-600 ring-1 ring-inset ring-gray-500/10">Height: 100%</span> <span class="inline-flex items-center rounded-md bg-green-50 px-2 py-1 text-xs font-medium text-green-700 ring-1 ring-inset ring-green-600/20">Close Button</span> <span class="inline-flex items-center rounded-md bg-pink-50 px-2 py-1 text-xs font-medium text-pink-700 ring-1 ring-inset ring-pink-700/10">Scroll Down Arrow</span>
+
+## Topscroll
+
+The Topscroll is the first users see, making it perfect as a branding format. Positioned at the top of the site, it fills the screen to 70%. This format features a scrolling effect, providing an elegant transition into the site as the user scrolls down.
+
+<span class="inline-flex items-center rounded-md bg-gray-50 px-2 py-1 text-xs font-medium text-gray-600 ring-1 ring-inset ring-gray-500/10">Width 100%</span> <span class="inline-flex items-center rounded-md bg-gray-50 px-2 py-1 text-xs font-medium text-gray-600 ring-1 ring-inset ring-gray-500/10">Height: 70%</span> <span class="inline-flex items-center rounded-md bg-blue-50 px-2 py-1 text-xs font-medium text-blue-700 ring-1 ring-inset ring-blue-700/10">Parallax Scrolling</span> <span class="inline-flex items-center rounded-md bg-green-50 px-2 py-1 text-xs font-medium text-green-700 ring-1 ring-inset ring-green-600/20">Close Button</span> <span class="inline-flex items-center rounded-md bg-pink-50 px-2 py-1 text-xs font-medium text-pink-700 ring-1 ring-inset ring-pink-700/10">Scroll Down Arrow</span>
+
+## Midscroll
+
+Midscroll format is defined by its appearance (taking 100% width and height of the viewport) and behavior (content is fixed with a clip path creating a parallax scrolling illusion).
+
+<span class="inline-flex items-center rounded-md bg-gray-50 px-2 py-1 text-xs font-medium text-gray-600 ring-1 ring-inset ring-gray-500/10">Width 100%</span> <span class="inline-flex items-center rounded-md bg-gray-50 px-2 py-1 text-xs font-medium text-gray-600 ring-1 ring-inset ring-gray-500/10">Height: 100%</span> <span class="inline-flex items-center rounded-md bg-blue-50 px-2 py-1 text-xs font-medium text-blue-700 ring-1 ring-inset ring-blue-700/10">Parallax Scrolling</span>
+
+## Double Midscroll
+
+The Double Midscroll is a responsive, high-impact format that provides a natural presentation of your message through an intuitive and user-friendly scrolling experience. This format becomes visible when the user scrolls past the content and remains visible until the scrolling distance reaches twice the height of the window.
+
+<span class="inline-flex items-center rounded-md bg-gray-50 px-2 py-1 text-xs font-medium text-gray-600 ring-1 ring-inset ring-gray-500/10">Width 100%</span> <span class="inline-flex items-center rounded-md bg-gray-50 px-2 py-1 text-xs font-medium text-gray-600 ring-1 ring-inset ring-gray-500/10">Height: 200%</span> <span class="inline-flex items-center rounded-md bg-blue-50 px-2 py-1 text-xs font-medium text-blue-700 ring-1 ring-inset ring-blue-700/10">Parallax Scrolling</span>

www/docs/concepts/integration.md

@@ -0,0 +1,11 @@
+---
+pageClass: docs
+---
+
+<p class="text-sm text-slate-500"><code>Docs > Key Concepts</code></p>
+
+# Integrations
+
+Integrations specify how a webpage incorporates an ad [format](./formats.md). This involves scripting and configuration that dictate where and how an ad format is displayed within the page. Integrations are responsible page-specific adjustments, such as modifying ad behavior or appearance to better fit the page's context without altering the base format.
+
+Each integration represents the connection between page and format (like Midscroll or Welcome page). Integration are either provided by AdVantage as templates or implemented by you.

www/docs/concepts/ui-layer.md

@@ -0,0 +1,16 @@
+---
+pageClass: docs
+---
+
+<p class="text-sm text-slate-500"><code>Docs > Key Concepts</code></p>
+
+# UI-Layer
+
+The UI Layer offers publishers a suite of tools and options to modify the look and feel of the [formats](formats.md). This includes the ability to change fonts, colors, sizes, and positions of various elements within an ad format.
+
+This layer serves as the interface between the ad content and the user, allowing for adjustments in visual elements to enhance user engagement and the effectiveness of the ads displayed.
+
+![dark](/ui-dark.png)
+![light](/ui-light.png)
+
+In summary, the UI Layer within AdVantage offers publishers a powerful tool to tailor the visual and interactive aspects of the formats to fit the unique style and user experience standards of their websites. By leveraging these customization capabilities, publishers can enhance ad effectiveness, improve user satisfaction, and maintain the aesthetic integrity of their digital properties.

www/docs/concepts/wrapper.md

@@ -0,0 +1,13 @@
+---
+pageClass: docs
+---
+
+<p class="text-sm text-slate-500"><code>Docs > Key Concepts</code></p>
+
+# Wrapper
+
+The Wrapper is a web component that acts as a container or placeholder for ad placements on a webpage. It's designed to securely and efficiently load the designated [format](formats.md) into the page's content, ensuring that ads are displayed in the intended manner without disrupting the user experience or site layout.
+
+<div class="tip custom-block" style="padding-top: 8px">
+  ℹ️ Using the Advantage Wrapper is highly recommended as it makes implementing Advantage high-impact formats on your website quick and easy. But if you already have custom implementations of the formats that you want, you can choose not to use the wrapper.
+</div>