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
---
content/notes/config.md | 188 +++++++++++++++++++++++++++++++++++++++++++----
1 files changed, 172 insertions(+), 16 deletions(-)
diff --git a/content/notes/config.md b/content/notes/config.md
index d04b152..e1633a0 100644
--- a/content/notes/config.md
+++ b/content/notes/config.md
@@ -2,36 +2,192 @@
title: "Configuration"
tags:
- setup
+weight: 0
---
## Configuration
Quartz is designed to be extremely configurable. You can find the bulk of the configuration scattered throughout the repository depending on how in-depth you'd like to get.
-The majority of configuration can be be found under `data/config.yaml`. An annotated example configuration is shown below.
+The majority of configuration can be found under `data/config.yaml`. An annotated example configuration is shown below.
-```yaml
-name: Your name here! # Shows in the footer
-enableToc: true # Whether to show a Table of Contents
-enableLinkPreview: true # whether to render card previews for links
-description: Page description to show to search engines
-page_title: Quartz Example Page # Default Page Title
+```yaml {title="data/config.yaml"}
+# The name to display in the footer
+name: Jacky Zhao
-links: # Links to show in footer
+# whether to globally show the table of contents on each page
+# this can be turned off on a per-page basis by adding this to the
+# front-matter of that note
+enableToc: true
+
+# whether to by-default open or close the table of contents on each page
+openToc: false
+
+# whether to display on-hover link preview cards
+enableLinkPreview: true
+
+# whether to render titles for code blocks
+enableCodeBlockTitle: true
+
+# whether to render copy buttons for code blocks
+enableCodeBlockCopy: true
+
+# whether to render callouts
+enableCallouts: true
+
+# whether to try to process Latex
+enableLatex: true
+
+# whether to enable single-page-app style rendering
+# this prevents flashes of unstyled content and improves
+# smoothness of Quartz. More info in issue #109 on GitHub
+enableSPA: true
+
+# whether to render a footer
+enableFooter: true
+
+# whether backlinks of pages should show the context in which
+# they were mentioned
+enableContextualBacklinks: true
+
+# whether to show a section of recent notes on the home page
+enableRecentNotes: false
+
+# 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
+# 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:
+ 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.
+
+# title of the home page (also for SEO)
+page_title:
+ "🪴 Quartz 3.2"
+
+# links to show in the footer
+links:
- link_name: Twitter
link: https://twitter.com/_jzhao
- link_name: Github
link: https://github.com/jackyzha0
```
+### Code Block Titles
+To add code block titles with Quartz:
+
+1. Ensure that code block titles are enabled in Quartz's configuration:
+
+ ```yaml {title="data/config.yaml", linenos=false}
+ enableCodeBlockTitle: true
+ ```
+
+2. Add the `title` attribute to the desired [code block
+ fence](https://gohugo.io/content-management/syntax-highlighting/#highlighting-in-code-fences):
+
+ ```markdown {linenos=false}
+ ```yaml {title="data/config.yaml"}
+ enableCodeBlockTitle: true # example from step 1
+ ```
+ ```
+
+**Note** that if `{title=<my-title>}` is included, and code block titles are not
+enabled, no errors will occur, and the title attribute will be ignored.
+
+### HTML Favicons
+If you would like to customize the favicons of your Quartz-based website, you
+can add them to the `data/config.yaml` file. The **default** without any set
+`favicon` key is:
+
+```html {title="layouts/partials/head.html", linenostart=15}
+<link rel="shortcut icon" href="icon.png" type="image/png">
+```
+
+The default can be overridden by defining a value to the `favicon` key in your
+`data/config.yaml` file. For example, here is a `List[Dictionary]` example format, which is
+equivalent to the default:
+
+```yaml {title="data/config.yaml", linenos=false}
+favicon:
+ - { rel: "shortcut icon", href: "icon.png", type: "image/png" }
+# - { ... } # Repeat for each additional favicon you want to add
+```
+
+In this format, the keys are identical to their HTML representations.
+
+If you plan to add multiple favicons generated by a website (see list below), it
+may be easier to define it as HTML. Here is an example which appends the
+**Apple touch icon** to Quartz's default favicon:
+
+```yaml {title="data/config.yaml", linenos=false}
+favicon: |
+ <link rel="shortcut icon" href="icon.png" type="image/png">
+ <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">
+```
+
+This second favicon will now be used as a web page icon when someone adds your
+webpage to the home screen of their Apple device. If you are interested in more
+information about the current and past standards of favicons, you can read
+[this article](https://www.emergeinteractive.com/insights/detail/the-essentials-of-favicons/).
+
+**Note** that all generated favicon paths, defined by the `href`
+attribute, are relative to the `static/` directory.
+
### Graph View
To customize the Interactive Graph view, you can poke around `data/graphConfig.yaml`.
-```yaml
-enableLegend: false # automatically generate a legend
-enableDrag: true # allow dragging nodes in the graph
-enableZoom: true # allow zooming and panning the graph
-depth: -1 # how many neighbours of the current node to show (-1 is all nodes)
-paths: # colour specific nodes path off of their path
+```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.
+# if false, Local Graph will be default on every page as usual
+enableGlobalGraph: false
+
+### Local Graph ###
+localGraph:
+ # whether automatically generate a legend
+ enableLegend: false
+
+ # whether to allow dragging nodes in the graph
+ enableDrag: true
+
+ # whether to allow zooming and panning the graph
+ enableZoom: true
+
+ # how many neighbours of the current node to show (-1 is all nodes)
+ depth: 1
+
+ # initial zoom factor of the graph
+ scale: 1.2
+
+ # how strongly nodes should repel each other
+ repelForce: 2
+
+ # how strongly should nodes be attracted to the center of gravity
+ centerForce: 1
+
+ # what the default link length should be
+ linkDistance: 1
+
+ # how big the node labels should be
+ fontSize: 0.6
+
+ # scale at which to start fading the labes on nodes
+ opacityScale: 3
+
+### Global Graph ###
+globalGraph:
+ # same settings as above
+
+### For all graphs ###
+# colour specific nodes path off of their path
+paths:
- /moc: "#4388cc"
```
@@ -40,7 +196,7 @@
Want to go even more in-depth? You can add custom CSS styling and change existing colours through editing `assets/styles/custom.scss`. If you'd like to target specific parts of the site, you can add ids and classes to the HTML partials in `/layouts/partials`.
### Partials
-Partials are what dictate what actually gets rendered to the page. Want to change how pages are styled and structured? You can edit the appropriate layout in `/layouts`.
+Partials are what dictate what gets rendered to the page. Want to change how pages are styled and structured? You can edit the appropriate layout in `/layouts`.
For example, the structure of the home page can be edited through `/layouts/index.html`. To customize the footer, you can edit `/layouts/partials/footer.html`
@@ -48,7 +204,7 @@
Still having problems? Checkout our [FAQ and Troubleshooting guide](notes/troubleshooting.md).
-## Multilingual
+## Language Support
[CJK + Latex Support (测试)](notes/CJK%20+%20Latex%20Support%20(测试).md) comes out of the box with Quartz.
Want to support languages that read from right-to-left (like Arabic)? Hugo (and by proxy, Quartz) supports this natively.
--
Gitblit v1.10.0