From b10b23a47bb822bc3eee671d24fd954ec8d74a7d Mon Sep 17 00:00:00 2001 From: Jacky Zhao Date: Sun, 31 Jul 2022 18:02:06 -0700 Subject: [PATCH] docs: add documentation for Operand Search, remove debounce --- assets/js/semantic-search.js | 12 ++------ content/_index.md | 4 +-- content/notes/config.md | 10 +++---- content/notes/preview changes.md | 4 +-- content/notes/search.md | 50 ++++++++++++++++++++++++++++++++ data/config.yaml | 4 +-- 6 files changed, 63 insertions(+), 21 deletions(-) create mode 100644 content/notes/search.md diff --git a/assets/js/semantic-search.js b/assets/js/semantic-search.js index 45c51e0b..3cebe5a4 100644 --- a/assets/js/semantic-search.js +++ b/assets/js/semantic-search.js @@ -15,15 +15,7 @@ async function searchContents(query) { 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 @@ registerHandlers(debounce((e) => { )) .then(results => displayResults(results)) } -})) +}) diff --git a/content/_index.md b/content/_index.md index 0278cc5e..b5efe4ec 100644 --- a/content/_index.md +++ b/content/_index.md @@ -4,8 +4,8 @@ title: 🪴 Quartz 3.2 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 bc509c2b..e1633a00 100644 --- a/content/notes/config.md +++ b/content/notes/config.md @@ -52,14 +52,16 @@ enableContextualBacklinks: true # 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 @@ links: ``` ### 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 @@ attribute, are relative to the `static/` directory. ### 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 b79c635b..937b99ba 100644 --- a/content/notes/preview changes.md +++ b/content/notes/preview changes.md @@ -12,7 +12,7 @@ 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. -```shell +```bash # Install and link `hugo-obsidian` locally go install github.com/jackyzha0/hugo-obsidian@latest ``` @@ -24,7 +24,7 @@ Afterwards, start the Hugo server as shown above and your local backlinks and in ## 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 diff --git a/content/notes/search.md b/content/notes/search.md new file mode 100644 index 00000000..b6a13176 --- /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 23bba0f4..00c6b741 100644 --- a/data/config.yaml +++ b/data/config.yaml @@ -12,8 +12,8 @@ enableContextualBacklinks: true 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.