DOCS-876: Use instantsearch and typesense for tutorials page (#1693)

.github/workflows/docs.yml

@@ -28,14 +28,14 @@ jobs:
         uses: actions/configure-pages@v2
 
       - name: Setup Hugo
-        uses: peaceiris/actions-hugo@v2 
+        uses: peaceiris/actions-hugo@v2
         with:
           hugo-version: 'latest'
           extended: true
-          
+
       - name: Build
         run: make build-prod
-        
+
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v1
         with:
@@ -52,7 +52,7 @@ jobs:
         id: deployment
         uses: actions/deploy-pages@v1
 
-  generate-index:
+  generate-index-and-tutorials-collection:
     needs: build
     if: github.repository_owner == 'viamrobotics'
     runs-on: [self-hosted, x64]
@@ -74,5 +74,13 @@ jobs:
           echo TYPESENSE_PORT=443 >> typesense.env
           echo TYPESENSE_PROTOCOL=https >> typesense.env
 
+      - name: Upload tutorials documents
+        run: |
+          jq -c '.[]' ./public/tutorials/typesense.json > documents.jsonl
+          curl -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
+          -X POST \
+          -T documents.jsonl \
+          "https://cgnvrk0xwyj9576lp-1.a1.typesense.net/collections/tutorials/documents/import?action=upsert"
+
       - name: Index
         run:  docker run --env-file=typesense.env -e "CONFIG=$(cat docsearch.json)" typesense/docsearch-scraper

.htmltest.yml

@@ -22,6 +22,7 @@ IgnoreURLs:
 - "slamtec.com"
 - "softroboticsinc.com"
 - "universal-robots.com"
+- "digikey.com"
 - "ufactory.cc"
 IgnoreDirs:
 - "lib"

assets/scss/_styles_project.scss

@@ -562,10 +562,12 @@ END MARKETING CSS
 .hover-card.tutorial {
   background-color: white;
   padding: 10px;
+  margin: 1rem 0.8rem 1rem 0.2rem;
 }
 
 .hover-card.tutorial > a {
   width: 100%;
+  text-decoration: none;
 }
 
 // Text is black
@@ -644,6 +646,11 @@ END MARKETING CSS
  font-weight: 400 !important;
 }
 
+.hover-card.tutorial * .pills > .pill.pill-highlight {
+  background-color: #000;
+  color: white;
+}
+
 .hover-card.tutorial * .pill.pill-lang {
   border-color: #00e8e8;
 }
@@ -1130,3 +1137,158 @@ ul.sectionlist > li:hover {
   padding: 0;
   font-size: 30px;
 }
+
+.td-sidebar__toggle {
+  float: right;
+}
+
+// Tutorials page start
+
+.search-panel__results.card-container {
+  max-width: 100%;
+}
+
+#tutorial-menu {
+  display: flex;
+  flex-direction: column;
+  max-width: 600px;
+}
+
+#tutorial-filters, #tutorial-filter-items {
+  display: flex;
+  flex-wrap: wrap;
+}
+
+#tutorial-filters > .filter {
+  text-decoration: none;
+  color: black;
+  padding: 0.2rem 1rem;
+  margin: 0.2rem;
+  border: 1px solid black;
+}
+
+.ais-Hits-item {
+  display: flex;
+}
+
+#hits .ais-Hits-list {
+  list-style-type: none;
+  display: flex;
+  flex-wrap: wrap;
+  width: 100%;
+}
+
+.search-panel__filters {
+  display: flex;
+}
+
+.search-facets {
+  width: 100%;
+  border: 1px solid black;
+  margin: 0.2rem;
+  padding: 0.2rem;
+}
+
+.search-facets > ul {
+  display: flex;
+  flex-wrap: wrap;
+  margin: 0.2rem;
+  padding: 0;
+}
+
+.search-facets * li {
+  list-style: none;
+  margin: 0.2rem
+}
+
+.search-facets * label {
+  margin: 0;
+}
+
+.search-facets * input {
+  padding: 0.1rem 0.25rem;
+  border: 1px solid black;
+  margin: 0.1rem;
+  font-size: 0.833rem !important;
+  font-weight: 400 !important;
+  line-height: 1.4375em;
+  background-color: whitesmoke;
+}
+
+.search-facets * input.refined {
+  background-color: #000;
+  color: white;
+}
+
+#components-list * input,
+#services-list * input {
+  border-color: #a51aff;
+}
+
+#languages-list * input {
+  border-color: #00e8e8;
+}
+
+.ais-Hits-list {
+  padding: 0;
+}
+
+// Pagination CSS start
+
+#pagination {
+  margin: 2rem auto;
+}
+
+.ais-Pagination-item {
+  display: inline-block;
+}
+
+span.ais-Pagination-link {
+  background-color: #e7e5e4;
+}
+
+.ais-Pagination-item.ais-Pagination-item--selected > a.ais-Pagination-link {
+  background-color: #000;
+  color: white;
+}
+
+.ais-Pagination-link {
+  text-decoration: none;
+  color: black;
+  padding: 0.2rem 1rem;
+  margin: 0 0.2rem;
+  border: 1px solid black;
+}
+
+a.ais-Pagination-link:hover {
+  color: black;
+  background-color: #e7e5e4;
+}
+
+.ais-Pagination-list {
+  text-align: center;
+  padding: 0;
+}
+// Pagination CSS end
+
+// Tutorials page end
+
+// Search-autocomplete start
+
+.algolia-autocomplete {
+  flex-grow: 1;
+}
+
+// Search-autocomplete end
+
+// Make videos work without js
+
+.no-js * .lozad {
+  display: none;
+}
+
+// ensure tutorials page is 100% of height
+
+.row.flex-xl-nowrap {
+  min-height: 100%;
+}

config.toml

@@ -48,7 +48,13 @@ weight = 1
     codeFences = true
 
 [outputs]
-section = ["HTML"]
+section = ["HTML", "Typesense"]
+
+[outputFormats.Typesense]
+baseName = "typesense"
+isPlainText = true
+mediaType = "application/json"
+notAlternative = true
 
 [params]
 copyright = "Viam, Inc. - Documentation is licensed under Creative Commons ShareAlike License. "

docs/tutorials/_index.md

@@ -3,6 +3,7 @@ title: "Tutorials"
 linkTitle: "Tutorials"
 weight: 65
 type: docs
+layout: "tutorials"
 webmSrc: "/tutorials/videos/scuttle-gamepad-preview.webm"
 mp4Src: "/tutorials/videos/scuttle-gamepad-preview.mp4"
 videoAlt: "Drive a Scuttle robot with a Bluetooth gamepad."
@@ -13,75 +14,4 @@ sitemap:
   priority: 1.0
 aliases:
     - "/build/"
----
-
-{{< alert title="Tip" color="tip" >}}
-While following a tutorial may require specific hardware, the hardware only affects the part of a project where you configure your components.
-If you are using different hardware your configuration will be different but you can still use the **same tutorial code**.
-
-For this reason, we list tutorials based on features you may be looking for.
-{{< /alert >}}
-
-## Your first robots
-
-{{< cards >}}
-    {{% tutorialcard link="/tutorials/get-started/try-viam-sdk" %}}
-    {{% tutorialcard link="/tutorials/get-started/blink-an-led/" %}}
-    {{% tutorialcard link="/tutorials/get-started/servo-mousemover/" %}}
-    {{% tutorialcard link="/tutorials/get-started/confetti-bot/" %}}
-    {{% tutorialcard link="/tutorials/get-started/lazy-susan/" %}}
-{{< /cards >}}
-
-## Configuration and Testing
-
-{{< cards >}}
-    {{% tutorialcard link="/tutorials/configure/build-a-mock-robot/" %}}
-    {{% tutorialcard link="/tutorials/configure/scuttlebot/" %}}
-{{< /cards >}}
-
-## Controlling
-
-{{< cards >}}
-    {{% tutorialcard link="/tutorials/control/scuttle-gamepad/" %}}
-    {{% tutorialcard link="/tutorials/control/yahboom-rover/" %}}
-{{< /cards >}}
-
-## Services
-
-{{< cards >}}
-    {{% tutorialcard link="/tutorials/services/accessing-and-moving-robot-arm/" %}}
-    {{% tutorialcard link="/tutorials/services/plan-motion-with-arm-gripper/" %}}
-    {{% tutorialcard link="/tutorials/services/constrain-motion/" %}}
-    {{% tutorialcard link="/tutorials/services/data-management-tutorial/" %}}
-    {{% tutorialcard link="/tutorials/services/try-viam-color-detection" %}}
-    {{% tutorialcard link="/tutorials/services/color-detection-scuttle/" %}}
-    {{% tutorialcard link="/tutorials/services/webcam-line-follower-robot/" %}}
-{{< /cards >}}
-
-## Custom Resources
-
-{{< cards >}}
-    {{% tutorialcard link="/tutorials/custom/custom-base-dog/" %}}
-    {{% tutorialcard link="/tutorials/custom/controlling-an-intermode-rover-canbus/" %}}
-{{< /cards >}}
-
-## Projects
-
-{{< cards >}}
-    {{% tutorialcard link="/tutorials/projects/make-a-plant-watering-robot/" %}}
-    {{% tutorialcard link="/tutorials/projects/foam-dart-launcher/" %}}
-    {{% tutorialcard link="/tutorials/projects/light-up/" %}}
-    {{% tutorialcard link="/tutorials/projects/send-security-photo/" %}}
-    {{% tutorialcard link="/tutorials/projects/guardian/" %}}
-    {{% tutorialcard link="/tutorials/projects/integrating-viam-with-openai/" %}}
-    {{% tutorialcard link="/tutorials/projects/modernize-retro-robot/" %}}
-    {{% tutorialcard link="/tutorials/projects/build-an-outdoor-rover/" %}}
-    {{% tutorialcard link="/tutorials/projects/pet-treat-dispenser/" %}}
-    {{% tutorialcard link="/tutorials/projects/tipsy/" %}}
-    {{% tutorialcard link="/tutorials/projects/claw-game/" %}}
-    {{% tutorialcard link="/tutorials/projects/bedtime-songs-bot/" %}}
-{{< /cards >}}
-
-<br>
-
-Have questions, or want to meet other people working on robots? Join our [Community Discord](https://discord.gg/viam).
+---

docs/tutorials/configure/build-a-mock-robot.md

@@ -1,7 +1,6 @@
 ---
 title: "Build a Mock Robot"
 linkTitle: "Mock Robot"
-weight: 41
 type: "docs"
 description: "Create a mock robot using just your personal computer to try using Viam without any robotic hardware."
 webmSrc: "/tutorials/build-a-mock-robot/mock-robot.webm"
@@ -15,8 +14,9 @@ tags: ["mock", "simulation"]
 authors: []
 languages: [ "python", "go" ]
 viamresources: [ "board", "arm", "motor" ]
-level: "Beginner"
-date: "11 October 2022"
+level: "Intermediate"
+date: "2022-10-11"
+# updated: ""
 cost: "0"
 ---
 
@@ -521,4 +521,4 @@ When you run this code, you will see your mock sub motor toggling between runnin
 
 In this tutorial, we showed you how to set up a mock robot with a sub-part so that you can learn more about using fake components, setting up a local development environment, and writing code using a Viam SDK.
 
-If you're ready to get started with building robots with real hardware components, pick up a [board](/components/board/) and try building one of Viam's [introductory robots](/tutorials/#your-first-robots).
+If you're ready to get started with building robots with real hardware components, pick up a [board](/components/board/) and try following another [tutorial](/tutorials/).

docs/tutorials/configure/scuttlebot.md

@@ -1,7 +1,6 @@
 ---
 title: "Configure a SCUTTLE Robot"
 linkTitle: "Configure a SCUTTLE Robot"
-weight: 15
 type: "docs"
 description: "Configure a SCUTTLE robot on the Viam platform."
 image: "/tutorials/scuttlebot/createcomponent.png"
@@ -15,8 +14,8 @@ authors: []
 languages: [ "python", "go" ]
 viamresources: [ "board", "motor", "camera" ]
 level: "Beginner"
-date: "2 August 2022"
-updated: "15 August 2023"
+date: "2022-08-02"
+updated: "2023-08-05"
 cost: 540
 ---
 

docs/tutorials/control/scuttle-gamepad.md

@@ -1,7 +1,6 @@
 ---
 title: "Drive a Rover (like SCUTTLE) Using a Gamepad with a Dongle"
 linkTitle: "Drive a Rover with a Dongle Gamepad"
-weight: 20
 type: "docs"
 description: "Drive a wheeled rover with a Bluetooth gamepad that has a dongle."
 webmSrc: "/tutorials/videos/scuttle-gamepad-preview.webm"
@@ -15,8 +14,9 @@ tags: ["base", "scuttle", "gamepad"]
 authors: []
 languages: []
 viamresources: [ "base", "input_controller" ]
-level: "Beginner"
-date: "10 August 2022"
+level: "Intermediate"
+date: "2022-08-10"
+# updated: ""
 cost: 575
 ---