alrayyes/wiki
1
0
Fork 0
mirror of https://github.com/alrayyes/wiki.git synced 2025-05-12 19:50:39 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions2

run prettier

Browse source
This commit is contained in:
Jacky Zhao 2023-07-22 17:27:41 -07:00
parent 2034b970b6
commit 7db2eda76c
101 changed files with 1810 additions and 1405 deletions

2
content/advanced/creating components.md
View file

@ -2,4 +2,4 @@
title: Creating your own Quartz components
---
See the [component listing](/tags/component) for a full-list of the Quartz built-in components.
See the [component listing](/tags/component) for a full-list of the Quartz built-in components.

3
content/advanced/making plugins.md
View file

@ -5,6 +5,7 @@ title: Making your own plugins
This part of the documentation will assume you have some basic coding knowledge and will include code snippets that describe the interface of what Quartz plugins should look like.
## Transformers
```ts
export type QuartzTransformerPluginInstance = {
name: string
@ -17,4 +18,4 @@ export type QuartzTransformerPluginInstance = {
## Filters
## Emitters
## Emitters

51
content/configuration.md
View file

@ -2,7 +2,7 @@
title: Configuration
---
Quartz is meant to be extremely configurable, even if you don't know any coding. Most of the configuration you should need can be done by just editing `quartz.config.ts`.
Quartz is meant to be extremely configurable, even if you don't know any coding. Most of the configuration you should need can be done by just editing `quartz.config.ts`.
If you edit this file using a text-editor that has TypeScript language support like VSCode, it will warn you when you you've made an error in your configuration.
@ -16,33 +16,35 @@ const config: QuartzConfig = {
```
## General Configuration
This part of the configuration concerns anything that can affect the whole site. The following is a list breaking down all the things you can configure:
- `pageTitle`: used as an anchor to return to the home page. This is also used when generating the [[RSS Feed]] for your site.
- `enableSPA`: whether to enable [[SPA Routing]] on your site.
- `enablePopovers`: whether to enable [[popover previews]] on your site.
- `analytics`: what to use for analytics on your site. Values can be
- `null`: don't use analytics;
- `{ provider: 'plausible' }`: use [Plausible](https://plausible.io/), a privacy-friendly alternative to Google Analytics; or
- `{ provider: 'google', tagId: <your-google-tag> }`: use Google Analytics
- `caononicalUrl`: sometimes called `baseURL` in other site generators. This is used for sitemaps and RSS feeds that require an absolute URL to know where the canonical 'home' of your site lives. This is normally the deployed URL of your site (e.g. `https://quartz.jzhao.xyz/` for this site). Note that Quartz 4 will avoid using this as much as possible and use relative URLs whenever it can to make sure your site works no matter *where* you end up actually deploying it.
- `ignorePatterns`: a list of [glob](https://en.wikipedia.org/wiki/Glob_(programming)) patterns that Quartz should ignore and not search through when looking for files inside the `content` folder.
- `analytics`: what to use for analytics on your site. Values can be
- `null`: don't use analytics;
- `{ provider: 'plausible' }`: use [Plausible](https://plausible.io/), a privacy-friendly alternative to Google Analytics; or
- `{ provider: 'google', tagId: <your-google-tag> }`: use Google Analytics
- `caononicalUrl`: sometimes called `baseURL` in other site generators. This is used for sitemaps and RSS feeds that require an absolute URL to know where the canonical 'home' of your site lives. This is normally the deployed URL of your site (e.g. `https://quartz.jzhao.xyz/` for this site). Note that Quartz 4 will avoid using this as much as possible and use relative URLs whenever it can to make sure your site works no matter _where_ you end up actually deploying it.
- `ignorePatterns`: a list of [glob](<https://en.wikipedia.org/wiki/Glob_(programming)>) patterns that Quartz should ignore and not search through when looking for files inside the `content` folder.
- `theme`: configure how the site looks.
- `typography`: what fonts to use. Any font available on [Google Fonts](https://fonts.google.com/) works here.
- `header`: Font to use for headers
- `code`: Font for inline and block quotes.
- `body`: Font for everything
- `colors`: controls the theming of the site.
- `light`: page background
- `lightgray`: borders
- `gray`: graph links, heavier borders
- `darkgray`: body text
- `dark`: header text and icons
- `secondary`: link colour, current [[graph view|graph]] node
- `tertiary`: hover states and visited [[graph view|graph]] nodes
- `highlight`: internal link background, highlighted text, [[syntax highlighting|highlighted lines of code]]
- `typography`: what fonts to use. Any font available on [Google Fonts](https://fonts.google.com/) works here.
- `header`: Font to use for headers
- `code`: Font for inline and block quotes.
- `body`: Font for everything
- `colors`: controls the theming of the site.
- `light`: page background
- `lightgray`: borders
- `gray`: graph links, heavier borders
- `darkgray`: body text
- `dark`: header text and icons
- `secondary`: link colour, current [[graph view|graph]] node
- `tertiary`: hover states and visited [[graph view|graph]] nodes
- `highlight`: internal link background, highlighted text, [[syntax highlighting|highlighted lines of code]]
## Plugins
You can think of Quartz plugins as a series of transformations over content.
![[quartz-transform-pipeline.png]]
@ -62,18 +64,19 @@ plugins: {
By adding, removing, and reordering plugins from the `tranformers`, `filters`, and `emitters` fields, you can customize the behaviour of Quartz.
> [!note]
> Each node is modified by every transformer *in order*. Some transformers are position-sensitive so you may need to take special note of whether it needs come before or after any other particular plugins.
> Each node is modified by every transformer _in order_. Some transformers are position-sensitive so you may need to take special note of whether it needs come before or after any other particular plugins.
Additionally, plugins may also have their own configuration settings that you can pass in. For example, the [[Latex]] plugin allows you to pass in a field specifying the `renderEngine` to choose between Katex and MathJax.
```ts
transformers: [
Plugin.FrontMatter(), // uses default options
Plugin.Latex({ renderEngine: 'katex' }) // specify some options
Plugin.FrontMatter(), // uses default options
Plugin.Latex({ renderEngine: "katex" }), // specify some options
]
```
### Layout
Certain emitters may also output [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML) files. To make sure that
Certain emitters may also output [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML) files. To make sure that
### Components

10
content/features/Latex.md
View file

@ -3,6 +3,7 @@ Quartz uses [Katex](https://katex.org/) by default to typeset both inline and bl
## Formatting
### Block Math
Block math can be rendered by delimiting math expression with `$$`.
```
@ -20,20 +21,25 @@ f(x) = \int_{-\infty}^\infty
$$
### Inline Math
Similarly, inline math can be rendered by delimiting math expression with a single `$`. For example, `$e^{i\pi} = -1$` produces $e^{i\pi} = -1$
### Escaping symbols
There will be cases where you may have more than one `$` in a paragraph at once which may accidentally trigger MathJax/Katex.
There will be cases where you may have more than one `$` in a paragraph at once which may accidentally trigger MathJax/Katex.
To get around this, you can escape the dollar sign by doing `\$` instead.
For example:
- Incorrect: `I have $1 and you have $2` produces I have $1 and you have $2
- Correct: `I have \$1 and you have \$2` produces I have \$1 and you have \$2
## MathJax
In `quartz.config.ts`, you can configure Quartz to use [MathJax SVG rendering](https://docs.mathjax.org/en/latest/output/svg.html) by replacing `Plugin.Latex({ renderEngine: 'katex' })` with `Plugin.Latex({ renderEngine: 'mathjax' })`
## Customization
- Removing Latex support: remove all instances of `Plugin.Latex()` from `quartz.config.ts`.
- Plugin: `quartz/plugins/transformers/latex.ts`
- Plugin: `quartz/plugins/transformers/latex.ts`

2
content/features/Mermaid diagrams.md
View file

@ -1,5 +1,5 @@
> [!warning]
> Wondering why Mermaid diagrams may not be showing up even if you have them enabled? You may need to reorder your plugins so that `Plugin.ObsidianFlavoredMarkdown()` is *after* `Plugin.SyntaxHighlighting()`.
> Wondering why Mermaid diagrams may not be showing up even if you have them enabled? You may need to reorder your plugins so that `Plugin.ObsidianFlavoredMarkdown()` is _after_ `Plugin.SyntaxHighlighting()`.
```mermaid
sequenceDiagram

2
content/features/SPA Routing.md
View file

@ -1 +1 @@
Single-page-app style rendering. This prevents flashes of unstyled content and improves smoothness of Quartz
Single-page-app style rendering. This prevents flashes of unstyled content and improves smoothness of Quartz

5
content/features/backlinks.md
View file

@ -1,13 +1,14 @@
---
title: Backlinks
tags:
- component
- component
---
A backlink for a note is a link from another note to that note. Links in the backlink pane also feature rich [[popover previews]] if you have that feature enabled.
## Customization
- Removing backlinks: delete all usages of `Component.Backlinks()` from `quartz.config.ts`.
- Component: `quartz/components/Backlinks.tsx`
- Style: `quartz/components/styles/backlinks.scss`
- Script: `quartz/components/scripts/search.inline.ts`
- Script: `quartz/components/scripts/search.inline.ts`

21
content/features/callouts.md
View file

@ -3,15 +3,16 @@ title: Callouts
---
> [!warning]
> Wondering why callouts may not be showing up even if you have them enabled? You may need to reorder your plugins so that `Plugin.ObsidianFlavoredMarkdown()` is *after* `Plugin.SyntaxHighlighting()`.
> Wondering why callouts may not be showing up even if you have them enabled? You may need to reorder your plugins so that `Plugin.ObsidianFlavoredMarkdown()` is _after_ `Plugin.SyntaxHighlighting()`.
> [!info]
> Default title
> [!question]+ Can callouts be nested?
>
> > [!todo]- Yes!, they can.
> > > [!example] You can even use multiple layers of nesting.
> >
> > > [!example] You can even use multiple layers of nesting.
> [!EXAMPLE] Examples
>
@ -21,31 +22,31 @@ title: Callouts
>
> Aliases: note
> [!abstract] Summaries
> [!abstract] Summaries
>
> Aliases: abstract, summary, tldr
> [!info] Info
> [!info] Info
>
> Aliases: info, todo
> [!tip] Hint
> [!tip] Hint
>
> Aliases: tip, hint, important
> [!success] Success
> [!success] Success
>
> Aliases: success, check, done
> [!question] Question
> [!question] Question
>
> Aliases: question, help, faq
> [!warning] Warning
> [!warning] Warning
>
> Aliases: warning, caution, attention
> [!failure] Failure
> [!failure] Failure
>
> Aliases: failure, fail, missing

10
content/features/full-text search.md
View file

@ -1,12 +1,12 @@
---
title: Full-text Search
tags:
- component
tags:
- component
---
Full-text search in Quartz is powered by [Flexsearch](https://github.com/nextapps-de/flexsearch). It's fast enough to return search results in under 10ms for Quartzs as large as half a million words.
It can be opened by either clicking on the search bar or pressing ⌘+K. The top 5 search results are shown on each query. Matching subterms are highlighted and the most relevant 30 words are excerpted. Clicking on a search result will navigate to that page.
It can be opened by either clicking on the search bar or pressing ⌘+K. The top 5 search results are shown on each query. Matching subterms are highlighted and the most relevant 30 words are excerpted. Clicking on a search result will navigate to that page.
This component is also keyboard accessible: Tab and Shift+Tab will cycle forward and backward through search results and Enter will navigate to the highlighted result (first result by default).
@ -14,13 +14,15 @@ This component is also keyboard accessible: Tab and Shift+Tab will cycle forward
> Search requires the `ContentIndex` emitter plugin to be present in the [[configuration]].
### Indexing Behaviour
By default, it indexes every page on the site with **Markdown syntax removed**. This means link URLs for instance are not indexed.
It properly tokenizes Chinese, Korean, and Japenese characters and constructs separate indexes for the title and content, weighing title matches above content matches.
## Customization
- Removing search: delete all usages of `Component.Search()` from `quartz.config.ts`.
- Component: `quartz/components/Search.tsx`
- Style: `quartz/components/styles/search.scss`
- Script: `quartz/components/scripts/search.inline.ts`
- You can edit `contextWindowWords` or `numSearchResults` to suit your needs
- You can edit `contextWindowWords` or `numSearchResults` to suit your needs

23
content/features/graph view.md
View file

@ -1,13 +1,13 @@
---
title: "Graph View"
tags:
- component
- component
---
Quartz features a graph-view that can show both a local graph view and a global graph view.
Quartz features a graph-view that can show both a local graph view and a global graph view.
- The local graph view shows files that either link to the current file or are linked from the current file. In other words, it shows all notes that are *at most* one hop away.
- The global graph view can be toggled by clicking the graph icon on the top-right of the local graph view. It shows *all* the notes in your graph and how they connect to each other.
- The local graph view shows files that either link to the current file or are linked from the current file. In other words, it shows all notes that are _at most_ one hop away.
- The global graph view can be toggled by clicking the graph icon on the top-right of the local graph view. It shows _all_ the notes in your graph and how they connect to each other.
By default, the node radius is proportional to the total number of incoming and outgoing internal links from that file.
@ -17,6 +17,7 @@ Additionally, similar to how browsers highlight visited links a different colour
> Graph View requires the `ContentIndex` emitter plugin to be present in the [[configuration]].
## Customization
Most configuration can be done by passing in options to `Component.Graph()`.
For example, here's what the default configuration looks like:
@ -26,13 +27,13 @@ Component.Graph({
localGraph: {
drag: true, // whether to allow panning the view around
zoom: true, // whether to allow zooming in and out
depth: 1, // how many hops of notes to display
depth: 1, // how many hops of notes to display
scale: 1.1, // default view scale
repelForce: 0.5, // how much nodes should repel each other
repelForce: 0.5, // how much nodes should repel each other
centerForce: 0.3, // how much force to use when trying to center the nodes
linkDistance: 30, // how long should the links be by default?
fontSize: 0.6, // what size should the node labels be?
opacityScale: 1 // how quickly do we fade out the labels when zooming out?
fontSize: 0.6, // what size should the node labels be?
opacityScale: 1, // how quickly do we fade out the labels when zooming out?
},
globalGraph: {
drag: true,
@ -43,8 +44,8 @@ Component.Graph({
centerForce: 0.3,
linkDistance: 30,
fontSize: 0.6,
opacityScale: 1
}
opacityScale: 1,
},
})
```
@ -55,4 +56,4 @@ Want to customize it even more?
- Removing graph view: delete all usages of `Component.Graph()` from `quartz.config.ts`.
- Component: `quartz/components/Graph.tsx`
- Style: `quartz/components/styles/graph.scss`
- Script: `quartz/components/scripts/graph.inline.ts`
- Script: `quartz/components/scripts/graph.inline.ts`

2
content/features/index.md
View file

@ -1,3 +1,3 @@
---
title: Feature List
---
---

3
content/features/popover previews.md
View file

@ -9,6 +9,7 @@ By default, Quartz only fetches previews for pages inside your vault due to [COR
When [[creating components|creating your own components]], you can include this `popover-hint` class to also include it in the popover.
## Configuration
- Remove popovers: set the `enablePopovers` field in `quartz.config.ts` to be `false`.
- Style: `quartz/components/styles/popover.scss`
- Script: `quartz/components/scripts/popover.inline.ts`
- Script: `quartz/components/scripts/popover.inline.ts`

19
content/features/syntax highlighting.md
View file

@ -12,6 +12,7 @@ In short, it generates HTML that looks exactly like your code in an editor like
> Syntax highlighting does have an impact on build speed if you have a lot of code snippets in your notes.
## Formatting
Text inside `backticks` on a line will be formatted like code.
````
@ -37,11 +38,12 @@ export function trimPathSuffix(fp: string): string {
```
### Titles
Add a file title to your code block, with text inside double quotes (`""`):
````
```js title="..."
```
````
@ -56,11 +58,12 @@ export function trimPathSuffix(fp: string): string {
```
### Line highlighting
Place a numeric range inside `{}`.
````
```js {1-3,4}
```
````
@ -75,6 +78,7 @@ export function trimPathSuffix(fp: string): string {
```
### Word highlighting
A series of characters, like a literal regex.
````
@ -85,16 +89,17 @@ const [name, setName] = useState('Taylor');
````
```js /useState/
const [age, setAge] = useState(50);
const [name, setName] = useState('Taylor');
const [age, setAge] = useState(50)
const [name, setName] = useState("Taylor")
```
### Line numbers
Syntax highlighting has line numbers configured automatically. If you want to start line numbers at a specific number, use `showLineNumbers{number}`:
````
```js showLineNumbers{number}
```
````
@ -109,6 +114,7 @@ export function trimPathSuffix(fp: string): string {
```
### Escaping code blocks
You can format a codeblock inside of a codeblock by wrapping it with another level of backtick fences that has one more backtick than the previous fence.
`````
@ -121,6 +127,7 @@ const [name, setName] = useState('Taylor');
`````
## Customization
- Removing syntax highlighting: delete all usages of `Plugin.SyntaxHighlighting()` from `quartz.config.ts`.
- Style: By default, Quartz uses derivatives of the GitHub light and dark themes. You can customize the colours in the `quartz/styles/syntax.scss` file.
- Plugin: `quartz/plugins/transformers/syntax.ts`
- Plugin: `quartz/plugins/transformers/syntax.ts`

4
content/features/table of contents.md
View file

@ -1,5 +1,5 @@
---
title: "Table of Contents"
tags:
- component
---
- component
---

10
content/features/upcoming features.md
View file

@ -12,9 +12,9 @@ draft: true
- custom md blocks (e.g. for poetry)
- sidenotes? [https://github.com/capnfabs/paperesque](https://github.com/capnfabs/paperesque)
- watch mode
- watch for markdown changes and quartz config changes
- markdown changes only involve processing that single markdown file (at least for parsing) and then rerunning the filter and emitters
- config changes rebuild the whole thing
- watch for markdown changes and quartz config changes
- markdown changes only involve processing that single markdown file (at least for parsing) and then rerunning the filter and emitters
- config changes rebuild the whole thing
- direct match in search using double quotes
- attachments path
- [https://help.obsidian.md/Advanced+topics/Using+Obsidian+URI](https://help.obsidian.md/Advanced+topics/Using+Obsidian+URI)
@ -26,8 +26,8 @@ draft: true
- audio/video embed styling
- Canvas
- mermaid styling: [https://mermaid.js.org/config/theming.html#theme-variables-reference-table](https://mermaid.js.org/config/theming.html#theme-variables-reference-table)
- [https://github.com/jackyzha0/quartz/issues/331](https://github.com/jackyzha0/quartz/issues/331)
- [https://github.com/jackyzha0/quartz/issues/331](https://github.com/jackyzha0/quartz/issues/331)
- block links: [https://help.obsidian.md/Linking+notes+and+files/Internal+links#Link+to+a+block+in+a+note](https://help.obsidian.md/Linking+notes+and+files/Internal+links#Link+to+a+block+in+a+note)
- note/header/block transcludes: [https://help.obsidian.md/Linking+notes+and+files/Embedding+files](https://help.obsidian.md/Linking+notes+and+files/Embedding+files)
- parse all images in page: use this for page lists if applicable?
- CV mode? with print stylesheet
- CV mode? with print stylesheet

4
content/index.md
View file

@ -5,6 +5,7 @@ title: Welcome to Quartz 4
Quartz is a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites. Thousands of students, developers, and teachers are [[showcase|already using Quartz]] to publish personal notes, wikis, and [digital gardens](https://jzhao.xyz/posts/networked-thought/) to the web.
## 🪴 Get Started
Quartz requires **at least [Node](https://nodejs.org/) v16** to function correctly. In your terminal of choice, enter the following commands line by line:
```shell
@ -26,7 +27,8 @@ When you're ready, you can edit `quartz.config.ts` to customize and configure Qu
- [[SPA Routing|Ridiculously fast page loads]] and tiny bundle sizes
- Fully-customizable parsing, filtering, and page generation through [[making plugins|plugins]]
For a comprehensive list of features, visit the [features page](/features). You can read more the *why* behind these features on the [[philosophy]] page.
For a comprehensive list of features, visit the [features page](/features). You can read more the _why_ behind these features on the [[philosophy]] page.
### 🚧 Troubleshooting
Having trouble with Quartz? Try searching for your issue using the search feature. If you're still having trouble, feel free to [submit an issue](https://github.com/jackyzha0/quartz/issues) if you feel you found a bug or ask for help in our [Discord Community](https://discord.gg/cRFFHYye7t).

4
content/philosophy.md
View file

@ -5,7 +5,7 @@ title: Philosophy of Quartz
## A garden should be a true hypertext
> The garden is the web as topology. Every walk through the garden creates new paths, new meanings, and when we add things to the garden we add them in a way that allows many future, unpredicted relationships.
>
>
> (The Garden and the Stream)
The problem with the file cabinet is that it focuses on efficiency of access and interoperability rather than generativity and creativity. Thinking is not linear, nor is it hierarchical. In fact, not many things are linear or hierarchical at all. Then why is it that most tools and thinking strategies assume a nice chronological or hierarchical order for my thought processes? The ideal tool for thought for me would embrace the messiness of my mind, and organically help insights emerge from chaos instead of forcing an artificial order. A rhizomatic, not arboresecent, form of note taking.
@ -20,7 +20,7 @@ Quartz embraces the inherent rhizomatic and web-like nature of our thinking and
The goal of digital gardening should be to tap into your network’s collective intelligence to create constructive feedback loops. If done well, I have a shareable representation of my thoughts that I can send out into the world and people can respond. Even for my most half-baked thoughts, this helps me create a feedback cycle to strengthen and fully flesh out that idea.
Quartz is designed first and foremost as a tool for publishing [digital gardens](https://jzhao.xyz/posts/networked-thought/) to the web. To me, digital gardening is not just passive knowledge collection. It’s a form of expression and sharing.
Quartz is designed first and foremost as a tool for publishing [digital gardens](https://jzhao.xyz/posts/networked-thought/) to the web. To me, digital gardening is not just passive knowledge collection. It’s a form of expression and sharing.
> “[One] who works with the door open gets all kinds of interruptions, but [they] also occasionally gets clues as to what the world is and what might be important.” — Richard Hamming

2
content/tags/component.md
View file

@ -2,4 +2,4 @@
title: Components
---
Want to create your own custom component? Check out the advanced guide on [[creating components]] for more information.
Want to create your own custom component? Check out the advanced guide on [[creating components]] for more information.