feat: new docs structure (#20)

components/sidebar/index.tsx

@@ -29,10 +29,26 @@ const rootStyles = cva([
 const contentStyles = cva(["w-2/3"]);
 
 const Sidebar = ({ map, onPageEntryClick, className }: SidebarProps) => {
+    const meta = map[0].kind === "Meta" ? map[0] : undefined;
+
+    // This should never happen
+    if (!meta) return null;
+
+    const sortedMap: PageMapItem[] = [meta];
+    for (const childMeta of Object.keys(meta.data)) {
+        const foundChild = map.find((child) => {
+            const found =
+                (child.kind === "Folder" || child.kind === "MdxPage") &&
+                child.name === childMeta;
+            return found;
+        });
+        sortedMap.push(foundChild);
+    }
+
     return (
         <div className={rootStyles({ className: className?.root })}>
             <div className={contentStyles({ className: className?.content })}>
-                <Section map={map} onPageEntryClick={onPageEntryClick} />
+                <Section map={sortedMap} onPageEntryClick={onPageEntryClick} />
             </div>
         </div>
     );

pages/_meta.json

@@ -1,5 +1,7 @@
 {
-    "index": "Welcome",
-    "protocol": "Protocol",
-    "using-the-dapp": "Using the dapp"
+    "index": "Welcome to Carrot documentation",
+    "about-carrot": "About Carrot",
+    "carrot-protocol": "Carrot protocol",
+    "for-the-campaign-creators": "For the campaign creators",
+    "for-the-users": "For the users"
 }

pages/about-carrot/_meta.json

@@ -0,0 +1,10 @@
+{
+    "what-is-carrot": "What is Carrot?",
+    "how-does-carrot-work": "How does Carrot work?",
+    "technical-documentation": "Technical documentation",
+    "links-and-socials": "Links and socials",
+    "faq": "FAQ",
+    "carrot-dapp": "Carrot dapp",
+    "carrot-protocol": "Carrot protocol",
+    "carrot-templates": "Carrot templates"
+}

pages/carrot-protocol/_meta.json

@@ -0,0 +1,7 @@
+{
+    "introduction": "Introduction",
+    "how-does-carrot-work": "How does Carrot work?",
+    "what-are-templates": "What are templates?",
+    "what-are-kpi-token-templates": "What are KPI token templates?",
+    "what-are-oracle-templates": "What are oracle templates?"
+}

pages/carrot-protocol/how-does-carrot-work/_meta.json

@@ -0,0 +1,6 @@
+{
+    "index": "How does Carrot work?",
+    "what-are-goals-and-conditions": "What are goals and conditions?",
+    "what-is-a-collateral": "What is a collateral?",
+    "what-is-an-oracle": "What is an oracle?"
+}

pages/carrot-protocol/how-does-carrot-work/index.mdx

@@ -0,0 +1,38 @@
+---
+title: How does Carrot work
+subtitle: Exploring the Features of the Carrot Orchestrator
+---
+
+The Carrot Orchestrator, as the base Carrot dApp, enables users to interact with
+Carrot templates. It serves as an orchestrator for these templates, offering the
+following key pages:
+
+## Homepage
+
+The homepage of the orchestrator consists of three distinct sections:
+
+-   **Informative Video and Hero Section**: When no featured campaign is
+    present, the homepage showcases an explanatory video that highlights how
+    Carrot simplifies incentivization.
+-   **Featured Campaigns**: At times, the Carrot team may feature campaigns from
+    partners, which will be prominently displayed at the top of the homepage.
+-   **Latest Campaigns**: The subsequent section presents the five most recent
+    campaigns. These listings are continually updated, providing a quick
+    overview of ongoing activities in the Carrot ecosystem.
+-   **KPI Token Templates**: This section offers a selection of KPI token
+    templates that allow users to create campaigns. Note that the availability
+    of this section depends on whether multiple templates are deployed on the
+    network. If only one template is deployed, the section will not be visible
+    by default.
+
+## Campaigns Page
+
+The campaigns page provides a user-friendly interface to browse through created
+campaigns. Users can optionally filter campaigns by state (active, expired, or
+finalized) or search for specific text. Additionally, campaigns can be sorted in
+ascending or descending order based on their creation dates.
+
+These two main pages form the core functionality of the Carrot Orchestrator. The
+subsequent sections will delve into the details of interacting with the official
+first-party Carrot templates, which users typically engage with the most on the
+Carrot dApp.

pages/carrot-protocol/what-are-kpi-token-templates/_meta.json

@@ -0,0 +1,5 @@
+{
+    "index": "What are KPI token templates",
+    "erc20-kpi-token-template": "ERC20 KPI token template",
+    "creating-your-own-kpi-token-template": "Creating your own KPI token template"
+}

pages/carrot-protocol/what-are-kpi-token-templates/index.mdx

@@ -0,0 +1,38 @@
+---
+title: What are KPI token templates
+subtitle: Exploring the Features of the Carrot Orchestrator
+---
+
+The Carrot Orchestrator, as the base Carrot dApp, enables users to interact with
+Carrot templates. It serves as an orchestrator for these templates, offering the
+following key pages:
+
+## Homepage
+
+The homepage of the orchestrator consists of three distinct sections:
+
+-   **Informative Video and Hero Section**: When no featured campaign is
+    present, the homepage showcases an explanatory video that highlights how
+    Carrot simplifies incentivization.
+-   **Featured Campaigns**: At times, the Carrot team may feature campaigns from
+    partners, which will be prominently displayed at the top of the homepage.
+-   **Latest Campaigns**: The subsequent section presents the five most recent
+    campaigns. These listings are continually updated, providing a quick
+    overview of ongoing activities in the Carrot ecosystem.
+-   **KPI Token Templates**: This section offers a selection of KPI token
+    templates that allow users to create campaigns. Note that the availability
+    of this section depends on whether multiple templates are deployed on the
+    network. If only one template is deployed, the section will not be visible
+    by default.
+
+## Campaigns Page
+
+The campaigns page provides a user-friendly interface to browse through created
+campaigns. Users can optionally filter campaigns by state (active, expired, or
+finalized) or search for specific text. Additionally, campaigns can be sorted in
+ascending or descending order based on their creation dates.
+
+These two main pages form the core functionality of the Carrot Orchestrator. The
+subsequent sections will delve into the details of interacting with the official
+first-party Carrot templates, which users typically engage with the most on the
+Carrot dApp.

pages/carrot-protocol/what-are-templates.mdx

@@ -0,0 +1,37 @@
+---
+subtitle: Exploring the Features of the Carrot Orchestrator
+---
+
+The Carrot Orchestrator, as the base Carrot dApp, enables users to interact with
+Carrot templates. It serves as an orchestrator for these templates, offering the
+following key pages:
+
+## Homepage
+
+The homepage of the orchestrator consists of three distinct sections:
+
+-   **Informative Video and Hero Section**: When no featured campaign is
+    present, the homepage showcases an explanatory video that highlights how
+    Carrot simplifies incentivization.
+-   **Featured Campaigns**: At times, the Carrot team may feature campaigns from
+    partners, which will be prominently displayed at the top of the homepage.
+-   **Latest Campaigns**: The subsequent section presents the five most recent
+    campaigns. These listings are continually updated, providing a quick
+    overview of ongoing activities in the Carrot ecosystem.
+-   **KPI Token Templates**: This section offers a selection of KPI token
+    templates that allow users to create campaigns. Note that the availability
+    of this section depends on whether multiple templates are deployed on the
+    network. If only one template is deployed, the section will not be visible
+    by default.
+
+## Campaigns Page
+
+The campaigns page provides a user-friendly interface to browse through created
+campaigns. Users can optionally filter campaigns by state (active, expired, or
+finalized) or search for specific text. Additionally, campaigns can be sorted in
+ascending or descending order based on their creation dates.
+
+These two main pages form the core functionality of the Carrot Orchestrator. The
+subsequent sections will delve into the details of interacting with the official
+first-party Carrot templates, which users typically engage with the most on the
+Carrot dApp.

pages/for-the-campaign-creators/_meta.json

@@ -0,0 +1,4 @@
+{
+    "benefits-of-using-carrot": "Benefits of using Carrot",
+    "how-to-create-a-campaign": "How to create a campaign?"
+}

pages/for-the-campaign-creators/benefits-of-using-carrot.mdx

@@ -0,0 +1,34 @@
+---
+subtitle: Get started with Carrot and what it's all about.
+---
+
+Carrot is a platform that enables flexible and efficient incentivization,
+rewarding what really matters to you in a capital efficient way. Whether you're
+a protocol or a single user, if you need to reach a goal by incentivizing a
+certain behavior, Carrot can help.
+
+## How it works
+
+Incentivization in Carrot is enabled through what we call **KPI token
+campaigns**. At a high level, **KPI token campaigns** are made up of the
+following concepts:
+
+-   **Goal**: each KPI token campaign defines a goal to be reached and for which
+    efficient incentivization is needed.
+-   **Condition**: the goal needs to be turned into a condition so that Carrot
+    can correctly assess if it was reached or not. This is a simple step that
+    will be described in more details later in the documentation.
+-   **Collateral(s)**: collaterals are the rewards given out to the campaign
+    participants if the goal is reached. Logic related to collateral(s)
+    unlocking is template-specific (the concept of templates is addressed later
+    in the docs).
+-   **KPI tokens**: KPI tokens represent a claim to all or part of the
+    collateral whenever the goal is either fully reached or partially reached.
+-   **Oracle(s)**: oracles are used in Carrot to relay condition outcomes
+    on-chain from the real world once they are known, allowing for the
+    finalization of the KPI token campaign.
+
+Some of these concepts are on-chain entities and implemented through the use of
+templates, which enables Carrot to be extremely flexible in implementing
+incentivization strategies that work great for every possible use case. The
+concept of templates is expanded in the next section.

pages/for-the-campaign-creators/how-to-create-a-campaign.mdx

@@ -0,0 +1,16 @@
+---
+title: KPI tokens
+subtitle: KPI tokens implement incentivization strategies.
+---
+
+KPI tokens and their templates are the main piece of logic in Carrot, the ones
+that have full control over the incentivization strategies.
+
+They represent on-chain the condition that the user wants to incentivize and the
+collateral(s) it can take. They have attached oracles that relay information to
+them regarding condition outcomes.
+
+Based on these outcomes, they can freely decide what to do about the
+collateral(s) and where to allocate it.
+
+In this sense, KPI tokens are the heart of any KPI token campaign.

pages/for-the-users/_meta.json

@@ -0,0 +1,4 @@
+{
+    "what-is-a-carrot-token": "What is a Carrot token?",
+    "how-to-redeem-the-collateral": "How to redeem the collateral?"
+}

pages/for-the-users/how-to-redeem-the-collateral.mdx

@@ -0,0 +1,16 @@
+---
+title: KPI tokens
+subtitle: KPI tokens implement incentivization strategies.
+---
+
+KPI tokens and their templates are the main piece of logic in Carrot, the ones
+that have full control over the incentivization strategies.
+
+They represent on-chain the condition that the user wants to incentivize and the
+collateral(s) it can take. They have attached oracles that relay information to
+them regarding condition outcomes.
+
+Based on these outcomes, they can freely decide what to do about the
+collateral(s) and where to allocate it.
+
+In this sense, KPI tokens are the heart of any KPI token campaign.

pages/for-the-users/what-is-a-carrot-token.mdx

@@ -0,0 +1,34 @@
+---
+subtitle: Get started with Carrot and what it's all about.
+---
+
+Carrot is a platform that enables flexible and efficient incentivization,
+rewarding what really matters to you in a capital efficient way. Whether you're
+a protocol or a single user, if you need to reach a goal by incentivizing a
+certain behavior, Carrot can help.
+
+## How it works
+
+Incentivization in Carrot is enabled through what we call **KPI token
+campaigns**. At a high level, **KPI token campaigns** are made up of the
+following concepts:
+
+-   **Goal**: each KPI token campaign defines a goal to be reached and for which
+    efficient incentivization is needed.
+-   **Condition**: the goal needs to be turned into a condition so that Carrot
+    can correctly assess if it was reached or not. This is a simple step that
+    will be described in more details later in the documentation.
+-   **Collateral(s)**: collaterals are the rewards given out to the campaign
+    participants if the goal is reached. Logic related to collateral(s)
+    unlocking is template-specific (the concept of templates is addressed later
+    in the docs).
+-   **KPI tokens**: KPI tokens represent a claim to all or part of the
+    collateral whenever the goal is either fully reached or partially reached.
+-   **Oracle(s)**: oracles are used in Carrot to relay condition outcomes
+    on-chain from the real world once they are known, allowing for the
+    finalization of the KPI token campaign.
+
+Some of these concepts are on-chain entities and implemented through the use of
+templates, which enables Carrot to be extremely flexible in implementing
+incentivization strategies that work great for every possible use case. The
+concept of templates is expanded in the next section.

pages/index.mdx

@@ -1,5 +1,5 @@
 ---
-title: Welcome
+title: Welcome to Carrot documentation
 subtitle:
     Learn how the Carrot protocol makes tokenized incentivization possible.
 ---