From b10b23a47bb822bc3eee671d24fd954ec8d74a7d Mon Sep 17 00:00:00 2001
From: Jacky Zhao <j.zhao2k19@gmail.com>
Date: Mon, 01 Aug 2022 01:02:06 +0000
Subject: [PATCH] docs: add documentation for Operand Search, remove debounce
---
assets/js/semantic-search.js | 12 +-----
content/notes/config.md | 10 ++--
content/notes/search.md | 50 +++++++++++++++++++++++++
data/config.yaml | 4 +-
content/notes/preview changes.md | 4 +-
content/_index.md | 4 +-
6 files changed, 63 insertions(+), 21 deletions(-)
diff --git a/assets/js/semantic-search.js b/assets/js/semantic-search.js
index 45c51e0..3cebe5a 100644
--- a/assets/js/semantic-search.js
+++ b/assets/js/semantic-search.js
@@ -15,15 +15,7 @@
return (await response.json());
}
-function debounce(func, timeout = 300) {
- let timer;
- return (...args) => {
- clearTimeout(timer)
- timer = setTimeout(() => { func.apply(this, args); }, timeout)
- };
-}
-
-registerHandlers(debounce((e) => {
+registerHandlers((e) => {
term = e.target.value
if (term !== "") {
searchContents(term)
@@ -35,4 +27,4 @@
))
.then(results => displayResults(results))
}
-}))
+})
diff --git a/content/_index.md b/content/_index.md
index 0278cc5..b5efe4e 100644
--- a/content/_index.md
+++ b/content/_index.md
@@ -4,8 +4,8 @@
Host your second brain and [digital garden](https://jzhao.xyz/posts/networked-thought) for free. Quartz features
-1. Extremely fast full-text search by pressing `Ctrl` + `k`
-2. Customizable and hackable design based on Hugo
+1. Extremely fast natural-language [[notes/search|search]]
+2. Customizable and hackable design based on [Hugo](https://gohugo.io/)
3. Automatically generated backlinks, link previews, and local graph
4. Built-in [[notes/CJK + Latex Support (测试) | CJK + Latex Support]] and [[notes/callouts | Admonition-style callouts]]
5. Support for both Markdown Links and Wikilinks
diff --git a/content/notes/config.md b/content/notes/config.md
index bc509c2..e1633a0 100644
--- a/content/notes/config.md
+++ b/content/notes/config.md
@@ -52,14 +52,16 @@
# whether to show a section of recent notes on the home page
enableRecentNotes: false
-# whether to display and 'edit' button next to the last edited field
+# whether to display an 'edit' button next to the last edited field
# that links to github
enableGitHubEdit: true
GitHubLink: https://github.com/jackyzha0/quartz/tree/hugo/content
# whether to use Operand to power semantic search
-enableSemanticSearch: true
-operandApiKey: "1e47d93b-1468-45b7-98d5-7f733d5e45e2"
+# IMPORTANT: replace this API key with your own if you plan on using
+# Operand search!
+enableSemanticSearch: false
+operandApiKey: "REPLACE-WITH-YOUR-OPERAND-API-KEY"
# page description used for SEO
description:
@@ -79,7 +81,6 @@
```
### Code Block Titles
-
To add code block titles with Quartz:
1. Ensure that code block titles are enabled in Quartz's configuration:
@@ -142,7 +143,6 @@
### Graph View
To customize the Interactive Graph view, you can poke around `data/graphConfig.yaml`.
-
```yaml {title="data/graphConfig.yaml"}
# if true, a Global Graph will be shown on home page with full width, no backlink.
# A different set of Local Graphs will be shown on sub pages.
diff --git a/content/notes/preview changes.md b/content/notes/preview changes.md
index b79c635..937b99b 100644
--- a/content/notes/preview changes.md
+++ b/content/notes/preview changes.md
@@ -12,7 +12,7 @@
## 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.
-```shell
+```bash
# Install and link `hugo-obsidian` locally
go install github.com/jackyzha0/hugo-obsidian@latest
```
@@ -24,7 +24,7 @@
## Installing Hugo
Hugo is the static site generator that powers Quartz. [Install Hugo with "extended" Sass/SCSS version](https://gohugo.io/getting-started/installing/) first. Then,
-```
+```bash
# Navigate to your local Quartz folder
cd <location-of-your-local-quartz>
diff --git a/content/notes/search.md b/content/notes/search.md
new file mode 100644
index 0000000..b6a1317
--- /dev/null
+++ b/content/notes/search.md
@@ -0,0 +1,50 @@
+---
+title: "Search"
+---
+
+Quartz supports two modes of searching through content.
+
+## Full-text
+Full-text search is the default in Quartz. It produces results that *exactly* match the search query. This is easier to setup but usually produces lower quality matches.
+
+```yaml {title="data/config.yaml"}
+# the default option
+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 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/).
+2. Go to Dashboard > Settings > Integrations.
+3. Follow the steps to setup the GitHub integration. Operand needs access to GitHub in order to index your digital garden properly!
+4. Head over to Dashboard > Objects and press `(Cmd + K)` to open the omnibar and select 'Create Collection'.
+ 1. Set the 'Collection Label' to something that will help you remember it.
+ 2. You can leave the 'Parent Collection' field empty.
+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
+operandApiKey: "0e733a7f-9b9c-48c6-9691-b54fa1c8b910"
+```
+7. Make a commit and push your changes to GitHub. See the [[notes/hosting|hosting]] page if you haven't done this already.
+ 1. This step is *required* for Operand to be able to properly index your content.
+ 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!
\ No newline at end of file
diff --git a/data/config.yaml b/data/config.yaml
index 23bba0f..00c6b74 100644
--- a/data/config.yaml
+++ b/data/config.yaml
@@ -12,8 +12,8 @@
enableRecentNotes: false
enableGitHubEdit: true
GitHubLink: https://github.com/jackyzha0/quartz/tree/hugo/content
-enableSemanticSearch: true
-operandApiKey: "1e47d93b-1468-45b7-98d5-7f733d5e45e2"
+enableSemanticSearch: false
+operandApiKey: "REPLACE-WITH-YOUR-OPERAND-API-KEY"
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.
--
Gitblit v1.10.0