feat: docker docs, semantic search alpha

Makefile

@@ -19,3 +19,6 @@ update-force: ## Forcefully pull all changes and don't ask to patch
 serve: ## Serve Quartz locally
 	hugo-obsidian -input=content -output=assets/indices -index -root=.
 	hugo server --enableGitInfo --minify --bind=$(or $(HUGO_BIND),0.0.0.0) --baseURL=$(or $(HUGO_BASEURL),http://localhost) --port=$(or $(HUGO_PORT),1313) --appendPort=$(or $(HUGO_APPENDPORT),true)
+
+docker: ## Serve locally using Docker
+	docker run -it --volume=$(shell pwd):/quartz -p 1313:1313 ghcr.io/jackyzha0/quartz:hugo

assets/js/semantic-search.js

@@ -1,18 +1,26 @@
-const apiKey = "{{$.Site.Data.config.operandApiKey}}"
+import {
+  operandClient,
+  indexIDHeaderKey,
+} from "https://unpkg.com/@operandinc/sdk@4.1.3/dist/esm/index.js"
+
+const apiKey = "{{$.Site.Data.config.search.operandApiKey}}"
+const indexId = "{{$.Site.Data.config.search.operandIndexId}}"
+const operand = operandClient(
+  ObjectService,
+  apiKey,
+  "https://api.operand.ai",
+  {
+    [indexIDHeaderKey]: indexId,
+  }
+);
 
 async function searchContents(query) {
-  const response = await fetch('https://prod.operand.ai/v3/search/objects', {
+  const results = await operand.searchWithin({
-    method: 'POST',
+    query,
-    headers: {
+    limit: 10,
-      'Content-Type': 'application/json',
+  })
-      Authorization: apiKey,
+  console.log(results.matches)
-    },
+  return results.matches.flat()
-    body: JSON.stringify({
-      query,
-      max: 10
-    }),
-  });
-  return (await response.json());
 }
 
 function debounce(func, timeout = 200) {

assets/styles/base.scss

@@ -299,13 +299,11 @@ footer {
 }
 
 hr {
-  width: 25%;
+  width: 100%;
-  margin: 4em auto;
+  margin: 2em auto;
-  height: 2px;
+  height: 1px;
-  border-radius: 1px;
+  border: none;
-  border-width: 0;
+  background-color: var(--outlinegray);
-  color: var(--dark);
-  background-color: var(--dark);
 }
 
 .page-end {

content/notes/config.md

@@ -60,8 +60,10 @@ GitHubLink: https://github.com/jackyzha0/quartz/tree/hugo/content
 # whether to use Operand to power semantic search
 # IMPORTANT: replace this API key with your own if you plan on using
 # Operand search!
-enableSemanticSearch: false
+search:
-operandApiKey: "REPLACE-WITH-YOUR-OPERAND-API-KEY"
+  enableSemanticSearch: false
+  operandApiKey: "REPLACE-WITH-YOUR-OPERAND-API-KEY"
+  operandIndexId: "REPLACE-WITH-YOUR-OPERAND-INDEX-ID"
 
 # page description used for SEO
 description:

content/notes/docker.md

@@ -4,11 +4,10 @@ tags:
 - setup
 ---
 
-If you want to host Quartz on a specific machine, it may be easier to [install Docker Compose](https://docs.docker.com/compose/install/) and follow the instructions below (than to [install Quartz's dependencies manually](notes/preview%20changes.md)).
+If you want to host Quartz on a machine without using a webpage hosting service, it may be easier to [install Docker Compose](https://docs.docker.com/compose/install/) and follow the instructions below than to [install Quartz's dependencies manually](notes/preview%20changes.md).
-
 ## Hosting Quartz Locally
-
+You can serve Quartz locally at `http://localhost:1313` with the following script, replacing `/path/to/quartz` with the 
-You can serve Quartz locally at `http://localhost:1313` with the following script:
+actual path to your Quartz folder.
 
 docker-compose.yml
 ```
@@ -29,11 +28,9 @@ services:
       - HUGO_APPENDPORT=true
 ```
 
-By default, the container will clone and serve `github:jackyzha0/quartz`. However, you can serve your own fork of `quartz` by cloning to the above `/path/to/quartz` directory.
-
 Then run with: `docker-compose up -d` in the same directory as your `docker-compose.yml` file.
 
-While the container is running, you can update their `quartz` fork with: `docker exec -it quartz-hugo make update`.
+While the container is running, you can update the `quartz` fork with: `docker exec -it quartz-hugo make update`.
 
 ## Exposing Your Container to the Internet
 

content/notes/editing.md

@@ -56,8 +56,6 @@ This step is purely optional and mostly for those who want to see the published
 
 > 👀 Step 4: [Preview Quartz Changes](notes/preview%20changes.md)
 
-If you prefer, you can preview changes by [hosting locally with Docker](notes/docker.md) instead! If you have Docker, this might be the easiest approach.
-
 For those who like to live life more on the edge, viewing the garden through Obsidian gets you pretty close to the real thing.
 
 ## Publishing Changes
@@ -65,10 +63,4 @@ Now that you know the basics of managing your digital garden using Quartz, you c
 
 > 🌍 Step 5: [Hosting Quartz online!](notes/hosting.md)
 
-## Hosting with Docker
-You can also choose to publish your digital garden on a local or remote machine using Docker.
-
-> 🐳 [Hosting with Docker](notes/docker.md)
-
-
 Having problems? Checkout our [FAQ and Troubleshooting guide](notes/troubleshooting.md).

content/notes/hosting.md

@@ -83,6 +83,10 @@ Only want to publish a subset of all of your notes? Don't worry, Quartz makes th
 
 ❌ [Excluding pages from being published](notes/ignore%20notes.md)
 
+## Docker Support
+If you don't want to use a hosting service, you can host using [Docker](notes/docker.md) instead!
+I would *not use this method* unless you know what you are doing.
+
 ---
 
 Now that your Quartz is live, let's figure out how to make Quartz really *yours*!

content/notes/preview changes.md

@@ -5,9 +5,9 @@ tags:
 weight: -2
 ---
 
-If you'd like to preview what your Quartz site looks like before deploying it to the internet, here's exactly how to do that!
+If you'd like to preview what your Quartz site looks like before deploying it to the internet, the following
+instructions guide you through installing the proper dependencies to run it locally.
 
-Note that both of these steps need to be completed.
 
 ## Install `hugo-obsidian`
 This step will generate the list of backlinks for Hugo to parse. Ensure you have [Go](https://golang.org/doc/install) (>= 1.16) installed.
@@ -34,4 +34,10 @@ make serve
 # View your site in a browser at http://localhost:1313/
 ```
 
+> [!INFO] Docker Support
+>
+> If you have Docker installed already, open your terminal, navigate to your folder with Quartz and run `make docker`
+
+Now that you are happy with how your Quartz instance looks, let's get it hosted!
+
 > 🌍 Step 5: [Hosting Quartz online!](notes/hosting.md)

content/notes/search.md

@@ -13,38 +13,25 @@ enableSemanticSearch: false
 ```
 
 ## Natural Language
-Natural language search is powered by [Operand](https://operand.ai/). It understands language like a person does and finds results that best match user intent. In this sense, it is closer to how Google Search works.
+Natural language search is powered by [Operand](https://beta.operand.ai/). It understands language like a person does and finds results that best match user intent. In this sense, it is closer to how Google Search works.
 
 Natural language search tends to produce higher quality results than full-text search.
 
 Here's how to set it up.
 
-1. Create an Operand Account on [their website](https://operand.ai/).
+1. Login or Register for a new Operand account. Click the verification link sent to your email, and you'll be redirected to the dashboard. (Note) You do not need to enter a credit card to create an account, or get started with the Operand API. The first $10 of usage each month is free. To learn more, see pricing. If you go over your free quota, we'll (politely) reach out and ask you to configure billing.
-2. Go to Dashboard > Settings > Integrations.
+2. Create your first index. On the dashboard, under "Indexes", enter the name and description of your index, and click "Create Index". Note down the ID of the index (obtained by clicking on the index name in the list of indexes), as you'll need it in the next step. IDs are unique to each index, and look something like `uqv1duxxbdxu`.
-3. Follow the steps to setup the GitHub integration. Operand needs access to GitHub in order to index your digital garden properly!
+3. Click into the index you've created. Under "Index Something", select "SITEMAP" from the dropdown and click "Add Source".
-4. Head over to Dashboard > Objects and press `(Cmd + K)` to open the omnibar and select 'Create Collection'.
+4. For the "Sitemap.xml URL", put your deployed site's base URL followed by `sitemap.xml`. For example, for `quartz.jzhao.xyz`, put `https://quartz.jzhao.xyz/sitemap.xml`. Leave the URL Regex empty. 
-	1. Set the 'Collection Label' to something that will help you remember it.
+5. Get your API key. On the dashboard, under "API Keys", you can manage your API keys. If you don't already have an API key, click "Create API Key". You'll need this for the next step.
-	2. You can leave the 'Parent Collection' field empty.
+6. Open `data/config.yaml`. Set `enableSemanticSearch` to `true`, `operandApiKey` to your copied key, and `operandIndexId` to the ID of the index we created from earlier..
-5. Click into your newly made Collection.
-	1. Press the 'share' button that looks like three dots connected by lines.
-	2. Set the 'Interface Type' to `object-search` and click 'Create'.
-	3. This will bring you to a new page with a search bar. Ignore this for now.
-6. Go back to Dashboard > Settings > API Keys and find your Quartz-specific Operand API key under 'Other keys'.
-	1. Copy the key (which looks something like `0e733a7f-9b9c-48c6-9691-b54fa1c8b910`).
-	2. Open `data/config.yaml`. Set `enableSemanticSearch` to `true` and `operandApiKey` to your copied key.
 
 ```yaml {title="data/config.yaml"}
 # the default option
-enableSemanticSearch: true
+search:
-operandApiKey: "0e733a7f-9b9c-48c6-9691-b54fa1c8b910"
+  enableSemanticSearch: true
+  operandApiKey: "jp9k5hudse2a828z98kxd6z3payi8u90rnjf"
+  operandIndexId: "s0kf3bd6tldw"
 ```
-7. Make a commit and push your changes to GitHub. See the [[notes/hosting|hosting]] page if you haven't done this already.
+7. Push your changes to the site and wait for it to deploy.
-	1. This step is *required* for Operand to be able to properly index your content. 
+8. Check the Operand dashboard and wait for your site to index. Enjoy natural language search powered by Operand!
-	2. Head over to Dashboard > Objects and select the collection that you made earlier
-8. Press `(Cmd + K)` to open the omnibar again and select 'Create GitHub Repo'
-	1. Set the 'Repository Label' to `Quartz`
-	2. Set the 'Repository Owner' to your GitHub username
-	3. Set the 'Repository Ref' to `master`
-	4. Set the 'Repository Name' to the name of your repository (usually just `quartz` if you forked the repository without changing the name)
-	5. Leave 'Root Path' and 'Root URL' empty
-9. Wait for your repository to index and enjoy natural language search in Quartz! Operand refreshes the index every 2h so all you need to do is just push to GitHub to update the contents in the search.

data/config.yaml

@@ -12,8 +12,12 @@ enableContextualBacklinks: true
 enableRecentNotes: false
 enableGitHubEdit: true
 GitHubLink: https://github.com/jackyzha0/quartz/tree/hugo/content
-enableSemanticSearch: false
+search:
-operandApiKey: "REPLACE-WITH-YOUR-OPERAND-API-KEY"
+  enableSemanticSearch: true
+  # operandApiKey: "REPLACE-WITH-YOUR-OPERAND-API-KEY"
+  # operandIndexId: "REPLACE-WITH-YOUR-OPERAND-INDEX-ID"
+  operandApiKey: "jp9k5hudse2a828z98kxd6z3payi8u90rnje"
+  operandIndexId: "s0kf3bd6tldw"
 description:
   Host your second brain and digital garden for free. Quartz features extremely fast full-text search,
   Wikilink support, backlinks, local graph, tags, and link previews.

layouts/partials/search.html

@@ -6,9 +6,9 @@
     </div>
   </div>
 </div>
-{{if $.Site.Data.config.enableSemanticSearch}}
+{{if $.Site.Data.config.search.enableSemanticSearch}}
 {{ $js := resources.Get "js/semantic-search.js" | resources.ExecuteAsTemplate "js/semantic-search.js" . | resources.Fingerprint "md5" | resources.Minify }}
-<script defer src="{{ $js.Permalink }}"></script>
+<script defer type="module" src="{{ $js.Permalink }}"></script>
 {{else}}
 <script src="https://cdn.jsdelivr.net/npm/flexsearch@0.7.21/dist/flexsearch.bundle.js"
   integrity="sha256-i3A0NZGkhsKjVMzFxv3ksk0DZh3aXqu0l49Bbh0MdjE=" crossorigin="anonymous" defer></script>