docs(site): setup getting started page and enable algola search

Collektive · Oct 21, 2024 · ef5c55e · ef5c55e
1 parent a79364a
commit ef5c55e
Show file tree

Hide file tree

Showing 10 changed files with 273 additions and 111 deletions.
diff --git a/site/docs/about/_category_.json b/site/docs/about/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "About",
-  "position": 1,
+  "position": 100,
   "link": {
     "type": "generated-index",
     "description": "TODO"

diff --git a/site/docs/explanation/_category_.json b/site/docs/explanation/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "Explanation",
-  "position": 5,
+  "position": 50,
   "link": {
     "type": "generated-index",
     "description": "TODO"

diff --git a/site/docs/getting-started.mdx b/site/docs/getting-started.mdx
@@ -0,0 +1,79 @@
+---
+sidebar_position: 1
+sidebar_label: Getting Started
+id: gettingstarted
+title: Getting Started
+---
+
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+**Collektive** is composed of several independent components:
+
+- The core _DSL_ (Domain Specific Language) defining the language syntax and semantics.
+- The _compiler plugin_ used to automatically devise the communication protocol based on the program's structure.
+- The _stdlib_ (Standard Library) providing common functionalities and data structures.
+
+## Compiler plugin setup
+
+To use **Collektive** in your project, first add the **compiler plugin** to your `build.gradle.kts` file:
+
+```kotlin
+plugins {
+    kotlin("multiplatform") version "<kotlin_version>"
+    id("it.unibo.collektive.collektive-plugin") version "<latest version>"
+}
+```
+
+:::danger
+The **compiler plugin** it's a mandatory component of the **Collektive** ecosystem. It is used to automatically devise
+the
+communication protocol based on the program's structure.
+
+Without this plugin, the program will **NOT** run as expected at runtime.
+:::
+
+## Dependencies setup
+To start you app development, add the `dsl` and (optionally) the `stdlib` dependencies to your `build.gradle.kts` file:
+
+<Tabs>
+<TabItem value="multiplatform" label="Multiplatform">
+
+```kotlin
+kotlin {
+    jvm()
+    js()
+    ...
+    sourceSets {
+        val commonMain by getting {
+            dependencies {
+                implementation("it.unibo.collektive:dsl:<latest version>")
+                implementation("it.unibo.collektive:stdlib:<latest version>")
+            }
+        }
+    }
+}
+```
+
+</TabItem>
+<TabItem value="jvm" label="JVM only">
+
+```kotlin
+dependencies {
+    implementation("it.unibo.collektive:dsl:<latest version>")
+    implementation("it.unibo.collektive:stdlib:<latest version>")
+}
+```
+
+</TabItem>
+</Tabs>
+
+:::tip[**Collektive** :heart: Kotlin Multiplatform]
+
+**Collektive** supports [KMP](https://kotlinlang.org/docs/multiplatform-intro.html) (Kotlin Multiplatform) projects, allowing you to use the DSL in Native, JS, and JVM environments.       
+Currently, the following platforms are supported:
+- **JVM**
+- **JS** (node.js and browser)
+- **Native** (iOS, macOS, Linux, Windows)
+:::
diff --git a/site/docs/how-to-guide/_category_.json b/site/docs/how-to-guide/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "How To Guide",
-  "position": 4,
+  "position": 40,
   "link": {
     "type": "generated-index",
     "description": "TODO"

diff --git a/site/docs/intro.md b/site/docs/intro.md
@@ -2,6 +2,6 @@
 sidebar_position: 0
 ---
 
-# Collektive Intro
+# Collektive Introduction
 
 todo
diff --git a/site/docs/introduction/_category_.json b/site/docs/introduction/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "Introduction",
-  "position": 2,
+  "position": 20,
   "link": {
     "type": "generated-index",
     "description": "TODO"

diff --git a/site/docs/reference-guides/_category_.json b/site/docs/reference-guides/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "Reference",
-  "position": 6,
+  "position": 60,
   "link": {
     "type": "generated-index",
     "description": "TODO"

diff --git a/site/docs/tutorials/_category_.json b/site/docs/tutorials/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "Tutorial",
-  "position": 7,
+  "position": 70,
   "link": {
     "type": "generated-index",
     "description": "TODO"

diff --git a/site/docusaurus.config.ts b/site/docusaurus.config.ts
@@ -3,102 +3,170 @@ import type {Config} from '@docusaurus/types';
 import type * as Preset from '@docusaurus/preset-classic';
 
 const config: Config = {
-  title: 'Collektive',
-  tagline: 'Aggregate Computing in Kotlin Multiplatform',
-  favicon: 'img/favicon.ico',
+    title: 'Collektive',
+    tagline: 'Aggregate Computing in Kotlin Multiplatform',
+    favicon: 'img/collektive-logo.svg',
 
-  // Set the production url of your site here
-  url: 'https://collektive.github.io',
-  // Set the /<baseUrl>/ pathname under which your site is served
-  // For GitHub pages deployment, it is often '/<projectName>/'
-  baseUrl: '/',
+    // Set the production url of your site here
+    url: 'https://collektive.github.io',
+    // Set the /<baseUrl>/ pathname under which your site is served
+    // For GitHub pages deployment, it is often '/<projectName>/'
+    baseUrl: '/',
+    trailingSlash: true,
 
-  // GitHub pages deployment config.
-  // If you aren't using GitHub pages, you don't need these.
-  organizationName: 'Collektive', // Usually your GitHub org/user name.
-  projectName: 'collektive', // Usually your repo name.
+    // GitHub pages deployment config.
+    // If you aren't using GitHub pages, you don't need these.
+    organizationName: 'Collektive', // Usually your GitHub org/user name.
+    projectName: 'collektive', // Usually your repo name.
 
-  onBrokenLinks: 'throw',
-  onBrokenMarkdownLinks: 'warn',
+    onBrokenLinks: 'throw',
+    onBrokenMarkdownLinks: 'warn',
 
-  // Even if you don't use internationalization, you can use this field to set
-  // useful metadata like html lang. For example, if your site is Chinese, you
-  // may want to replace "en" with "zh-Hans".
-  i18n: {
-    defaultLocale: 'en',
-    locales: ['en'],
-  },
+    // Even if you don't use internationalization, you can use this field to set
+    // useful metadata like html lang. For example, if your site is Chinese, you
+    // may want to replace "en" with "zh-Hans".
+    i18n: {
+        defaultLocale: 'en',
+        locales: ['en'],
+    },
 
-  presets: [
-    [
-      'classic',
-      {
-        docs: {
-          sidebarPath: './sidebars.ts',
-          // Please change this to your repo.
-          // Remove this to remove the "edit this page" links.
-          editUrl:
-            'https://github.com/Collektive/collektive/tree/main/site/docs/',
-        },
-        theme: {
-          customCss: './src/css/custom.css',
-        },
-      } satisfies Preset.Options,
+    presets: [
+        [
+            'classic',
+            {
+                docs: {
+                    sidebarPath: './sidebars.ts',
+                    // Please change this to your repo.
+                    // Remove this to remove the "edit this page" links.
+                    editUrl:
+                        'https://github.com/Collektive/collektive/tree/master/site/',
+                },
+                theme: {
+                    customCss: './src/css/custom.css',
+                },
+            } satisfies Preset.Options,
+        ],
     ],
-  ],
 
-  themeConfig: {
-    // Replace with your project's social card
-    image: 'img/collektive-logo.svg',
-    navbar: {
-      title: 'Collektive',
-      logo: {
-        alt: 'Collektive Logo',
-        src: 'img/collektive-logo.svg',
-      },
-      items: [
-        {
-          type: 'docSidebar',
-          sidebarId: 'tutorialSidebar',
-          position: 'left',
-          label: 'Documentation',
+    themeConfig: {
+        algolia: {
+            // The application ID provided by Algolia
+            appId: 'O0DP3M3LFT',
+
+            // Public API key: it is safe to commit it
+            apiKey: 'f0a3080f40caf6df450ca01ffb60b601',
+
+            indexName: 'collektive',
+
+            // Optional: see doc section below
+            contextualSearch: true,
+
+            // Optional: Replace parts of the item URLs from Algolia. Useful when using the same search index for multiple deployments using a different baseUrl. You can use regexp or string in the `from` param. For example: localhost:3000 vs myCompany.com/docs
+            replaceSearchResultPathname: {
+                from: '/docs/', // or as RegExp: /\/docs\//
+                to: '/',
+            },
+
         },
-        {
-          href: 'https://github.com/Collektive/collektive',
-          label: 'GitHub',
-          position: 'right',
+        // Replace with your project's social card
+        image: 'img/collektive-logo.svg',
+        navbar: {
+            title: 'Collektive',
+            logo: {
+                alt: 'Collektive Logo',
+                src: 'img/collektive-logo.svg',
+            },
+            items: [
+                {
+                    type: 'doc',
+                    position: 'left',
+                    docId: 'intro',
+                    label: 'Docs',
+                },
+                {
+                    type: 'dropdown',
+                    label: 'APIs',
+                    position: 'left',
+                    items: [
+                        {
+                            label: 'dsl',
+                            href: 'https://javadoc.io/doc/it.unibo.collektive/dsl/latest/index.html',
+                        },
+                        {
+                            label: 'stdlib',
+                            href: 'https://javadoc.io/doc/it.unibo.collektive/stdlib/latest/index.html',
+                        },
+                    ],
+                },
+                {
+                    type: 'search',
+                    position: 'right',
+                },
+                {
+                    href: 'https://github.com/Collektive/collektive',
+                    className: 'header-github-link',
+                    'aria-label': 'GitHub repository',
+                    position: 'right',
+                },
+            ],
         },
-      ],
-    },
-    footer: {
-      style: 'dark',
-      links: [
-        {
-          title: 'Docs',
-          items: [
+        footer: {
+            style: 'dark',
+            links: [
+                {
+                    title: 'Docs',
+                    items: [
+                        {
+                            label: 'Getting Started',
+                            to: '/docs/intro',
+                        },
+                    ],
+                },
+                {
+                    title: 'More',
+                    items: [
+                        {
+                            label: 'GitHub',
+                            href: 'https://github.com/Collektive/collektive',
+                        },
+                    ],
+                },
+            ],
+            copyright: `Copyright © ${new Date().getFullYear()} Collektive, Org. Built with Docusaurus.`,
+        },
+        prism: {
+            theme: prismThemes.github,
+            darkTheme: prismThemes.dracula,
+        },
+        metadata: [
+            {name: 'keywords', content: 'cooking, blog'},
+            {name: 'twitter:card', content: 'summary_large_image'},
+        ],
+        headTags: [
+            // Declare a <link> preconnect tag
             {
-              label: 'Getting Started',
-              to: '/docs/intro',
+                tagName: 'link',
+                attributes: {
+                    rel: 'preconnect',
+                    href: 'https://collektive.github.io',
+                },
             },
-          ],
-        },
-        {
-          title: 'More',
-          items: [
+            // Declare some json-ld structured data
             {
-              label: 'GitHub',
-              href: 'https://github.com/Collektive/collektive',
+                tagName: 'script',
+                attributes: {
+                    type: 'application/ld+json',
+                },
+                innerHTML: JSON.stringify({
+                    '@context': 'https://schema.org/',
+                    '@type': 'Organization',
+                    name: 'Collektive Org.',
+                    url: 'https://collektive.github.io/',
+                    logo: 'https://collective.github.io/img/collektive-logo.svg',
+                }),
             },
-          ],
-        },
-      ],
-      copyright: `Copyright © ${new Date().getFullYear()} Collektive, Org. Built with Docusaurus.`,
-    },
-    prism: {
-      theme: prismThemes.github,
-      darkTheme: prismThemes.dracula,
-    },
-  } satisfies Preset.ThemeConfig,
+        ],
+    } satisfies Preset.ThemeConfig,
 };
 
 export default config;