GitHub/quartz
1
0
Fork 2
mirror of https://github.com/jackyzha0/quartz.git synced 2026-03-24 15:05:42 -05:00
Code Issues Actions Packages Projects Releases Wiki Activity

pnpm run format

Browse Source
This commit is contained in:
semanticdata 2024-03-11 08:58:43 -05:00
parent 663b0673a3
commit 7eabbf2407
220 changed files with 12090 additions and 10521 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
.github/ISSUE_TEMPLATE/bug_report.md vendored
View File

@ -30,11 +30,11 @@ You can help speed up fixing the problem by either
**Desktop (please complete the following information):**
- Quartz Version: [e.g. v4.1.2]
- `node` Version: [e.g. v18.16]
- `npm` version: [e.g. v10.1.0]
- OS: [e.g. iOS]
- Browser [e.g. chrome, safari]
- Quartz Version: [e.g. v4.1.2]
- `node` Version: [e.g. v18.16]
- `npm` version: [e.g. v10.1.0]
- OS: [e.g. iOS]
- Browser [e.g. chrome, safari]
**Additional context**
Add any other context about the problem here.

8
.github/dependabot.yml vendored
View File

@ -5,7 +5,7 @@
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"

46
.github/workflows/build-only.yml vendored
View File

@ -1,32 +1,32 @@
name: Quartz - Build only
on:
workflow_dispatch:
pull_request:
# push:
# branches:
# - main
workflow_dispatch:
pull_request:
# push:
# branches:
# - main
permissions:
contents: read
pages: write
id-token: write
contents: read
pages: write
id-token: write
concurrency:
group: "pages"
cancel-in-progress: false
group: "pages"
cancel-in-progress: false
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # Fetch all history for git info
- uses: actions/setup-node@v4
with:
node-version: 18
- name: Install Dependencies
run: npm i
- name: Build Quartz
run: npx quartz build
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # Fetch all history for git info
- uses: actions/setup-node@v4
with:
node-version: 18
- name: Install Dependencies
run: npm i
- name: Build Quartz
run: npx quartz build

118
.github/workflows/ci.yaml vendored
View File

@ -1,71 +1,71 @@
name: Quartz - CI Test
on:
pull_request:
branches:
- v4
push:
branches:
- v4
pull_request:
branches:
- v4
push:
branches:
- v4
jobs:
build-and-test:
if: ${{ github.repository == 'jackyzha0/quartz' }}
strategy:
matrix:
os: [windows-latest, macos-latest, ubuntu-latest]
runs-on: ${{ matrix.os }}
permissions:
contents: write
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
build-and-test:
if: ${{ github.repository == 'jackyzha0/quartz' }}
strategy:
matrix:
os: [windows-latest, macos-latest, ubuntu-latest]
runs-on: ${{ matrix.os }}
permissions:
contents: write
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
- name: Setup Node
uses: actions/setup-node@v3
with:
node-version: 18
- name: Setup Node
uses: actions/setup-node@v3
with:
node-version: 18
- name: Cache dependencies
uses: actions/cache@v3
with:
path: ~/.npm
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
${{ runner.os }}-node-
- name: Cache dependencies
uses: actions/cache@v3
with:
path: ~/.npm
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
${{ runner.os }}-node-
- run: npm ci
- run: npm ci
- name: Check types and style
run: npm run check
- name: Check types and style
run: npm run check
- name: Test
run: npm test
- name: Test
run: npm test
- name: Ensure Quartz builds, check bundle info
run: npx quartz build --bundleInfo
- name: Ensure Quartz builds, check bundle info
run: npx quartz build --bundleInfo
publish-tag:
if: ${{ github.repository == 'jackyzha0/quartz' }}
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
- name: Setup Node
uses: actions/setup-node@v3
with:
node-version: 18
- name: Get package version
run: node -p -e '`PACKAGE_VERSION=${require("./package.json").version}`' >> $GITHUB_ENV
- name: Create release tag
uses: pkgdeps/git-tag-action@v2
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
github_repo: ${{ github.repository }}
version: ${{ env.PACKAGE_VERSION }}
git_commit_sha: ${{ github.sha }}
git_tag_prefix: "v"
publish-tag:
if: ${{ github.repository == 'jackyzha0/quartz' }}
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
- name: Setup Node
uses: actions/setup-node@v3
with:
node-version: 18
- name: Get package version
run: node -p -e '`PACKAGE_VERSION=${require("./package.json").version}`' >> $GITHUB_ENV
- name: Create release tag
uses: pkgdeps/git-tag-action@v2
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
github_repo: ${{ github.repository }}
version: ${{ env.PACKAGE_VERSION }}
git_commit_sha: ${{ github.sha }}
git_tag_prefix: "v"

80
.github/workflows/deploy-npm.yml vendored
View File

@ -1,52 +1,52 @@
name: Quartz - Deploy to GitHub Pages (npm)
on:
workflow_dispatch:
# push:
# branches:
# - main
workflow_dispatch:
# push:
# branches:
# - main
permissions:
contents: read
pages: write
id-token: write
contents: read
pages: write
id-token: write
concurrency:
group: "pages"
cancel-in-progress: false
group: "pages"
cancel-in-progress: false
defaults:
run:
shell: bash
run:
shell: bash
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0 # Fetch all history for git info
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 18
- name: Install Dependencies
run: npm i
- name: Build Quartz
run: npm run build
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: public
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0 # Fetch all history for git info
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 18
- name: Install Dependencies
run: npm i
- name: Build Quartz
run: npm run build
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: public
deploy:
needs: build
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
deploy:
needs: build
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4

102
.github/workflows/deploy-pnpm.yml vendored
View File

@ -1,63 +1,63 @@
name: Quartz - Deploy to GitHub Pages (pnpm)
on:
workflow_dispatch:
push:
branches:
- main
workflow_dispatch:
push:
branches:
- main
permissions:
contents: read
pages: write
id-token: write
contents: read
pages: write
id-token: write
concurrency:
group: "pages"
cancel-in-progress: false
group: "pages"
cancel-in-progress: false
defaults:
run:
shell: bash
run:
shell: bash
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0 # Fetch all history for git info
- name: Setup PNPM
uses: pnpm/action-setup@v3
with:
version: 8
- name: Get pnpm store directory
shell: bash
run: |
echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
- name: Setup pnpm cache
uses: actions/cache@v4
with:
path: ${{ env.STORE_PATH }}
key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
restore-keys: |
${{ runner.os }}-pnpm-store-
- name: Install dependencies
run: pnpm install
- name: Build Quartz Site
run: pnpm run build
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: public
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0 # Fetch all history for git info
- name: Setup PNPM
uses: pnpm/action-setup@v3
with:
version: 8
- name: Get pnpm store directory
shell: bash
run: |
echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
- name: Setup pnpm cache
uses: actions/cache@v4
with:
path: ${{ env.STORE_PATH }}
key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
restore-keys: |
${{ runner.os }}-pnpm-store-
- name: Install dependencies
run: pnpm install
- name: Build Quartz Site
run: pnpm run build
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: public
deploy:
needs: build
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Deploy to GitHub Pages
uses: actions/deploy-pages@v4
id: deployment
deploy:
needs: build
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Deploy to GitHub Pages
uses: actions/deploy-pages@v4
id: deployment

10
.prettierrc
View File

@ -1,7 +1,7 @@
{
"printWidth": 80,
"quoteProps": "as-needed",
"trailingComma": "all",
"tabWidth": 4,
"semi": false
"printWidth": 80,
"quoteProps": "as-needed",
"trailingComma": "all",
"tabWidth": 4,
"semi": false
}

42
README.md
View File

@ -15,21 +15,21 @@ It is powered by [Quartz](https://github.com/jackyzha0/quartz/) and [Obsidian](h
<details open>
<summary>Show/Hide</summary>
- [🌱 Forgetful Notes](#-forgetful-notes)
- [Contents](#contents)
- [Screenshots](#screenshots)
- [Full Width](#full-width)
- [Slim (light)](#slim-light)
- [Slim (dark)](#slim-dark)
- [Features](#features)
- [Background](#background)
- [Technology](#technology)
- [Useful Commands](#useful-commands)
- [Customization](#customization)
- [Stylesheets](#stylesheets)
- [Fonts](#fonts)
- [Folder Structure](#folder-structure)
- [License](#license)
- [🌱 Forgetful Notes](#-forgetful-notes)
- [Contents](#contents)
- [Screenshots](#screenshots)
- [Full Width](#full-width)
- [Slim (light)](#slim-light)
- [Slim (dark)](#slim-dark)
- [Features](#features)
- [Background](#background)
- [Technology](#technology)
- [Useful Commands](#useful-commands)
- [Customization](#customization)
- [Stylesheets](#stylesheets)
- [Fonts](#fonts)
- [Folder Structure](#folder-structure)
- [License](#license)
</details>
@ -54,12 +54,12 @@ It is powered by [Quartz](https://github.com/jackyzha0/quartz/) and [Obsidian](h
## Features
- Fast Natural-Language Search
- Bidirectional Backlinks
- Floating Link Previews
- Admonition-style Callouts
- Markdown Links and Wikilinks Support
- Latex Support
- Fast Natural-Language Search
- Bidirectional Backlinks
- Floating Link Previews
- Admonition-style Callouts
- Markdown Links and Wikilinks Support
- Latex Support
## Background

8
content/Atomic Notes.md
View File

@ -18,10 +18,10 @@ Tags: #exercise #health #wellness
Regular exercise confers numerous health benefits, including:
- Improved cardiovascular health
- Increased strength and flexibility
- Weight management
- Reduced risk of chronic diseases
- Improved cardiovascular health
- Increased strength and flexibility
- Weight management
- Reduced risk of chronic diseases
It is recommended to engage in at least 150 minutes of moderate-intensity exercise or 75 minutes of vigorous exercise per week. Exercise should be a combination of aerobic activity, strength training, and flexibility exercises.

16
content/Aurora Borealis Sighting.md
View File

@ -35,10 +35,10 @@ Viewing the aurora depends on four important factors.
If the geomagnetic field is active, then the aurora will be brighter and further from the poles. Geomagnetic activity is driven by solar activity and solar coronal holes and thus it waxes and wanes with time. The level of geomagnetic activity is indicated by the planetary K index or Kp. The Kp index ranges from 0 to 9.
- For Kp in the range 0 to 2, the aurora will be far north, quite dim in intensity, and not very active.
- For Kp in the range of 3 to 5, the aurora will move further from the poles, it will become brighter and there will be more auroral activity (motion and formations). If you are in the right place, these aurora can be quite pleasing to look at.
- For Kp in the range 6 to 7, the aurora will move even further from the poles and will become quite bright and active. At this geomagnetic activity level, it might be possible to see the aurora from the northern edge of the United States.
- For Kp in the range 8 to 9, the aurora will move even further towards the equator and it will become very bright and very active. These are the events that create the best aurora and the extended auroral oval will be observable by the most people. At these levels, aurora may be seen directly overhead from the northern states of the USA.
- For Kp in the range 0 to 2, the aurora will be far north, quite dim in intensity, and not very active.
- For Kp in the range of 3 to 5, the aurora will move further from the poles, it will become brighter and there will be more auroral activity (motion and formations). If you are in the right place, these aurora can be quite pleasing to look at.
- For Kp in the range 6 to 7, the aurora will move even further from the poles and will become quite bright and active. At this geomagnetic activity level, it might be possible to see the aurora from the northern edge of the United States.
- For Kp in the range 8 to 9, the aurora will move even further towards the equator and it will become very bright and very active. These are the events that create the best aurora and the extended auroral oval will be observable by the most people. At these levels, aurora may be seen directly overhead from the northern states of the USA.
It should be noted that the relationship between Kp and auroral latitude are approximate and represent averages. There will be times when these relationships do not hold up exactly.
@ -74,7 +74,7 @@ Kp is Planetary K Index (0–9)
## Additional Resources
- [Aurora Forecast](https://www.gi.alaska.edu/monitors/aurora-forecast)
- [Aurora Dashboard](https://www.swpc.noaa.gov/content/aurora-dashboard-experimental)
- [Space Weather Phenomena](https://www.swpc.noaa.gov/phenomena)
- [Dive Deeper Into the Science of the Aurora](https://www.swpc.noaa.gov/content/aurora-tutorial)
- [Aurora Forecast](https://www.gi.alaska.edu/monitors/aurora-forecast)
- [Aurora Dashboard](https://www.swpc.noaa.gov/content/aurora-dashboard-experimental)
- [Space Weather Phenomena](https://www.swpc.noaa.gov/phenomena)
- [Dive Deeper Into the Science of the Aurora](https://www.swpc.noaa.gov/content/aurora-tutorial)

12
content/Books.md
View File

@ -11,11 +11,11 @@ Non-inclusive, non-comprehensive list of books I've read.
## John Green
- [An Abundance of Katherines](https://www.librarything.com/work/2569212)
- [Looking for Alaska](https://www.librarything.com/work/30329846)
- [Paper Towns](https://www.librarything.com/work/5105584)
- [The Fault in Our Stars](https://www.librarything.com/work/11456497)
- [Will Grayson, Will Grayson](https://www.librarything.com/work/8463786)
- [An Abundance of Katherines](https://www.librarything.com/work/2569212)
- [Looking for Alaska](https://www.librarything.com/work/30329846)
- [Paper Towns](https://www.librarything.com/work/5105584)
- [The Fault in Our Stars](https://www.librarything.com/work/11456497)
- [Will Grayson, Will Grayson](https://www.librarything.com/work/8463786)
## Janet Evanovich
@ -59,4 +59,4 @@ Non-inclusive, non-comprehensive list of books I've read.
## Robert Pinsky
- [The Sounds of Poetry: A Brief Guide](https://www.librarything.com/work/121193)
- [The Sounds of Poetry: A Brief Guide](https://www.librarything.com/work/121193)

52
content/CSS.md
View File

@ -31,9 +31,9 @@ All _mobile-first-designs_ media queries and 1 _desktop-first-design_ media quer
```scss
@mixin screen-min($min) {
@media (min-width: $min) {
@content;
}
@media (min-width: $min) {
@content;
}
}
```
@ -41,9 +41,9 @@ All _mobile-first-designs_ media queries and 1 _desktop-first-design_ media quer
```scss
@mixin screen-max($max) {
@media (max-width: $max - 1) {
@content;
}
@media (max-width: $max - 1) {
@content;
}
}
```
@ -51,9 +51,9 @@ All _mobile-first-designs_ media queries and 1 _desktop-first-design_ media quer
```scss
@mixin screen-minmax($min, $max) {
@media (min-width: $min) and (max-width: $max - 1) {
@content;
}
@media (min-width: $min) and (max-width: $max - 1) {
@content;
}
}
```
@ -64,22 +64,22 @@ All _mobile-first-designs_ media queries and 1 _desktop-first-design_ media quer
------------------------------------------------------------------
.container {
margin: 0 auto;
width: 100%;
@include screen-min(768px) {
max-width: 750px;
}
@include screen-min(992px) {
max-width: 970px;
}
@include screen-min(1200px) {
max-width: 1170px;
}
@include screen-min(1400px) {
max-width: 1370px;
}
@include screen-min(1600px) {
max-width: 1570px;
}
margin: 0 auto;
width: 100%;
@include screen-min(768px) {
max-width: 750px;
}
@include screen-min(992px) {
max-width: 970px;
}
@include screen-min(1200px) {
max-width: 1170px;
}
@include screen-min(1400px) {
max-width: 1370px;
}
@include screen-min(1600px) {
max-width: 1570px;
}
}
```

6
content/Digital Garden.md
View File

@ -17,6 +17,6 @@ Digital Gardens are explorable rather than structured as a strictly linear strea
## Kinds of Notes
- 🌱 *Seedlings* for very rough and early ideas.
- 🌿 *Budding* for work I've cleaned up and clarified.
- 🌳 *Evergreen* for work that is reasonably complete (though I still tend these over time).
- 🌱 *Seedlings* for very rough and early ideas.
- 🌿 *Budding* for work I've cleaned up and clarified.
- 🌳 *Evergreen* for work that is reasonably complete (though I still tend these over time).

92
content/Emmet Cheat Sheet.md
View File

@ -4,8 +4,8 @@ updated: 2024-02-08
compartir: true
---
- [Documentation](https://docs.emmet.io/)
- [Documentation](https://code.visualstudio.com/docs/editor/emmet) for Emmet in VS Code
- [Documentation](https://docs.emmet.io/)
- [Documentation](https://code.visualstudio.com/docs/editor/emmet) for Emmet in VS Code
## Notes on Abbreviation Formatting
@ -13,8 +13,8 @@ When you get familiar with Emmet's abbreviations syntax, you may want to use som
This is why Emmet needs some indicators (like spaces) where it should stop parsing to not expand anything that you don't need. If you're still thinking that such formatting is required for complex abbreviations to make them more readable:
- Abbreviations are not a template language, they don't have to be "readable", they have to be "quickly expandable and removable".
- You don't really need to write complex abbreviations. Stop thinking that "typing" is the slowest process in web-development. You'll quickly find out that constructing a single complex abbreviation is much slower and error-prone than constructing and typing a few short ones.
- Abbreviations are not a template language, they don't have to be "readable", they have to be "quickly expandable and removable".
- You don't really need to write complex abbreviations. Stop thinking that "typing" is the slowest process in web-development. You'll quickly find out that constructing a single complex abbreviation is much slower and error-prone than constructing and typing a few short ones.
## HTML + CSS Emmet Short Guide
@ -28,9 +28,9 @@ div>ul>li
```html
<div>
<ul>
<li></li>
</ul>
<ul>
<li></li>
</ul>
</div>
```
@ -76,7 +76,7 @@ div+div>p>span+em^^^bq
```html
<div></div>
<div>
<p><span></span><em></em></p>
<p><span></span><em></em></p>
</div>
<blockquote></blockquote>
```
@ -89,11 +89,11 @@ ul>li*5
```html
<ul>
<li></li>
<li></li>
<li></li>
<li></li>
<li></li>
<li></li>
<li></li>
<li></li>
<li></li>
<li></li>
</ul>
```
@ -105,15 +105,15 @@ div>(header>ul>li*2>a)+footer>p
```html
<div>
<header>
<ul>
<li><a href=""></a></li>
<li><a href=""></a></li>
</ul>
</header>
<footer>
<p></p>
</footer>
<header>
<ul>
<li><a href=""></a></li>
<li><a href=""></a></li>
</ul>
</header>
<footer>
<p></p>
</footer>
</div>
```
@ -123,17 +123,17 @@ div>(header>ul>li*2>a)+footer>p
```html
<div>
<dl>
<dt></dt>
<dd></dd>
<dt></dt>
<dd></dd>
<dt></dt>
<dd></dd>
</dl>
<dl>
<dt></dt>
<dd></dd>
<dt></dt>
<dd></dd>
<dt></dt>
<dd></dd>
</dl>
</div>
<footer>
<p></p>
<p></p>
</footer>
```
@ -167,11 +167,11 @@ ul>li.item$*5
```html
<ul>
<li class="item1"></li>
<li class="item2"></li>
<li class="item3"></li>
<li class="item4"></li>
<li class="item5"></li>
<li class="item1"></li>
<li class="item2"></li>
<li class="item3"></li>
<li class="item4"></li>
<li class="item5"></li>
</ul>
```
@ -181,11 +181,11 @@ ul>li.item$$$*5
```html
<ul>
<li class="item001"></li>
<li class="item002"></li>
<li class="item003"></li>
<li class="item004"></li>
<li class="item005"></li>
<li class="item001"></li>
<li class="item002"></li>
<li class="item003"></li>
<li class="item004"></li>
<li class="item005"></li>
</ul>
```
@ -223,11 +223,11 @@ ul>li.item$@-3*5
```html
<ul>
<li class="item7"></li>
<li class="item6"></li>
<li class="item5"></li>
<li class="item4"></li>
<li class="item3"></li>
<li class="item7"></li>
<li class="item6"></li>
<li class="item5"></li>
<li class="item4"></li>
<li class="item3"></li>
</ul>
```

64
content/Espanso Cheat Sheet.md
View File

@ -12,21 +12,21 @@ Visit the [Documentation](https://espanso.org/docs/get-started/).
## Features
- Works on **Windows**, **macOS** and **Linux**
- Works with almost **any program**
- Works with **Emojis** 😄
- Works with **Images**
- Includes a powerful **Search Bar** 🔎
- **Date** expansion support
- **Custom scripts** support
- **Shell commands** support
- **App-specific** configurations
- Support [Forms](https://espanso.org/docs/matches/forms/)
- Expandable with **packages**
- Built-in **package manager** for [espanso hub](https://hub.espanso.org/)
- File based configuration
- Support Regex triggers
- Experimental Wayland support
- Works on **Windows**, **macOS** and **Linux**
- Works with almost **any program**
- Works with **Emojis** 😄
- Works with **Images**
- Includes a powerful **Search Bar** 🔎
- **Date** expansion support
- **Custom scripts** support
- **Shell commands** support
- **App-specific** configurations
- Support [Forms](https://espanso.org/docs/matches/forms/)
- Expandable with **packages**
- Built-in **package manager** for [espanso hub](https://hub.espanso.org/)
- File based configuration
- Support Regex triggers
- Experimental Wayland support
## Static Matches
@ -52,10 +52,10 @@ Visit the [Documentation](https://espanso.org/docs/get-started/).
- trigger: "now"
replace: "It's {{mytime}}"
vars:
- name: mytime
type: date
params:
format: "%H:%M"
- name: mytime
type: date
params:
format: "%H:%M"
```
### Preconfigured Choices
@ -76,8 +76,8 @@ Visit the [Documentation](https://espanso.org/docs/get-started/).
- name: getip
type: shell
params:
cmd: "curl ifconfig.me"
shell: cmd
cmd: "curl ifconfig.me"
shell: cmd
```
## Global Variables
@ -86,14 +86,14 @@ Visit the [Documentation](https://espanso.org/docs/get-started/).
```yml
global_vars:
- name: "global1"
type: "shell"
params:
cmd: "echo global var"
- name: "greet"
type: "echo"
params:
echo: "Hey"
- name: "global1"
type: "shell"
params:
cmd: "echo global var"
- name: "greet"
type: "echo"
params:
echo: "Hey"
```
### Usage
@ -122,9 +122,9 @@ global_vars:
word: true
```
- If you write `alh`, the match will be expanded to `although`.
- If you write `Alh`, the match will be expanded to `Although`.
- If you write `ALH`, the match will be expanded to `ALTHOUGH`.
- If you write `alh`, the match will be expanded to `although`.
- If you write `Alh`, the match will be expanded to `Although`.
- If you write `ALH`, the match will be expanded to `ALTHOUGH`.
## Cursor Hints

4
content/Guitar.md
View File

@ -42,5 +42,5 @@ You can then finish out the riff by grabbing the 6th fret on the 6th string with
## Sources
- [ultimate-guitar.com](https://tabs.ultimate-guitar.com/tab/metallica/enter-sandman-tabs-8595)
- [guitarlessons.org](https://www.guitarlessons.org/lessons/read-guitar-tabs/)
- [ultimate-guitar.com](https://tabs.ultimate-guitar.com/tab/metallica/enter-sandman-tabs-8595)
- [guitarlessons.org](https://www.guitarlessons.org/lessons/read-guitar-tabs/)

28
content/Inspirations.md
View File

@ -9,20 +9,20 @@ _These are people and projects have resonated with me. Inspiring me to do things
## People Who Inspire Me
- [Andy Bell](https://andy-bell.co.uk/)
- [Anjana Vakil](https://anjana.dev/)
- [Derek Sivers](https://sive.rs/)
- [Drew DeVault](https://drewdevault.com/)
- [Eric Bower](https://erock.prose.sh/)
- [Herman Martinus](https://herman.bearblog.dev/)
- [Jacky Zha](https://github.com/jackyzha0?tab=repositories)
- [Andy Bell](https://andy-bell.co.uk/)
- [Anjana Vakil](https://anjana.dev/)
- [Derek Sivers](https://sive.rs/)
- [Drew DeVault](https://drewdevault.com/)
- [Eric Bower](https://erock.prose.sh/)
- [Herman Martinus](https://herman.bearblog.dev/)
- [Jacky Zha](https://github.com/jackyzha0?tab=repositories)
## Projects That Inspire Me
- [Anemone](https://github.com/Speyll/anemone) – Clean Zola theme. Integrates public journals.
- [Bearblog](https://github.com/HermanMartinus/bearblog) – Blogging Platform.
- [Duotone Theme](https://github.com/Hussseinkizz/duotone-theme-v2-official) – VS Code Theme (Supports Ligaments).
- [Fira Code iScript](https://github.com/kencrocken/FiraCodeiScript) – Font Family (incl. ligations and cursive italics).
- [mataroa](https://github.com/mataroa-blog/mataroa) – Minimal Blogging Platform.
- [SorryTennesee](https://github.com/vpicone/SorryTennesee) – Remove Tennesee from drop-down menus.
- [wttr.in](https://github.com/chubin/wttr.in) – Plain Text Weather.
- [Anemone](https://github.com/Speyll/anemone) – Clean Zola theme. Integrates public journals.
- [Bearblog](https://github.com/HermanMartinus/bearblog) – Blogging Platform.
- [Duotone Theme](https://github.com/Hussseinkizz/duotone-theme-v2-official) – VS Code Theme (Supports Ligaments).
- [Fira Code iScript](https://github.com/kencrocken/FiraCodeiScript) – Font Family (incl. ligations and cursive italics).
- [mataroa](https://github.com/mataroa-blog/mataroa) – Minimal Blogging Platform.
- [SorryTennesee](https://github.com/vpicone/SorryTennesee) – Remove Tennesee from drop-down menus.
- [wttr.in](https://github.com/chubin/wttr.in) – Plain Text Weather.

52
content/Markdown Showcase.md
View File

@ -76,22 +76,22 @@ In arcu magna, aliquet vel pretium et, molestie et arcu. Mauris lobortis nulla e
In arcu magna, aliquet vel pretium et, molestie et arcu. Mauris lobortis nulla et felis ullamcorper bibendum. Phasellus et hendrerit mauris.
- List item
- Another item
- And another item
- List item
- Another item
- And another item
### Nested List
In arcu magna, aliquet vel pretium et, molestie et arcu. Mauris lobortis nulla et felis ullamcorper bibendum. Phasellus et hendrerit mauris.
- Item
1. First Sub-item
2. Second Sub-item
- Item
1. First Sub-item
2. Second Sub-item
1. Numbered Item
2. Another one
1. Sub-item
- Unordered again
1. Sub-item
- Unordered again
## Code
@ -103,26 +103,26 @@ Let us use some `inline code` and check out how it `looks`. Here's some `more`.
```html
<html>
<head>
<div style="background-color: #333;">
<a href="https://example.com/">Example</a>
</div>
</head>
<head>
<div style="background-color: #333;">
<a href="https://example.com/">Example</a>
</div>
</head>
</html>
```
```css
.niceClass {
color: blue;
background-color: #fff;
color: blue;
background-color: #fff;
}
```
```js
// Javascript code with syntax highlighting.
var fun = function lang(l) {
dateformat.i18n = require("./lang/" + l)
return true
dateformat.i18n = require("./lang/" + l)
return true
}
```
@ -167,16 +167,16 @@ In arcu magna, aliquet vel pretium et, molestie et arcu. Mauris lobortis nulla e
## Tasks and Custom Todos
- [ ] Pending Task
- [x] Completed Task
- [ ] Pending Task
- [x] Completed Task
* [-] Won't Do Task
* [/] In Progress Task
* [*] You are a star.
* [!] Exclamation Mark!
* [?] Question Mark?
* [<] Scheduled Task
* [>] Forwarded Task
* [-] Won't Do Task
* [/] In Progress Task
* [*] You are a star.
* [!] Exclamation Mark!
* [?] Question Mark?
* [<] Scheduled Task
* [>] Forwarded Task
## Images

12
content/Meta.md
View File

@ -24,12 +24,12 @@ The [source code](https://github.com/semanticdata/forgetful-notes) is hosted in
## Features
- Fast Natural-Language Search
- Bidirectional Backlinks
- Floating Link Previews
- Admonition-style Callouts
- Markdown Links and Wikilinks Support
- Latex Support
- Fast Natural-Language Search
- Bidirectional Backlinks
- Floating Link Previews
- Admonition-style Callouts
- Markdown Links and Wikilinks Support
- Latex Support
## File Structure

8
content/Move Your Body.md
View File

@ -7,9 +7,9 @@ tags: [stub]
Move your body every day. Benefits include:
- Improved sleep quality.
- Less risk of chronic disease.
- Increased productivity.
- Reduced anxiety.
- Improved sleep quality.
- Less risk of chronic disease.
- Increased productivity.
- Reduced anxiety.
The "every day" part is important, because [[./Consistency|Consistency]] is key to most things worth doing.

34
content/Outlines.md
View File

@ -10,29 +10,29 @@ Learning how to write with brevity (short-form), how to write long-form, how to
## Questions to Be Answered by Post
- What is an outline
- Why should I use one
- How do I make one
- What is an outline
- Why should I use one
- How do I make one
## What Needs to Be Mentioned
- Essential tips. Must do when creating an outline
- Provide an example of an outline
- Outlines are not barriers. They are a tool to structure your writing.
- Essential tips. Must do when creating an outline
- Provide an example of an outline
- Outlines are not barriers. They are a tool to structure your writing.
## Logical Order
- Define the purpose of the essay
- Define the audience of your essay
- Write your thesis statement (consequential thesis statement)
- Brainstorm all of the ideas you want to include in your essay
- Group related ideas
- Label your ideas with headings and sub-headings
- Write a draft of your outline
- Write an intro and conclusion. Purposely last.
- Define the purpose of the essay
- Define the audience of your essay
- Write your thesis statement (consequential thesis statement)
- Brainstorm all of the ideas you want to include in your essay
- Group related ideas
- Label your ideas with headings and sub-headings
- Write a draft of your outline
- Write an intro and conclusion. Purposely last.
## Links to Reference Material
- [How to Outline // Purdue Writing Lab](https://owl.purdue.edu/owl/general_writing/the_writing_process/developing_an_outline/how_to_outline.html)
- [How to Write an Outline: 4 Ways to Organize Your Thoughts | Grammarly](https://www.grammarly.com/blog/how-to-write-outline/)
- [How to Write a Blog Post Outline: A Simple Formula to Follow](https://blog.hubspot.com/marketing/how-to-write-blog-post-outline)
- [How to Outline // Purdue Writing Lab](https://owl.purdue.edu/owl/general_writing/the_writing_process/developing_an_outline/how_to_outline.html)
- [How to Write an Outline: 4 Ways to Organize Your Thoughts | Grammarly](https://www.grammarly.com/blog/how-to-write-outline/)
- [How to Write a Blog Post Outline: A Simple Formula to Follow](https://blog.hubspot.com/marketing/how-to-write-blog-post-outline)

30
content/Poetry.md
View File

@ -10,9 +10,9 @@ enableToc: true
Poetry is a broad literary category that covers everything from bawdy limericks to unforgettable song lyrics to the sentimental couplets inside greeting cards. A **poem** is a singular piece of poetry.
- Show, don't tell. The goal is to provoke an emotion in the reader.
- Less can be more. While it's perfectly acceptable to write long, flowery verse, using simple, concise language is also powerful. Word choice and poem length are up to you.
- It's OK to break grammatical rules when doing so helps you express yourself.
- Show, don't tell. The goal is to provoke an emotion in the reader.
- Less can be more. While it's perfectly acceptable to write long, flowery verse, using simple, concise language is also powerful. Word choice and poem length are up to you.
- It's OK to break grammatical rules when doing so helps you express yourself.
The key elements that distinguish poetry from other kinds of literature include sound, rhythm, rhyme, and format. One thing poetry has in common with other kinds of literature is its use of literary devices. Poems, like other kinds of creative writing, often make use of allegories and other kinds of figurative language to communicate themes.
@ -70,15 +70,15 @@ A **stanza** is the poetic equivalent of a paragraph. It's a group of lines that
## Literary Devices
- Figurative language
- Juxtaposition
- Onomatopoeia
- Simile
- Metaphor
- Puns
- Chiasmus
- Imagery
- Hyperbole
- Mood
- Motif
- Personification
- Figurative language
- Juxtaposition
- Onomatopoeia
- Simile
- Metaphor
- Puns
- Chiasmus
- Imagery
- Hyperbole
- Mood
- Motif
- Personification

40
content/SSD NVMe Comparison.md
View File

@ -12,23 +12,23 @@ tags: [archived]
### 3D NAND
- The most basic of modern SSD technologies. Great for throwing on cheap systems, home servers, anything non-critical really.
- It is not recommended to host your Operating System on 3D NAND, or QLC.
- The most basic of modern SSD technologies. Great for throwing on cheap systems, home servers, anything non-critical really.
- It is not recommended to host your Operating System on 3D NAND, or QLC.
### Quad Level Cell (QLC)
- QLC (Quad Level Cell) is cheaper to manufacture than TLC (Triple Level Cell).
- QLC is much slower and less durable to constant writing than TLC.
- It is not recommended to host your Operating System on 3D NAND, or QLC.
- QLC (Quad Level Cell) is cheaper to manufacture than TLC (Triple Level Cell).
- QLC is much slower and less durable to constant writing than TLC.
- It is not recommended to host your Operating System on 3D NAND, or QLC.
### Triple Level Cell (TLC)
- TLC is more reliable when compared to QLC.
- MLC is a Triple Level Cell based Samsung technology.
- TLC is more reliable when compared to QLC.
- MLC is a Triple Level Cell based Samsung technology.
### Multi Level Cell (MLC)
- MLC is a Triple Level Cell based Samsung technology.
- MLC is a Triple Level Cell based Samsung technology.
Let's break it down:
@ -42,23 +42,23 @@ Let's break it down:
### Storage
- 1 point per GB
- Less accurate the bigger the SSD
- 3 TB and higher drives scale exp/log instead of linearly.
- 1 point per GB
- Less accurate the bigger the SSD
- 3 TB and higher drives scale exp/log instead of linearly.
### Price
Based on price per $1.
Selected $0.10 as the baseline after averaging some calculations.
- 1 point for every $0.01 / GB below $0.10
- 1 point for every $0.01 / GB below $0.10
### Technology Coefficient
- 3D NAND Coefficient = 0.5 (Big Penalty)
- QLC Coefficient = 0.75 (Small Penalty)
- TLC Coefficient = 1.0 (No Change)
- MLC V-NAND coefficient = 1.25 (Small Advantage)
- 3D NAND Coefficient = 0.5 (Big Penalty)
- QLC Coefficient = 0.75 (Small Penalty)
- TLC Coefficient = 1.0 (No Change)
- MLC V-NAND coefficient = 1.25 (Small Advantage)
## NVMe M.2 2280 M Key
@ -136,7 +136,7 @@ Selected $0.10 as the baseline after averaging some calculations.
## Conclusions
- Cheap system? Get **any** of these.
- Secondary drive? Get any **QLC** or better.
- OS Drive? Get any **TLC** or better.
- Extra cash? Premium for reliability? Get any **Samsung** from the list.
- Cheap system? Get **any** of these.
- Secondary drive? Get any **QLC** or better.
- OS Drive? Get any **TLC** or better.
- Extra cash? Premium for reliability? Get any **Samsung** from the list.

5
content/Sans-serif.md
View File

@ -12,6 +12,7 @@ In typography and lettering, a "sans-serif", "sans serif", "gothic", or simply "
## Font Family in CSS
```css
font-family: -apple-system, BlinkMacSystemFont, "Avenir Next", Avenir, "Nimbus Sans L", Roboto,
Noto, "Segoe UI", Arial, Helvetica, "Helvetica Neue", sans-serif;
font-family: -apple-system, BlinkMacSystemFont, "Avenir Next", Avenir,
"Nimbus Sans L", Roboto, Noto, "Segoe UI", Arial, Helvetica,
"Helvetica Neue", sans-serif;
```

14
content/Scope of Work.md
View File

@ -10,10 +10,10 @@ You might create an SOW when multiple parties are working together on the projec
Usually, a scope of work has these standard components:
- Project goals: This includes all goals intended for the team to reach as the project progresses, as well as when it completes.
- Timeline: This includes the exact timeframe for the project's beginning and end, including when specific tasks should start and complete.
- Expected results: This includes specific outcomes intended to take place by the completion of the project.
- Deliverables: This includes the exact product or products the project should deliver by its completion.
- Conditions: This includes any stipulations the team should abide by or work under or requirements to meet.
- Financial information: This includes accounting data, such as how much the project may cost to complete, how much each team member is going to earn and how and when they're going to be paid.
- Management: This includes information regarding administrative details, such as who's responsible for approving financial decisions or who can agree to specific terms.
- Project goals: This includes all goals intended for the team to reach as the project progresses, as well as when it completes.
- Timeline: This includes the exact timeframe for the project's beginning and end, including when specific tasks should start and complete.
- Expected results: This includes specific outcomes intended to take place by the completion of the project.
- Deliverables: This includes the exact product or products the project should deliver by its completion.
- Conditions: This includes any stipulations the team should abide by or work under or requirements to meet.
- Financial information: This includes accounting data, such as how much the project may cost to complete, how much each team member is going to earn and how and when they're going to be paid.
- Management: This includes information regarding administrative details, such as who's responsible for approving financial decisions or who can agree to specific terms.

4
content/Serif.md
View File

@ -12,6 +12,6 @@ In typography, a serif (/ˈsɛrɪf/) is a small line or stroke regularly attache
## Font Family in CSS
```css
font-family: Constantia, "Lucida Bright", Lucidabright, "Lucida Serif", Lucida, "DejaVu Serif",
"Bitstream Vera Serif", "Liberation Serif", Georgia, serif;
font-family: Constantia, "Lucida Bright", Lucidabright, "Lucida Serif", Lucida,
"DejaVu Serif", "Bitstream Vera Serif", "Liberation Serif", Georgia, serif;
```

6
content/Static Site Generators.md
View File

@ -9,6 +9,6 @@ Static site generators (SSGs) are engines that use text input files (such as [[.
Popular choices in SSGs include:
- [Jekyll](https://jekyllrb.com/)
- [Hugo](https://gohugo.io/)
- [[./Zola|Zola]]
- [Jekyll](https://jekyllrb.com/)
- [Hugo](https://gohugo.io/)
- [[./Zola|Zola]]

60
content/Tools.md
View File

@ -9,47 +9,47 @@ A non-comprehensive list of the hardware and software I use on a day-to-day basi
## Hardware
- [Lenovo Thinkpad T480s](https://www.notebookcheck.net/Lenovo-ThinkPad-T480s-20L8S02D00.294734.0.html) – Laptop
- [Logi M575](https://www.logitech.com/en-us/products/mice/m575-ergo-wireless-trackball) – Mouse
- [Skullcandy Crusher ANC](https://info.skullcandy.com/Support?Dest=hc%2Fen-us%2Farticles%2F360034534854-Crusher-ANC-Wireless) – Headphones
- [Lenovo Thinkpad T480s](https://www.notebookcheck.net/Lenovo-ThinkPad-T480s-20L8S02D00.294734.0.html) – Laptop
- [Logi M575](https://www.logitech.com/en-us/products/mice/m575-ergo-wireless-trackball) – Mouse
- [Skullcandy Crusher ANC](https://info.skullcandy.com/Support?Dest=hc%2Fen-us%2Farticles%2F360034534854-Crusher-ANC-Wireless) – Headphones
## Software
### Daily Drivers
- [Obsidian](https://obsidian.md/) – Markdown Text Editor
- [Visual Studio Code](https://code.visualstudio.com/) – Code Editor
- [Raindrop](https://raindrop.io/) – Bookmarks Manager
- [Syncthing](https://github.com/syncthing/syncthing) – Open source continuous file synchronization.
- [Espanso](https://github.com/espanso/espanso) – Cross-platform text expander written in Rust.
- [Obsidian](https://obsidian.md/) – Markdown Text Editor
- [Visual Studio Code](https://code.visualstudio.com/) – Code Editor
- [Raindrop](https://raindrop.io/) – Bookmarks Manager
- [Syncthing](https://github.com/syncthing/syncthing) – Open source continuous file synchronization.
- [Espanso](https://github.com/espanso/espanso) – Cross-platform text expander written in Rust.
### Notable Visual Studio Code Extensions
- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) – Opinionated Code Formatter.
- [Markdown All in One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one) – Markdown Support.
- [Markwhen](https://marketplace.visualstudio.com/items?itemName=Markwhen.markwhen) – View/Edit Markwhen documents.
- [Markmap](https://marketplace.visualstudio.com/items?itemName=gera2ld.markmap-vscode) – Preview markdown files as Markmap.
- [GistPad](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.gistfs) – Edit GitHub Gists and Repositories remotely.
- [Project Manager](https://marketplace.visualstudio.com/items?itemName=alefragnani.project-manager) – Easily change current Project/Folder.
- [shift shift](https://marketplace.visualstudio.com/items?itemName=ahgood.shift-shift) – Provides shortcuts for `shift + shift` and `ctrl + ctrl`.
- [CSS Peek](https://marketplace.visualstudio.com/items?itemName=pranaygp.vscode-css-peek) – Introduces `Go To Definition` and `Go To Symbol in Workspace` support.
- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) – Opinionated Code Formatter.
- [Markdown All in One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one) – Markdown Support.
- [Markwhen](https://marketplace.visualstudio.com/items?itemName=Markwhen.markwhen) – View/Edit Markwhen documents.
- [Markmap](https://marketplace.visualstudio.com/items?itemName=gera2ld.markmap-vscode) – Preview markdown files as Markmap.
- [GistPad](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.gistfs) – Edit GitHub Gists and Repositories remotely.
- [Project Manager](https://marketplace.visualstudio.com/items?itemName=alefragnani.project-manager) – Easily change current Project/Folder.
- [shift shift](https://marketplace.visualstudio.com/items?itemName=ahgood.shift-shift) – Provides shortcuts for `shift + shift` and `ctrl + ctrl`.
- [CSS Peek](https://marketplace.visualstudio.com/items?itemName=pranaygp.vscode-css-peek) – Introduces `Go To Definition` and `Go To Symbol in Workspace` support.
### Notable Obsidian Extensions
- [Omnisearch](https://github.com/scambier/obsidian-omnisearch) – Better Search Engine.
- [Obsidian Git](https://github.com/denolehov/obsidian-git) – Run Git commands from Obsidian.
- [Natural Language Dates](https://github.com/argenos/nldates-obsidian) – Adds `@today` format to dates.
- [Linter](https://github.com/platers/obsidian-linter) – Customizable Markdown Linter similar to Prettier.
- [Editor Shortcuts](https://github.com/timhor/obsidian-editor-shortcuts) – Adds shortcuts usually found in Code Editors.
- [GitHub Publisher](https://github.com/ObsidianPublisher/obsidian-github-publisher) – Publish your notes to a preconfigured repository.
- [DoubleShift](https://github.com/Qwyntex/doubleshift) – Provides shortcuts for `shift + shift` and `ctrl + ctrl`.
- [Contextual Typography](https://github.com/mgmeyers/obsidian-contextual-typography) – Allows for custom insertion of code at the block level.
- [Omnisearch](https://github.com/scambier/obsidian-omnisearch) – Better Search Engine.
- [Obsidian Git](https://github.com/denolehov/obsidian-git) – Run Git commands from Obsidian.
- [Natural Language Dates](https://github.com/argenos/nldates-obsidian) – Adds `@today` format to dates.
- [Linter](https://github.com/platers/obsidian-linter) – Customizable Markdown Linter similar to Prettier.
- [Editor Shortcuts](https://github.com/timhor/obsidian-editor-shortcuts) – Adds shortcuts usually found in Code Editors.
- [GitHub Publisher](https://github.com/ObsidianPublisher/obsidian-github-publisher) – Publish your notes to a preconfigured repository.
- [DoubleShift](https://github.com/Qwyntex/doubleshift) – Provides shortcuts for `shift + shift` and `ctrl + ctrl`.
- [Contextual Typography](https://github.com/mgmeyers/obsidian-contextual-typography) – Allows for custom insertion of code at the block level.
### Notable Windows Programs
- [Everything](https://www.voidtools.com/) – Locate files and folders by name instantly.
- [QuickLook](https://github.com/QL-Win/QuickLook) – Bring macOS "Quick Look" feature to Windows.
- [PowerToys](https://github.com/microsoft/PowerToys) – Windows system utilities to maximize productivity.
- [EarTrumpet](https://github.com/File-New-Project/EarTrumpet) – Volume control, multi-channel discovery, default playback device management.
- [PDFsam](https://github.com/torakiki/pdfsam) – Desktop application to split, merge, mix, rotate PDF files and extract pages.
- [TaskbarX](https://github.com/ChrisAnd1998/TaskbarX) – Center Windows taskbar icons with a variety of animations and options.
- [Everything](https://www.voidtools.com/) – Locate files and folders by name instantly.
- [QuickLook](https://github.com/QL-Win/QuickLook) – Bring macOS "Quick Look" feature to Windows.
- [PowerToys](https://github.com/microsoft/PowerToys) – Windows system utilities to maximize productivity.
- [EarTrumpet](https://github.com/File-New-Project/EarTrumpet) – Volume control, multi-channel discovery, default playback device management.
- [PDFsam](https://github.com/torakiki/pdfsam) – Desktop application to split, merge, mix, rotate PDF files and extract pages.
- [TaskbarX](https://github.com/ChrisAnd1998/TaskbarX) – Center Windows taskbar icons with a variety of animations and options.

2
content/Words.md
View File

@ -63,7 +63,7 @@ compartir: true
### Dogfooding (slang)
- _From [Wikipedia](https://en.wikipedia.org/wiki/Eating_your_own_dog_food)_: Eating your own dog food or "_dogfooding_" is the practice of using one's own products or services.
- _From [Wikipedia](https://en.wikipedia.org/wiki/Eating_your_own_dog_food)_: Eating your own dog food or "_dogfooding_" is the practice of using one's own products or services.
### Excoriate (verb)

12
content/index.md
View File

@ -13,12 +13,12 @@ You will find within a wide range of topics, expanding and exploring ideas acros
Like me, all notes contained within should be considered work-in-progress. Expect changes at all content levels. That said, I try not to let perfectionism get in the way. That means what you read here is not authoritative or complete, and is not representative of my best work. Please keep that in mind as you navigate around the garden. I'm glad you are here. Enjoy your visit!
- Want to learn more _about me_?
Check out the [[./About|About]] page.
- Want to read more of my material?
Visit my [Blog](https://miguelpimentel.do/).
- Want to learn more _about the site_?
Review the site's [[./Meta|Meta]] page.
- Want to learn more _about me_?
Check out the [[./About|About]] page.
- Want to read more of my material?
Visit my [Blog](https://miguelpimentel.do/).
- Want to learn more _about the site_?
Review the site's [[./Meta|Meta]] page.
I leave you with some fun quotes. Feel free to stop by the [[./Quotes|Quotes]].

60
docs/advanced/architecture.md
View File

@ -11,42 +11,42 @@ This question is best answered by tracing what happens when a user (you!) runs `
1. After running `npx quartz build`, npm will look at `package.json` to find the `bin` entry for `quartz` which points at `./quartz/bootstrap-cli.mjs`.
2. This file has a [shebang](<https://en.wikipedia.org/wiki/Shebang_(Unix)>) line at the top which tells npm to execute it using Node.
3. `bootstrap-cli.mjs` is responsible for a few things:
1. Parsing the command-line arguments using [yargs](http://yargs.js.org/).
2. Transpiling and bundling the rest of Quartz (which is in Typescript) to regular JavaScript using [esbuild](https://esbuild.github.io/). The `esbuild` configuration here is slightly special as it also handles `.scss` file imports using [esbuild-sass-plugin v2](https://www.npmjs.com/package/esbuild-sass-plugin). Additionally, we bundle 'inline' client-side scripts (any `.inline.ts` file) that components declare using a custom `esbuild` plugin that runs another instance of `esbuild` which bundles for the browser instead of `node`. Modules of both types are imported as plain text.
3. Running the local preview server if `--serve` is set. This starts two servers:
1. A WebSocket server on port 3001 to handle hot-reload signals. This tracks all inbound connections and sends a 'rebuild' message a server-side change is detected (either content or configuration).
2. An HTTP file-server on a user defined port (normally 8080) to serve the actual website files.
4. If the `--serve` flag is set, it also starts a file watcher to detect source-code changes (e.g. anything that is `.ts`, `.tsx`, `.scss`, or packager files). On a change, we rebuild the module (step 2 above) using esbuild's [rebuild API](https://esbuild.github.io/api/#rebuild) which drastically reduces the build times.
5. After transpiling the main Quartz build module (`quartz/build.ts`), we write it to a cache file `.quartz-cache/transpiled-build.mjs` and then dynamically import this using `await import(cacheFile)`. However, we need to be pretty smart about how to bust Node's [import cache](https://github.com/nodejs/modules/issues/307) so we add a random query string to fake Node into thinking it's a new module. This does, however, cause memory leaks so we just hope that the user doesn't hot-reload their configuration too many times in a single session :)) (it leaks about ~350kB memory on each reload). After importing the module, we then invoke it, passing in the command line arguments we parsed earlier along with a callback function to signal the client to refresh.
1. Parsing the command-line arguments using [yargs](http://yargs.js.org/).
2. Transpiling and bundling the rest of Quartz (which is in Typescript) to regular JavaScript using [esbuild](https://esbuild.github.io/). The `esbuild` configuration here is slightly special as it also handles `.scss` file imports using [esbuild-sass-plugin v2](https://www.npmjs.com/package/esbuild-sass-plugin). Additionally, we bundle 'inline' client-side scripts (any `.inline.ts` file) that components declare using a custom `esbuild` plugin that runs another instance of `esbuild` which bundles for the browser instead of `node`. Modules of both types are imported as plain text.
3. Running the local preview server if `--serve` is set. This starts two servers:
1. A WebSocket server on port 3001 to handle hot-reload signals. This tracks all inbound connections and sends a 'rebuild' message a server-side change is detected (either content or configuration).
2. An HTTP file-server on a user defined port (normally 8080) to serve the actual website files.
4. If the `--serve` flag is set, it also starts a file watcher to detect source-code changes (e.g. anything that is `.ts`, `.tsx`, `.scss`, or packager files). On a change, we rebuild the module (step 2 above) using esbuild's [rebuild API](https://esbuild.github.io/api/#rebuild) which drastically reduces the build times.
5. After transpiling the main Quartz build module (`quartz/build.ts`), we write it to a cache file `.quartz-cache/transpiled-build.mjs` and then dynamically import this using `await import(cacheFile)`. However, we need to be pretty smart about how to bust Node's [import cache](https://github.com/nodejs/modules/issues/307) so we add a random query string to fake Node into thinking it's a new module. This does, however, cause memory leaks so we just hope that the user doesn't hot-reload their configuration too many times in a single session :)) (it leaks about ~350kB memory on each reload). After importing the module, we then invoke it, passing in the command line arguments we parsed earlier along with a callback function to signal the client to refresh.
4. In `build.ts`, we start by installing source map support manually to account for the query string cache busting hack we introduced earlier. Then, we start processing content:
1. Clean the output directory.
2. Recursively glob all files in the `content` folder, respecting the `.gitignore`.
3. Parse the Markdown files.
1. Quartz detects the number of threads available and chooses to spawn worker threads if there are >128 pieces of content to parse (rough heuristic). If it needs to spawn workers, it will invoke esbuild again to transpile the worker script `quartz/worker.ts`. Then, a work-stealing [workerpool](https://www.npmjs.com/package/workerpool) is then created and batches of 128 files are assigned to workers.
2. Each worker (or just the main thread if there is no concurrency) creates a [unified](https://github.com/unifiedjs/unified) parser based off of the plugins defined in the [[configuration]].
3. Parsing has three steps:
1. Read the file into a [vfile](https://github.com/vfile/vfile).
2. Applied plugin-defined text transformations over the content.
3. Slugify the file path and store it in the data for the file. See the page on [[paths]] for more details about how path logic works in Quartz (spoiler: its complicated).
4. Markdown parsing using [remark-parse](https://www.npmjs.com/package/remark-parse) (text to [mdast](https://github.com/syntax-tree/mdast)).
5. Apply plugin-defined Markdown-to-Markdown transformations.
6. Convert Markdown into HTML using [remark-rehype](https://github.com/remarkjs/remark-rehype) ([mdast](https://github.com/syntax-tree/mdast) to [hast](https://github.com/syntax-tree/hast)).
7. Apply plugin-defined HTML-to-HTML transformations.
4. Filter out unwanted content using plugins.
5. Emit files using plugins.
1. Gather all the static resources (e.g. external CSS, JS modules, etc.) each emitter plugin declares.
2. Emitters that emit HTML files do a bit of extra work here as they need to transform the [hast](https://github.com/syntax-tree/hast) produced in the parse step to JSX. This is done using [hast-util-to-jsx-runtime](https://github.com/syntax-tree/hast-util-to-jsx-runtime) with the [Preact](https://preactjs.com/) runtime. Finally, the JSX is rendered to HTML using [preact-render-to-string](https://github.com/preactjs/preact-render-to-string) which statically renders the JSX to HTML (i.e. doesn't care about `useState`, `useEffect`, or any other React/Preact interactive bits). Here, we also do a bunch of fun stuff like assemble the page [[layout]] from `quartz.layout.ts`, assemble all the inline scripts that actually get shipped to the client, and all the transpiled styles. The bulk of this logic can be found in `quartz/components/renderPage.tsx`. Other fun things of note:
1. CSS is minified and transformed using [Lightning CSS](https://github.com/parcel-bundler/lightningcss) to add vendor prefixes and do syntax lowering.
2. Scripts are split into `beforeDOMLoaded` and `afterDOMLoaded` and are inserted in the `<head>` and `<body>` respectively.
3. Finally, each emitter plugin is responsible for emitting and writing it's own emitted files to disk.
6. If the `--serve` flag was detected, we also set up another file watcher to detect content changes (only `.md` files). We keep a content map that tracks the parsed AST and plugin data for each slug and update this on file changes. Newly added or modified paths are rebuilt and added to the content map. Then, all the filters and emitters are run over the resulting content map. This file watcher is debounced with a threshold of 250ms. On success, we send a client refresh signal using the passed in callback function.
1. Clean the output directory.
2. Recursively glob all files in the `content` folder, respecting the `.gitignore`.
3. Parse the Markdown files.
1. Quartz detects the number of threads available and chooses to spawn worker threads if there are >128 pieces of content to parse (rough heuristic). If it needs to spawn workers, it will invoke esbuild again to transpile the worker script `quartz/worker.ts`. Then, a work-stealing [workerpool](https://www.npmjs.com/package/workerpool) is then created and batches of 128 files are assigned to workers.
2. Each worker (or just the main thread if there is no concurrency) creates a [unified](https://github.com/unifiedjs/unified) parser based off of the plugins defined in the [[configuration]].
3. Parsing has three steps:
1. Read the file into a [vfile](https://github.com/vfile/vfile).
2. Applied plugin-defined text transformations over the content.
3. Slugify the file path and store it in the data for the file. See the page on [[paths]] for more details about how path logic works in Quartz (spoiler: its complicated).
4. Markdown parsing using [remark-parse](https://www.npmjs.com/package/remark-parse) (text to [mdast](https://github.com/syntax-tree/mdast)).
5. Apply plugin-defined Markdown-to-Markdown transformations.
6. Convert Markdown into HTML using [remark-rehype](https://github.com/remarkjs/remark-rehype) ([mdast](https://github.com/syntax-tree/mdast) to [hast](https://github.com/syntax-tree/hast)).
7. Apply plugin-defined HTML-to-HTML transformations.
4. Filter out unwanted content using plugins.
5. Emit files using plugins.
1. Gather all the static resources (e.g. external CSS, JS modules, etc.) each emitter plugin declares.
2. Emitters that emit HTML files do a bit of extra work here as they need to transform the [hast](https://github.com/syntax-tree/hast) produced in the parse step to JSX. This is done using [hast-util-to-jsx-runtime](https://github.com/syntax-tree/hast-util-to-jsx-runtime) with the [Preact](https://preactjs.com/) runtime. Finally, the JSX is rendered to HTML using [preact-render-to-string](https://github.com/preactjs/preact-render-to-string) which statically renders the JSX to HTML (i.e. doesn't care about `useState`, `useEffect`, or any other React/Preact interactive bits). Here, we also do a bunch of fun stuff like assemble the page [[layout]] from `quartz.layout.ts`, assemble all the inline scripts that actually get shipped to the client, and all the transpiled styles. The bulk of this logic can be found in `quartz/components/renderPage.tsx`. Other fun things of note:
1. CSS is minified and transformed using [Lightning CSS](https://github.com/parcel-bundler/lightningcss) to add vendor prefixes and do syntax lowering.
2. Scripts are split into `beforeDOMLoaded` and `afterDOMLoaded` and are inserted in the `<head>` and `<body>` respectively.
3. Finally, each emitter plugin is responsible for emitting and writing it's own emitted files to disk.
6. If the `--serve` flag was detected, we also set up another file watcher to detect content changes (only `.md` files). We keep a content map that tracks the parsed AST and plugin data for each slug and update this on file changes. Newly added or modified paths are rebuilt and added to the content map. Then, all the filters and emitters are run over the resulting content map. This file watcher is debounced with a threshold of 250ms. On success, we send a client refresh signal using the passed in callback function.
## On the client
1. The browser opens a Quartz page and loads the HTML. The `<head>` also links to page styles (emitted to `public/index.css`) and page-critical JS (emitted to `public/prescript.js`)
2. Then, once the body is loaded, the browser loads the non-critical JS (emitted to `public/postscript.js`)
3. Once the page is done loading, the page will then dispatch a custom synthetic browser event `"nav"`. This is used so client-side scripts declared by components can 'setup' anything that requires access to the page DOM.
1. If the [[SPA Routing|enableSPA option]] is enabled in the [[configuration]], this `"nav"` event is also fired on any client-navigation to allow for components to unregister and reregister any event handlers and state.
2. If it's not, we wire up the `"nav"` event to just be fired a single time after page load to allow for consistency across how state is setup across both SPA and non-SPA contexts.
1. If the [[SPA Routing|enableSPA option]] is enabled in the [[configuration]], this `"nav"` event is also fired on any client-navigation to allow for components to unregister and reregister any event handlers and state.
2. If it's not, we wire up the `"nav"` event to just be fired a single time after page load to allow for consistency across how state is setup across both SPA and non-SPA contexts.
The architecture and design of the plugin system was intentionally left pretty vague here as this is described in much more depth in the guide on [[making plugins|making your own plugin]].

120
docs/advanced/creating components.md
View File

@ -9,8 +9,8 @@ Normally on the web, we write layout code using HTML which looks something like
```html
<article>
<h1>An article header</h1>
<p>Some content</p>
<h1>An article header</h1>
<p>Some content</p>
</article>
```
@ -32,24 +32,24 @@ In your component, you can use the values from the configuration option to chang
```tsx {11-17}
interface Options {
favouriteNumber: number
favouriteNumber: number
}
const defaultOptions: Options = {
favouriteNumber: 42,
favouriteNumber: 42,
}
export default ((userOpts?: Options) => {
const opts = { ...userOpts, ...defaultOpts }
function YourComponent(props: QuartzComponentProps) {
if (opts.favouriteNumber < 0) {
return null
const opts = { ...userOpts, ...defaultOpts }
function YourComponent(props: QuartzComponentProps) {
if (opts.favouriteNumber < 0) {
return null
}
return <p>My favourite number is {opts.favouriteNumber}</p>
}
return <p>My favourite number is {opts.favouriteNumber}</p>
}
return YourComponent
return YourComponent
}) satisfies QuartzComponentConstructor
```
@ -62,21 +62,21 @@ All Quartz components accept the same set of props:
```tsx title="quartz/components/types.ts"
// simplified for sake of demonstration
export type QuartzComponentProps = {
fileData: QuartzPluginData
cfg: GlobalConfiguration
tree: Node<QuartzPluginData>
allFiles: QuartzPluginData[]
displayClass?: "mobile-only" | "desktop-only"
fileData: QuartzPluginData
cfg: GlobalConfiguration
tree: Node<QuartzPluginData>
allFiles: QuartzPluginData[]
displayClass?: "mobile-only" | "desktop-only"
}
```
- `fileData`: Any metadata [[making plugins|plugins]] may have added to the current page.
- `fileData.slug`: slug of the current page.
- `fileData.frontmatter`: any frontmatter parsed.
- `cfg`: The `configuration` field in `quartz.config.ts`.
- `tree`: the resulting [HTML AST](https://github.com/syntax-tree/hast) after processing and transforming the file. This is useful if you'd like to render the content using [hast-util-to-jsx-runtime](https://github.com/syntax-tree/hast-util-to-jsx-runtime) (you can find an example of this in `quartz/components/pages/Content.tsx`).
- `allFiles`: Metadata for all files that have been parsed. Useful for doing page listings or figuring out the overall site structure.
- `displayClass`: a utility class that indicates a preference from the user about how to render it in a mobile or desktop setting. Helpful if you want to conditionally hide a component on mobile or desktop.
- `fileData`: Any metadata [[making plugins|plugins]] may have added to the current page.
- `fileData.slug`: slug of the current page.
- `fileData.frontmatter`: any frontmatter parsed.
- `cfg`: The `configuration` field in `quartz.config.ts`.
- `tree`: the resulting [HTML AST](https://github.com/syntax-tree/hast) after processing and transforming the file. This is useful if you'd like to render the content using [hast-util-to-jsx-runtime](https://github.com/syntax-tree/hast-util-to-jsx-runtime) (you can find an example of this in `quartz/components/pages/Content.tsx`).
- `allFiles`: Metadata for all files that have been parsed. Useful for doing page listings or figuring out the overall site structure.
- `displayClass`: a utility class that indicates a preference from the user about how to render it in a mobile or desktop setting. Helpful if you want to conditionally hide a component on mobile or desktop.
### Styling
@ -86,17 +86,17 @@ Note that inlined styles **must** be plain vanilla CSS:
```tsx {6-10} title="quartz/components/YourComponent.tsx"
export default (() => {
function YourComponent() {
return <p class="red-text">Example Component</p>
}
function YourComponent() {
return <p class="red-text">Example Component</p>
}
YourComponent.css = `
YourComponent.css = `
p.red-text {
color: red;
}
`
return YourComponent
return YourComponent
}) satisfies QuartzComponentConstructor
```
@ -107,12 +107,12 @@ Imported styles, however, can be from SCSS files:
import styles from "./styles/YourComponent.scss"
export default (() => {
function YourComponent() {
return <p>Example Component</p>
}
function YourComponent() {
return <p>Example Component</p>
}
YourComponent.css = styles
return YourComponent
YourComponent.css = styles
return YourComponent
}) satisfies QuartzComponentConstructor
```
@ -125,20 +125,20 @@ What about interactivity? Suppose you want to add an-click handler for example.
```tsx title="quartz/components/YourComponent.tsx"
export default (() => {
function YourComponent() {
return <button id="btn">Click me</button>
}
function YourComponent() {
return <button id="btn">Click me</button>
}
YourComponent.beforeDOM = `
YourComponent.beforeDOM = `
console.log("hello from before the page loads!")
`
YourComponent.afterDOM = `
YourComponent.afterDOM = `
document.getElementById('btn').onclick = () => {
alert('button clicked!')
}
`
return YourComponent
return YourComponent
}) satisfies QuartzComponentConstructor
```
@ -153,11 +153,11 @@ If you need to create an `afterDOMLoaded` script that depends on _page specific_
```ts
document.addEventListener("nav", () => {
// do page specific logic here
// e.g. attach event listeners
const toggleSwitch = document.querySelector("#switch") as HTMLInputElement
toggleSwitch.removeEventListener("change", switchTheme)
toggleSwitch.addEventListener("change", switchTheme, { passive: true })
// do page specific logic here
// e.g. attach event listeners
const toggleSwitch = document.querySelector("#switch") as HTMLInputElement
toggleSwitch.removeEventListener("change", switchTheme)
toggleSwitch.addEventListener("change", switchTheme, { passive: true })
})
```
@ -176,12 +176,12 @@ Quartz supports importing component code through `.inline.ts` files.
import script from "./scripts/graph.inline"
export default (() => {
function YourComponent() {
return <button id="btn">Click me</button>
}
function YourComponent() {
return <button id="btn">Click me</button>
}
YourComponent.afterDOM = script
return YourComponent
YourComponent.afterDOM = script
return YourComponent
}) satisfies QuartzComponentConstructor
```
@ -190,7 +190,7 @@ export default (() => {
import * as d3 from "d3"
document.getElementById("btn").onclick = () => {
alert("button clicked!")
alert("button clicked!")
}
```
@ -217,16 +217,16 @@ As Quartz components are just functions that return React components, you can co
import YourComponent from "./YourComponent"
export default (() => {
function AnotherComponent(props: QuartzComponentProps) {
return (
<div>
<p>It's nested!</p>
<YourComponent {...props} />
</div>
)
}
function AnotherComponent(props: QuartzComponentProps) {
return (
<div>
<p>It's nested!</p>
<YourComponent {...props} />
</div>
)
}
return AnotherComponent
return AnotherComponent
}) satisfies QuartzComponentConstructor
```

294
docs/advanced/making plugins.md
View File

@ -13,22 +13,24 @@ All plugins are defined as a function that takes in a single parameter for optio
```ts
type OptionType = object | undefined
type QuartzPlugin<Options extends OptionType = undefined> = (opts?: Options) => QuartzPluginInstance
type QuartzPlugin<Options extends OptionType = undefined> = (
opts?: Options,
) => QuartzPluginInstance
type QuartzPluginInstance =
| QuartzTransformerPluginInstance
| QuartzFilterPluginInstance
| QuartzEmitterPluginInstance
| QuartzTransformerPluginInstance
| QuartzFilterPluginInstance
| QuartzEmitterPluginInstance
```
The following sections will go into detail for what methods can be implemented for each plugin type. Before we do that, let's clarify a few more ambiguous types:
- `BuildCtx` is defined in `quartz/ctx.ts`. It consists of
- `argv`: The command line arguments passed to the Quartz [[build]] command
- `cfg`: The full Quartz [[configuration]]
- `allSlugs`: a list of all the valid content slugs (see [[paths]] for more information on what a `ServerSlug` is)
- `StaticResources` is defined in `quartz/resources.tsx`. It consists of
- `css`: a list of URLs for stylesheets that should be loaded
- `js`: a list of scripts that should be loaded. A script is described with the `JSResource` type which is also defined in `quartz/resources.tsx`. It allows you to define a load time (either before or after the DOM has been loaded), whether it should be a module, and either the source URL or the inline content of the script.
- `BuildCtx` is defined in `quartz/ctx.ts`. It consists of
- `argv`: The command line arguments passed to the Quartz [[build]] command
- `cfg`: The full Quartz [[configuration]]
- `allSlugs`: a list of all the valid content slugs (see [[paths]] for more information on what a `ServerSlug` is)
- `StaticResources` is defined in `quartz/resources.tsx`. It consists of
- `css`: a list of URLs for stylesheets that should be loaded
- `js`: a list of scripts that should be loaded. A script is described with the `JSResource` type which is also defined in `quartz/resources.tsx`. It allows you to define a load time (either before or after the DOM has been loaded), whether it should be a module, and either the source URL or the inline content of the script.
## Transformers
@ -36,20 +38,20 @@ Transformers **map** over content, taking a Markdown file and outputting modifie
```ts
export type QuartzTransformerPluginInstance = {
name: string
textTransform?: (ctx: BuildCtx, src: string | Buffer) => string | Buffer
markdownPlugins?: (ctx: BuildCtx) => PluggableList
htmlPlugins?: (ctx: BuildCtx) => PluggableList
externalResources?: (ctx: BuildCtx) => Partial<StaticResources>
name: string
textTransform?: (ctx: BuildCtx, src: string | Buffer) => string | Buffer
markdownPlugins?: (ctx: BuildCtx) => PluggableList
htmlPlugins?: (ctx: BuildCtx) => PluggableList
externalResources?: (ctx: BuildCtx) => Partial<StaticResources>
}
```
All transformer plugins must define at least a `name` field to register the plugin and a few optional functions that allow you to hook into various parts of transforming a single Markdown file.
- `textTransform` performs a text-to-text transformation _before_ a file is parsed into the [Markdown AST](https://github.com/syntax-tree/mdast).
- `markdownPlugins` defines a list of [remark plugins](https://github.com/remarkjs/remark/blob/main/doc/plugins.md). `remark` is a tool that transforms Markdown to Markdown in a structured way.
- `htmlPlugins` defines a list of [rehype plugins](https://github.com/rehypejs/rehype/blob/main/doc/plugins.md). Similar to how `remark` works, `rehype` is a tool that transforms HTML to HTML in a structured way.
- `externalResources` defines any external resources the plugin may need to load on the client-side for it to work properly.
- `textTransform` performs a text-to-text transformation _before_ a file is parsed into the [Markdown AST](https://github.com/syntax-tree/mdast).
- `markdownPlugins` defines a list of [remark plugins](https://github.com/remarkjs/remark/blob/main/doc/plugins.md). `remark` is a tool that transforms Markdown to Markdown in a structured way.
- `htmlPlugins` defines a list of [rehype plugins](https://github.com/rehypejs/rehype/blob/main/doc/plugins.md). Similar to how `remark` works, `rehype` is a tool that transforms HTML to HTML in a structured way.
- `externalResources` defines any external resources the plugin may need to load on the client-side for it to work properly.
Normally for both `remark` and `rehype`, you can find existing plugins that you can use to . If you'd like to create your own `remark` or `rehype` plugin, checkout the [guide to creating a plugin](https://unifiedjs.com/learn/guide/create-a-plugin/) using `unified` (the underlying AST parser and transformer library).
@ -62,46 +64,46 @@ import rehypeMathjax from "rehype-mathjax/svg"
import { QuartzTransformerPlugin } from "../types"
interface Options {
renderEngine: "katex" | "mathjax"
renderEngine: "katex" | "mathjax"
}
export const Latex: QuartzTransformerPlugin<Options> = (opts?: Options) => {
const engine = opts?.renderEngine ?? "katex"
return {
name: "Latex",
markdownPlugins() {
return [remarkMath]
},
htmlPlugins() {
if (engine === "katex") {
// if you need to pass options into a plugin, you
// can use a tuple of [plugin, options]
return [[rehypeKatex, { output: "html" }]]
} else {
return [rehypeMathjax]
}
},
externalResources() {
if (engine === "katex") {
return {
css: [
// base css
"https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.9/katex.min.css",
],
js: [
{
// fix copy behaviour: https://github.com/KaTeX/KaTeX/blob/main/contrib/copy-tex/README.md
src: "https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.9/contrib/copy-tex.min.js",
loadTime: "afterDOMReady",
contentType: "external",
},
],
}
} else {
return {}
}
},
}
const engine = opts?.renderEngine ?? "katex"
return {
name: "Latex",
markdownPlugins() {
return [remarkMath]
},
htmlPlugins() {
if (engine === "katex") {
// if you need to pass options into a plugin, you
// can use a tuple of [plugin, options]
return [[rehypeKatex, { output: "html" }]]
} else {
return [rehypeMathjax]
}
},
externalResources() {
if (engine === "katex") {
return {
css: [
// base css
"https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.9/katex.min.css",
],
js: [
{
// fix copy behaviour: https://github.com/KaTeX/KaTeX/blob/main/contrib/copy-tex/README.md
src: "https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.9/contrib/copy-tex.min.js",
loadTime: "afterDOMReady",
contentType: "external",
},
],
}
} else {
return {}
}
},
}
}
```
@ -109,30 +111,30 @@ Another common thing that transformer plugins will do is parse a file and add ex
```ts
export const AddWordCount: QuartzTransformerPlugin = () => {
return {
name: "AddWordCount",
markdownPlugins() {
return [
() => {
return (tree, file) => {
// tree is an `mdast` root element
// file is a `vfile`
const text = file.value
const words = text.split(" ").length
file.data.wordcount = words
}
return {
name: "AddWordCount",
markdownPlugins() {
return [
() => {
return (tree, file) => {
// tree is an `mdast` root element
// file is a `vfile`
const text = file.value
const words = text.split(" ").length
file.data.wordcount = words
}
},
]
},
]
},
}
}
}
// tell typescript about our custom data fields we are adding
// other plugins will then also be aware of this data field
declare module "vfile" {
interface DataMap {
wordcount: number
}
interface DataMap {
wordcount: number
}
}
```
@ -183,12 +185,12 @@ Filters **filter** content, taking the output of all the transformers and determ
```ts
export type QuartzFilterPlugin<Options extends OptionType = undefined> = (
opts?: Options,
opts?: Options,
) => QuartzFilterPluginInstance
export type QuartzFilterPluginInstance = {
name: string
shouldPublish(ctx: BuildCtx, content: ProcessedContent): boolean
name: string
shouldPublish(ctx: BuildCtx, content: ProcessedContent): boolean
}
```
@ -200,12 +202,12 @@ For example, here is the built-in plugin for removing drafts:
import { QuartzFilterPlugin } from "../types"
export const RemoveDrafts: QuartzFilterPlugin<{}> = () => ({
name: "RemoveDrafts",
shouldPublish(_ctx, [_tree, vfile]) {
// uses frontmatter parsed from transformers
const draftFlag: boolean = vfile.data?.frontmatter?.draft ?? false
return !draftFlag
},
name: "RemoveDrafts",
shouldPublish(_ctx, [_tree, vfile]) {
// uses frontmatter parsed from transformers
const draftFlag: boolean = vfile.data?.frontmatter?.draft ?? false
return !draftFlag
},
})
```
@ -215,13 +217,17 @@ Emitters **reduce** over content, taking in a list of all the transformed and fi
```ts
export type QuartzEmitterPlugin<Options extends OptionType = undefined> = (
opts?: Options,
opts?: Options,
) => QuartzEmitterPluginInstance
export type QuartzEmitterPluginInstance = {
name: string
emit(ctx: BuildCtx, content: ProcessedContent[], resources: StaticResources): Promise<FilePath[]>
getQuartzComponents(ctx: BuildCtx): QuartzComponent[]
name: string
emit(
ctx: BuildCtx,
content: ProcessedContent[],
resources: StaticResources,
): Promise<FilePath[]>
getQuartzComponents(ctx: BuildCtx): QuartzComponent[]
}
```
@ -231,14 +237,14 @@ Creating new files can be done via regular Node [fs module](https://nodejs.org/a
```ts
export type WriteOptions = (data: {
// the build context
ctx: BuildCtx
// the name of the file to emit (not including the file extension)
slug: ServerSlug
// the file extension
ext: `.${string}` | ""
// the file content to add
content: string
// the build context
ctx: BuildCtx
// the name of the file to emit (not including the file extension)
slug: ServerSlug
// the file extension
ext: `.${string}` | ""
// the file content to add
content: string
}) => Promise<FilePath>
```
@ -246,54 +252,68 @@ This is a thin wrapper around writing to the appropriate output folder and ensur
If you are creating an emitter plugin that needs to render components, there are three more things to be aware of:
- Your component should use `getQuartzComponents` to declare a list of `QuartzComponents` that it uses to construct the page. See the page on [[creating components]] for more information.
- You can use the `renderPage` function defined in `quartz/components/renderPage.tsx` to render Quartz components into HTML.
- If you need to render an HTML AST to JSX, you can use the `htmlToJsx` function from `quartz/util/jsx.ts`. An example of this can be found in `quartz/components/pages/Content.tsx`.
- Your component should use `getQuartzComponents` to declare a list of `QuartzComponents` that it uses to construct the page. See the page on [[creating components]] for more information.
- You can use the `renderPage` function defined in `quartz/components/renderPage.tsx` to render Quartz components into HTML.
- If you need to render an HTML AST to JSX, you can use the `htmlToJsx` function from `quartz/util/jsx.ts`. An example of this can be found in `quartz/components/pages/Content.tsx`.
For example, the following is a simplified version of the content page plugin that renders every single page.
```tsx title="quartz/plugins/emitters/contentPage.tsx"
export const ContentPage: QuartzEmitterPlugin = () => {
// construct the layout
const layout: FullPageLayout = {
...sharedPageComponents,
...defaultContentPageLayout,
pageBody: Content(),
}
const { head, header, beforeBody, pageBody, left, right, footer } = layout
return {
name: "ContentPage",
getQuartzComponents() {
return [head, ...header, ...beforeBody, pageBody, ...left, ...right, footer]
},
async emit(ctx, content, resources, emit): Promise<FilePath[]> {
const cfg = ctx.cfg.configuration
const fps: FilePath[] = []
const allFiles = content.map((c) => c[1].data)
for (const [tree, file] of content) {
const slug = canonicalizeServer(file.data.slug!)
const externalResources = pageResources(slug, resources)
const componentData: QuartzComponentProps = {
fileData: file.data,
externalResources,
cfg,
children: [],
tree,
allFiles,
}
// construct the layout
const layout: FullPageLayout = {
...sharedPageComponents,
...defaultContentPageLayout,
pageBody: Content(),
}
const { head, header, beforeBody, pageBody, left, right, footer } = layout
return {
name: "ContentPage",
getQuartzComponents() {
return [
head,
...header,
...beforeBody,
pageBody,
...left,
...right,
footer,
]
},
async emit(ctx, content, resources, emit): Promise<FilePath[]> {
const cfg = ctx.cfg.configuration
const fps: FilePath[] = []
const allFiles = content.map((c) => c[1].data)
for (const [tree, file] of content) {
const slug = canonicalizeServer(file.data.slug!)
const externalResources = pageResources(slug, resources)
const componentData: QuartzComponentProps = {
fileData: file.data,
externalResources,
cfg,
children: [],
tree,
allFiles,
}
const content = renderPage(cfg, slug, componentData, opts, externalResources)
const fp = await emit({
content,
slug: file.data.slug!,
ext: ".html",
})
const content = renderPage(
cfg,
slug,
componentData,
opts,
externalResources,
)
const fp = await emit({
content,
slug: file.data.slug!,
ext: ".html",
})
fps.push(fp)
}
return fps
},
}
fps.push(fp)
}
return fps
},
}
}
```

8
docs/advanced/paths.md
View File

@ -43,9 +43,9 @@ graph LR
Here are the main types of slugs with a rough description of each type of path:
- `FilePath`: a real file path to a file on disk. Cannot be relative and must have a file extension.
- `FullSlug`: cannot be relative and may not have leading or trailing slashes. It can have `index` as it's last segment. Use this wherever possible is it's the most 'general' interpretation of a slug.
- `SimpleSlug`: cannot be relative and shouldn't have `/index` as an ending or a file extension. It _can_ however have a trailing slash to indicate a folder path.
- `RelativeURL`: must start with `.` or `..` to indicate it's a relative URL. Shouldn't have `/index` as an ending or a file extension but can contain a trailing slash.
- `FilePath`: a real file path to a file on disk. Cannot be relative and must have a file extension.
- `FullSlug`: cannot be relative and may not have leading or trailing slashes. It can have `index` as it's last segment. Use this wherever possible is it's the most 'general' interpretation of a slug.
- `SimpleSlug`: cannot be relative and shouldn't have `/index` as an ending or a file extension. It _can_ however have a trailing slash to indicate a folder path.
- `RelativeURL`: must start with `.` or `..` to indicate it's a relative URL. Shouldn't have `/index` as an ending or a file extension but can contain a trailing slash.
To get a clearer picture of how these relate to each other, take a look at the path tests in `quartz/path.test.ts`.

14
docs/authoring content.md
View File

@ -19,7 +19,7 @@ Additionally, Quartz also allows you to specify additional metadata in your note
title: Example Title
draft: false
tags:
- example-tag
- example-tag
---
The rest of your content lives here. You can use **Markdown** here :)
@ -27,12 +27,12 @@ The rest of your content lives here. You can use **Markdown** here :)
Some common frontmatter fields that are natively supported by Quartz:
- `title`: Title of the page. If it isn't provided, Quartz will use the name of the file as the title.
- `description`: Description of the page used for link previews.
- `aliases`: Other names for this note. This is a list of strings.
- `tags`: Tags for this note.
- `draft`: Whether to publish the page or not. This is one way to make [[private pages|pages private]] in Quartz.
- `date`: A string representing the day the note was published. Normally uses `YYYY-MM-DD` format.
- `title`: Title of the page. If it isn't provided, Quartz will use the name of the file as the title.
- `description`: Description of the page used for link previews.
- `aliases`: Other names for this note. This is a list of strings.
- `tags`: Tags for this note.
- `draft`: Whether to publish the page or not. This is one way to make [[private pages|pages private]] in Quartz.
- `date`: A string representing the day the note was published. Normally uses `YYYY-MM-DD` format.
## Syncing your Content

12
docs/build.md
View File

@ -15,9 +15,9 @@ This will start a local web server to run your Quartz on your computer. Open a w
>
> Most of these have sensible defaults but you can override them if you have a custom setup:
>
> - `-d` or `--directory`: the content folder. This is normally just `content`
> - `-v` or `--verbose`: print out extra logging information
> - `-o` or `--output`: the output folder. This is normally just `public`
> - `--serve`: run a local hot-reloading server to preview your Quartz
> - `--port`: what port to run the local preview server on
> - `--concurrency`: how many threads to use to parse notes
> - `-d` or `--directory`: the content folder. This is normally just `content`
> - `-v` or `--verbose`: print out extra logging information
> - `-o` or `--output`: the output folder. This is normally just `public`
> - `--serve`: run a local hot-reloading server to preview your Quartz
> - `--port`: what port to run the local preview server on
> - `--concurrency`: how many threads to use to parse notes

70
docs/configuration.md
View File

@ -20,36 +20,36 @@ const config: QuartzConfig = {
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`: title of the site. 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: 'google', tagId: '<your-google-tag>' }`: use Google Analytics;
- `{ provider: 'plausible' }` (managed) or `{ provider: 'plausible', host: '<your-plausible-host>' }` (self-hosted): use [Plausible](https://plausible.io/);
- `{ provider: 'umami', host: '<your-umami-host>', websiteId: '<your-umami-website-id>' }`: use [Umami](https://umami.is/);
- `{ provider: 'goatcounter', websiteId: 'my-goatcounter-id' }` (managed) or `{ provider: 'goatcounter', websiteId: 'my-goatcounter-id', host: 'my-goatcounter-domain.com', scriptSrc: 'https://my-url.to/counter.js' }` (self-hosted) use [GoatCounter](https://goatcounter.com)
- `locale`: used for [[i18n]] and date formatting
- `baseUrl`: 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. `quartz.jzhao.xyz` for this site). Do not include the protocol (i.e. `https://`) or any leading or trailing slashes.
- This should also include the subpath if you are [[hosting]] on GitHub pages without a custom domain. For example, if my repository is `jackyzha0/quartz`, GitHub pages would deploy to `https://jackyzha0.github.io/quartz` and the `baseUrl` would be `jackyzha0.github.io/quartz`.
- 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. See [[private pages]] for more details.
- `defaultDateType`: whether to use created, modified, or published as the default date to display on pages and page listings.
- `theme`: configure how the site looks.
- `cdnCaching`: If `true` (default), use Google CDN to cache the fonts. This will generally will be faster. Disable (`false`) this if you want Quartz to download the fonts to be self-contained.
- `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]]
- `pageTitle`: title of the site. 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: 'google', tagId: '<your-google-tag>' }`: use Google Analytics;
- `{ provider: 'plausible' }` (managed) or `{ provider: 'plausible', host: '<your-plausible-host>' }` (self-hosted): use [Plausible](https://plausible.io/);
- `{ provider: 'umami', host: '<your-umami-host>', websiteId: '<your-umami-website-id>' }`: use [Umami](https://umami.is/);
- `{ provider: 'goatcounter', websiteId: 'my-goatcounter-id' }` (managed) or `{ provider: 'goatcounter', websiteId: 'my-goatcounter-id', host: 'my-goatcounter-domain.com', scriptSrc: 'https://my-url.to/counter.js' }` (self-hosted) use [GoatCounter](https://goatcounter.com)
- `locale`: used for [[i18n]] and date formatting
- `baseUrl`: 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. `quartz.jzhao.xyz` for this site). Do not include the protocol (i.e. `https://`) or any leading or trailing slashes.
- This should also include the subpath if you are [[hosting]] on GitHub pages without a custom domain. For example, if my repository is `jackyzha0/quartz`, GitHub pages would deploy to `https://jackyzha0.github.io/quartz` and the `baseUrl` would be `jackyzha0.github.io/quartz`.
- 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. See [[private pages]] for more details.
- `defaultDateType`: whether to use created, modified, or published as the default date to display on pages and page listings.
- `theme`: configure how the site looks.
- `cdnCaching`: If `true` (default), use Google CDN to cache the fonts. This will generally will be faster. Disable (`false`) this if you want Quartz to download the fonts to be self-contained.
- `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
@ -65,9 +65,9 @@ plugins: {
}
```
- [[tags/plugin/transformer|Transformers]] **map** over content (e.g. parsing frontmatter, generating a description)
- [[tags/plugin/filter|Filters]] **filter** content (e.g. filtering out drafts)
- [[tags/plugin/emitter|Emitters]] **reduce** over content (e.g. creating an RSS feed or pages that list all files with a specific tag)
- [[tags/plugin/transformer|Transformers]] **map** over content (e.g. parsing frontmatter, generating a description)
- [[tags/plugin/filter|Filters]] **filter** content (e.g. filtering out drafts)
- [[tags/plugin/emitter|Emitters]] **reduce** over content (e.g. creating an RSS feed or pages that list all files with a specific tag)
You can customize the behaviour of Quartz by adding, removing and reordering plugins in the `transformers`, `filters` and `emitters` fields.
@ -92,8 +92,8 @@ For example, the [[plugins/Latex|Latex]] plugin allows you to pass in a field sp
```ts title="quartz.config.ts"
transformers: [
Plugin.FrontMatter(), // use default options
Plugin.Latex({ renderEngine: "katex" }), // set some custom options
Plugin.FrontMatter(), // use default options
Plugin.Latex({ renderEngine: "katex" }), // set some custom options
]
```

6
docs/features/Latex.md
View File

@ -1,7 +1,7 @@
---
title: LaTeX
tags:
- feature/transformer
- feature/transformer
---
Quartz uses [Katex](https://katex.org/) by default to typeset both inline and block math expressions at build time.
@ -54,8 +54,8 @@ 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
- 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
### Using mhchem

2
docs/features/Mermaid diagrams.md
View File

@ -1,7 +1,7 @@
---
title: "Mermaid Diagrams"
tags:
- feature/transformer
- feature/transformer
---
Quartz supports Mermaid which allows you to add diagrams and charts to your notes. Mermaid supports a range of diagrams, such as [flow charts](https://mermaid.js.org/syntax/flowchart.html), [sequence diagrams](https://mermaid.js.org/syntax/sequenceDiagram.html), and [timelines](https://mermaid.js.org/syntax/timeline.html). This is enabled as a part of [[Obsidian compatibility]] and can be configured and enabled/disabled from that plugin.

2
docs/features/Obsidian compatibility.md
View File

@ -1,7 +1,7 @@
---
title: "Obsidian Compatibility"
tags:
- feature/transformer
- feature/transformer
---
Quartz was originally designed as a tool to publish Obsidian vaults as websites. Even as the scope of Quartz has widened over time, it hasn't lost the ability to seamlessly interoperate with Obsidian.

2
docs/features/OxHugo compatibility.md
View File

@ -1,7 +1,7 @@
---
title: "OxHugo Compatibility"
tags:
- feature/transformer
- feature/transformer
---
[org-roam](https://www.orgroam.com/) is a plain-text personal knowledge management system for [emacs](https://en.wikipedia.org/wiki/Emacs). [ox-hugo](https://github.com/kaushalmodi/ox-hugo) is org exporter backend that exports `org-mode` files to [Hugo](https://gohugo.io/) compatible Markdown.

2
docs/features/SPA Routing.md
View File

@ -4,4 +4,4 @@ Under the hood, this is done by hijacking page navigations and instead fetching
## Configuration
- Disable SPA Routing: set the `enableSPA` field of the [[configuration]] in `quartz.config.ts` to be `false`.
- Disable SPA Routing: set the `enableSPA` field of the [[configuration]] in `quartz.config.ts` to be `false`.

10
docs/features/backlinks.md
View File

@ -1,14 +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.layout.ts`.
- Component: `quartz/components/Backlinks.tsx`
- Style: `quartz/components/styles/backlinks.scss`
- Script: `quartz/components/scripts/search.inline.ts`
- Removing backlinks: delete all usages of `Component.Backlinks()` from `quartz.layout.ts`.
- Component: `quartz/components/Backlinks.tsx`
- Style: `quartz/components/styles/backlinks.scss`
- Script: `quartz/components/scripts/search.inline.ts`

20
docs/features/breadcrumbs.md
View File

@ -1,7 +1,7 @@
---
title: "Breadcrumbs"
tags:
- component
- component
---
Breadcrumbs provide a way to navigate a hierarchy of pages within your site using a list of its parent folders.
@ -16,11 +16,11 @@ For example, here's what the default configuration looks like:
```typescript title="quartz.layout.ts"
Component.Breadcrumbs({
spacerSymbol: "❯", // symbol between crumbs
rootName: "Home", // name of first/root element
resolveFrontmatterTitle: true, // whether to resolve folder names through frontmatter titles
hideOnRoot: true, // whether to hide breadcrumbs on root `index.md` page
showCurrentPage: true, // whether to display the current page in the breadcrumbs
spacerSymbol: "❯", // symbol between crumbs
rootName: "Home", // name of first/root element
resolveFrontmatterTitle: true, // whether to resolve folder names through frontmatter titles
hideOnRoot: true, // whether to hide breadcrumbs on root `index.md` page
showCurrentPage: true, // whether to display the current page in the breadcrumbs
})
```
@ -30,7 +30,7 @@ You can also adjust where the breadcrumbs will be displayed by adjusting the [[l
Want to customize it even more?
- Removing breadcrumbs: delete all usages of `Component.Breadcrumbs()` from `quartz.layout.ts`.
- Component: `quartz/components/Breadcrumbs.tsx`
- Style: `quartz/components/styles/breadcrumbs.scss`
- Script: inline at `quartz/components/Breadcrumbs.tsx`
- Removing breadcrumbs: delete all usages of `Component.Breadcrumbs()` from `quartz.layout.ts`.
- Component: `quartz/components/Breadcrumbs.tsx`
- Style: `quartz/components/styles/breadcrumbs.scss`
- Script: inline at `quartz/components/Breadcrumbs.tsx`

18
docs/features/callouts.md
View File

@ -1,15 +1,15 @@
---
title: Callouts
tags:
- feature/transformer
- feature/transformer
---
Quartz supports the same Admonition-callout syntax as Obsidian.
This includes
- 12 Distinct callout types (each with several aliases)
- Collapsable callouts
- 12 Distinct callout types (each with several aliases)
- Collapsable callouts
```
> [!info] Title
@ -33,12 +33,12 @@ By default, custom callouts are handled by applying the `note` style. To make fa
```scss title="quartz/styles/custom.scss"
.callout {
&[data-callout="custom"] {
--color: #customcolor;
--border: #custombordercolor;
--bg: #custombg;
--callout-icon: url("data:image/svg+xml; utf8, <custom formatted svg>"); //SVG icon code
}
&[data-callout="custom"] {
--color: #customcolor;
--border: #custombordercolor;
--bg: #custombg;
--callout-icon: url("data:image/svg+xml; utf8, <custom formatted svg>"); //SVG icon code
}
}
```

14
docs/features/darkmode.md
View File

@ -1,23 +1,23 @@
---
title: "Darkmode"
tags:
- component
- component
---
Quartz supports darkmode out of the box that respects the user's theme preference. Any future manual toggles of the darkmode switch will be saved in the browser's local storage so it can be persisted across future page loads.
## Customization
- Removing darkmode: delete all usages of `Component.Darkmode()` from `quartz.layout.ts`.
- Component: `quartz/components/Darkmode.tsx`
- Style: `quartz/components/styles/darkmode.scss`
- Script: `quartz/components/scripts/darkmode.inline.ts`
- Removing darkmode: delete all usages of `Component.Darkmode()` from `quartz.layout.ts`.
- Component: `quartz/components/Darkmode.tsx`
- Style: `quartz/components/styles/darkmode.scss`
- Script: `quartz/components/scripts/darkmode.inline.ts`
You can also listen to the `themechange` event to perform any custom logic when the theme changes.
```js
document.addEventListener("themechange", (e) => {
console.log("Theme changed to " + e.detail.theme) // either "light" or "dark"
// your logic here
console.log("Theme changed to " + e.detail.theme) // either "light" or "dark"
// your logic here
})
```

186
docs/features/explorer.md
View File

@ -1,7 +1,7 @@
---
title: "Explorer"
tags:
- component
- component
---
Quartz features an explorer that allows you to navigate all files and folders on your site. It supports nested folders and is highly customizable.
@ -42,14 +42,14 @@ When passing in your own options, you can omit any or all of these fields if you
Want to customize it even more?
- Removing explorer: remove `Component.Explorer()` from `quartz.layout.ts`
- (optional): After removing the explorer component, you can move the [[table of contents | Table of Contents]] component back to the `left` part of the layout
- Changing `sort`, `filter` and `map` behavior: explained in [[#Advanced customization]]
- Component:
- Wrapper (Outer component, generates file tree, etc): `quartz/components/Explorer.tsx`
- Explorer node (recursive, either a folder or a file): `quartz/components/ExplorerNode.tsx`
- Style: `quartz/components/styles/explorer.scss`
- Script: `quartz/components/scripts/explorer.inline.ts`
- Removing explorer: remove `Component.Explorer()` from `quartz.layout.ts`
- (optional): After removing the explorer component, you can move the [[table of contents | Table of Contents]] component back to the `left` part of the layout
- Changing `sort`, `filter` and `map` behavior: explained in [[#Advanced customization]]
- Component:
- Wrapper (Outer component, generates file tree, etc): `quartz/components/Explorer.tsx`
- Explorer node (recursive, either a folder or a file): `quartz/components/ExplorerNode.tsx`
- Style: `quartz/components/styles/explorer.scss`
- Script: `quartz/components/scripts/explorer.inline.ts`
## Advanced customization
@ -73,21 +73,21 @@ Every function you can pass is optional. By default, only a `sort` function will
```ts title="Default sort function"
// Sort order: folders first, then files. Sort folders and files alphabetically
Component.Explorer({
sortFn: (a, b) => {
if ((!a.file && !b.file) || (a.file && b.file)) {
// sensitivity: "base": Only strings that differ in base letters compare as unequal. Examples: a ≠ b, a = á, a = A
// numeric: true: Whether numeric collation should be used, such that "1" < "2" < "10"
return a.displayName.localeCompare(b.displayName, undefined, {
numeric: true,
sensitivity: "base",
})
}
if (a.file && !b.file) {
return 1
} else {
return -1
}
},
sortFn: (a, b) => {
if ((!a.file && !b.file) || (a.file && b.file)) {
// sensitivity: "base": Only strings that differ in base letters compare as unequal. Examples: a ≠ b, a = á, a = A
// numeric: true: Whether numeric collation should be used, such that "1" < "2" < "10"
return a.displayName.localeCompare(b.displayName, undefined, {
numeric: true,
sensitivity: "base",
})
}
if (a.file && !b.file) {
return 1
} else {
return -1
}
},
})
```
@ -110,9 +110,9 @@ mapFn: (node: FileNode) => void
>
> ```ts
> if (node.file) {
> // node is a file
> // node is a file
> } else {
> // node is a folder
> // node is a folder
> }
> ```
@ -126,16 +126,16 @@ Using this example, the explorer will alphabetically sort everything, but put al
```ts title="quartz.layout.ts"
Component.Explorer({
sortFn: (a, b) => {
if ((!a.file && !b.file) || (a.file && b.file)) {
return a.displayName.localeCompare(b.displayName)
}
if (a.file && !b.file) {
return -1
} else {
return 1
}
},
sortFn: (a, b) => {
if ((!a.file && !b.file) || (a.file && b.file)) {
return a.displayName.localeCompare(b.displayName)
}
if (a.file && !b.file) {
return -1
} else {
return 1
}
},
})
```
@ -145,9 +145,9 @@ Using this example, the display names of all `FileNodes` (folders + files) will
```ts title="quartz.layout.ts"
Component.Explorer({
mapFn: (node) => {
node.displayName = node.displayName.toUpperCase()
},
mapFn: (node) => {
node.displayName = node.displayName.toUpperCase()
},
})
```
@ -157,11 +157,11 @@ Using this example, you can remove elements from your explorer by providing an a
```ts title="quartz.layout.ts"
Component.Explorer({
filterFn: (node) => {
// set containing names of everything you want to filter out
const omit = new Set(["authoring content", "tags", "hosting"])
return !omit.has(node.name.toLowerCase())
},
filterFn: (node) => {
// set containing names of everything you want to filter out
const omit = new Set(["authoring content", "tags", "hosting"])
return !omit.has(node.name.toLowerCase())
},
})
```
@ -173,10 +173,12 @@ You can access the frontmatter of a file by `node.file?.frontmatter?`. This allo
```ts title="quartz.layout.ts"
Component.Explorer({
filterFn: (node) => {
// exclude files with the tag "explorerexclude"
return node.file?.frontmatter?.tags?.includes("explorerexclude") !== true
},
filterFn: (node) => {
// exclude files with the tag "explorerexclude"
return (
node.file?.frontmatter?.tags?.includes("explorerexclude") !== true
)
},
})
```
@ -186,7 +188,7 @@ To override the default filter function that removes the `tags` folder from the
```ts title="quartz.layout.ts"
Component.Explorer({
filterFn: undefined, // apply no filter function, every file and folder will visible
filterFn: undefined, // apply no filter function, every file and folder will visible
})
```
@ -199,13 +201,13 @@ Component.Explorer({
> ```ts title="functions.ts"
> import { Options } from "./quartz/components/ExplorerNode"
> export const mapFn: Options["mapFn"] = (node) => {
> // implement your function here
> // implement your function here
> }
> export const filterFn: Options["filterFn"] = (node) => {
> // implement your function here
> // implement your function here
> }
> export const sortFn: Options["sortFn"] = (a, b) => {
> // implement your function here
> // implement your function here
> }
> ```
>
@ -214,9 +216,9 @@ Component.Explorer({
> ```ts title="quartz.layout.ts"
> import { mapFn, filterFn, sortFn } from "./functions.ts"
> Component.Explorer({
> mapFn: mapFn,
> filterFn: filterFn,
> sortFn: sortFn,
> mapFn: mapFn,
> filterFn: filterFn,
> sortFn: sortFn,
> })
> ```
@ -226,17 +228,17 @@ To add emoji prefixes (📁 for folders, 📄 for files), you could use a map fu
```ts title="quartz.layout.ts"
Component.Explorer({
mapFn: (node) => {
// dont change name of root node
if (node.depth > 0) {
// set emoji for file/folder
if (node.file) {
node.displayName = "📄 " + node.displayName
} else {
node.displayName = "📁 " + node.displayName
}
}
},
mapFn: (node) => {
// dont change name of root node
if (node.depth > 0) {
// set emoji for file/folder
if (node.file) {
node.displayName = "📄 " + node.displayName
} else {
node.displayName = "📁 " + node.displayName
}
}
},
})
```
@ -246,10 +248,10 @@ In this example, we're going to customize the explorer by using functions from e
```ts title="quartz.layout.ts"
Component.Explorer({
filterFn: sampleFilterFn,
mapFn: sampleMapFn,
sortFn: sampleSortFn,
order: ["filter", "sort", "map"],
filterFn: sampleFilterFn,
mapFn: sampleMapFn,
sortFn: sampleSortFn,
order: ["filter", "sort", "map"],
})
```
@ -265,32 +267,32 @@ It's also worth mentioning, that the smaller the number set in `nameOrderMap`, t
```ts title="quartz.layout.ts"
Component.Explorer({
sortFn: (a, b) => {
const nameOrderMap: Record<string, number> = {
"poetry-folder": 100,
"essay-folder": 200,
"research-paper-file": 201,
"dinosaur-fossils-file": 300,
"other-folder": 400,
}
sortFn: (a, b) => {
const nameOrderMap: Record<string, number> = {
"poetry-folder": 100,
"essay-folder": 200,
"research-paper-file": 201,
"dinosaur-fossils-file": 300,
"other-folder": 400,
}
let orderA = 0
let orderB = 0
let orderA = 0
let orderB = 0
if (a.file && a.file.slug) {
orderA = nameOrderMap[a.file.slug] || 0
} else if (a.name) {
orderA = nameOrderMap[a.name] || 0
}
if (a.file && a.file.slug) {
orderA = nameOrderMap[a.file.slug] || 0
} else if (a.name) {
orderA = nameOrderMap[a.name] || 0
}
if (b.file && b.file.slug) {
orderB = nameOrderMap[b.file.slug] || 0
} else if (b.name) {
orderB = nameOrderMap[b.name] || 0
}
if (b.file && b.file.slug) {
orderB = nameOrderMap[b.file.slug] || 0
} else if (b.name) {
orderB = nameOrderMap[b.name] || 0
}
return orderA - orderB
},
return orderA - orderB
},
})
```

2
docs/features/folder and tag listings.md
View File

@ -1,7 +1,7 @@
---
title: Folder and Tag Listings
tags:
- feature/emitter
- feature/emitter
---
Quartz emits listing pages for any folders and tags you have.

12
docs/features/full-text search.md
View File

@ -1,7 +1,7 @@
---
title: Full-text Search
tags:
- component
- 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.
@ -23,8 +23,8 @@ It properly tokenizes Chinese, Korean, and Japenese characters and constructs se
## Customization
- Removing search: delete all usages of `Component.Search()` from `quartz.layout.ts`.
- Component: `quartz/components/Search.tsx`
- Style: `quartz/components/styles/search.scss`
- Script: `quartz/components/scripts/search.inline.ts`
- You can edit `contextWindowWords`, `numSearchResults` or `numTagResults` to suit your needs
- Removing search: delete all usages of `Component.Search()` from `quartz.layout.ts`.
- Component: `quartz/components/Search.tsx`
- Style: `quartz/components/styles/search.scss`
- Script: `quartz/components/scripts/search.inline.ts`
- You can edit `contextWindowWords`, `numSearchResults` or `numTagResults` to suit your needs

66
docs/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.
- 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.
@ -24,32 +24,32 @@ For example, here's what the default configuration looks like:
```typescript title="quartz.layout.ts"
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
scale: 1.1, // default view scale
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?
removeTags: [], // what tags to remove from the graph
showTags: true, // whether to show tags in the graph
},
globalGraph: {
drag: true,
zoom: true,
depth: -1,
scale: 0.9,
repelForce: 0.5,
centerForce: 0.3,
linkDistance: 30,
fontSize: 0.6,
opacityScale: 1,
removeTags: [], // what tags to remove from the graph
showTags: true, // whether to show tags in the 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
scale: 1.1, // default view scale
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?
removeTags: [], // what tags to remove from the graph
showTags: true, // whether to show tags in the graph
},
globalGraph: {
drag: true,
zoom: true,
depth: -1,
scale: 0.9,
repelForce: 0.5,
centerForce: 0.3,
linkDistance: 30,
fontSize: 0.6,
opacityScale: 1,
removeTags: [], // what tags to remove from the graph
showTags: true, // whether to show tags in the graph
},
})
```
@ -57,7 +57,7 @@ When passing in your own options, you can omit any or all of these fields if you
Want to customize it even more?
- Removing graph view: delete all usages of `Component.Graph()` from `quartz.layout.ts`.
- Component: `quartz/components/Graph.tsx`
- Style: `quartz/components/styles/graph.scss`
- Script: `quartz/components/scripts/graph.inline.ts`
- Removing graph view: delete all usages of `Component.Graph()` from `quartz.layout.ts`.
- Component: `quartz/components/Graph.tsx`
- Style: `quartz/components/styles/graph.scss`
- Script: `quartz/components/scripts/graph.inline.ts`

4
docs/features/i18n.md
View File

@ -6,8 +6,8 @@ Internationalization allows users to translate text in the Quartz interface into
The locale field generally follows a certain format: `{language}-{REGION}`
- `{language}` is usually a [2-letter lowercase language code](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes).
- `{REGION}` is usually a [2-letter uppercase region code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
- `{language}` is usually a [2-letter lowercase language code](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes).
- `{REGION}` is usually a [2-letter uppercase region code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
> [!tip] Interested in contributing?
> We [gladly welcome translation PRs](https://github.com/jackyzha0/quartz/tree/v4/quartz/i18n/locales)! To contribute a translation, do the following things:

6
docs/features/popover previews.md
View File

@ -12,6 +12,6 @@ Similar to Obsidian, [[quartz layout.png|images referenced using wikilinks]] can
## 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`
- 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`

10
docs/features/private pages.md
View File

@ -1,7 +1,7 @@
---
title: Private Pages
tags:
- feature/filter
- feature/filter
---
There may be some notes you want to avoid publishing as a website. Quartz supports this through two mechanisms which can be used in conjunction:
@ -26,10 +26,10 @@ This is a field in `quartz.config.ts` under the main [[configuration]] which all
Common examples include:
- `some/folder`: exclude the entire of `some/folder`
- `*.md`: exclude all files with a `.md` extension
- `!*.md` exclude all files that _don't_ have a `.md` extension
- `**/private`: exclude any files or folders named `private` at any level of nesting
- `some/folder`: exclude the entire of `some/folder`
- `*.md`: exclude all files with a `.md` extension
- `!*.md` exclude all files that _don't_ have a `.md` extension
- `**/private`: exclude any files or folders named `private` at any level of nesting
> [!warning]
> Marking something as private via either a plugin or through the `ignorePatterns` pattern will only prevent a page from being included in the final built site. If your GitHub repository is public, also be sure to include an ignore for those in the `.gitignore` of your Quartz. See the `git` [documentation](https://git-scm.com/docs/gitignore#_pattern_format) for more information.

14
docs/features/recent notes.md
View File

@ -7,10 +7,10 @@ Quartz can generate a list of recent notes based on some filtering and sorting c
## Customization
- Changing the title from "Recent notes": pass in an additional parameter to `Component.RecentNotes({ title: "Recent writing" })`
- Changing the number of recent notes: pass in an additional parameter to `Component.RecentNotes({ limit: 5 })`
- Show a 'see more' link: pass in an additional parameter to `Component.RecentNotes({ linkToMore: "tags/components" })`. This field should be a full slug to a page that exists.
- Customize filtering: pass in an additional parameter to `Component.RecentNotes({ filter: someFilterFunction })`. The filter function should be a function that has the signature `(f: QuartzPluginData) => boolean`.
- Customize sorting: pass in an additional parameter to `Component.RecentNotes({ sort: someSortFunction })`. By default, Quartz will sort by date and then tie break lexographically. The sort function should be a function that has the signature `(f1: QuartzPluginData, f2: QuartzPluginData) => number`. See `byDateAndAlphabetical` in `quartz/components/PageList.tsx` for an example.
- Component: `quartz/components/RecentNotes.tsx`
- Style: `quartz/components/styles/recentNotes.scss`
- Changing the title from "Recent notes": pass in an additional parameter to `Component.RecentNotes({ title: "Recent writing" })`
- Changing the number of recent notes: pass in an additional parameter to `Component.RecentNotes({ limit: 5 })`
- Show a 'see more' link: pass in an additional parameter to `Component.RecentNotes({ linkToMore: "tags/components" })`. This field should be a full slug to a page that exists.
- Customize filtering: pass in an additional parameter to `Component.RecentNotes({ filter: someFilterFunction })`. The filter function should be a function that has the signature `(f: QuartzPluginData) => boolean`.
- Customize sorting: pass in an additional parameter to `Component.RecentNotes({ sort: someSortFunction })`. By default, Quartz will sort by date and then tie break lexographically. The sort function should be a function that has the signature `(f1: QuartzPluginData, f2: QuartzPluginData) => number`. See `byDateAndAlphabetical` in `quartz/components/PageList.tsx` for an example.
- Component: `quartz/components/RecentNotes.tsx`
- Style: `quartz/components/styles/recentNotes.scss`

34
docs/features/syntax highlighting.md
View File

@ -1,7 +1,7 @@
---
title: Syntax Highlighting
tags:
- feature/transformer
- feature/transformer
---
Syntax highlighting in Quartz is completely done at build-time. This means that Quartz only ships pre-calculated CSS to highlight the right words so there is no heavy client-side bundle that does the syntax highlighting.
@ -31,11 +31,11 @@ export function trimPathSuffix(fp: string): string {
```ts
export function trimPathSuffix(fp: string): string {
fp = clientSideSlug(fp)
let [cleanPath, anchor] = fp.split("#", 2)
anchor = anchor === undefined ? "" : "#" + anchor
fp = clientSideSlug(fp)
let [cleanPath, anchor] = fp.split("#", 2)
anchor = anchor === undefined ? "" : "#" + anchor
return cleanPath + anchor
return cleanPath + anchor
}
```
@ -51,11 +51,11 @@ Add a file title to your code block, with text inside double quotes (`""`):
```ts title="quartz/path.ts"
export function trimPathSuffix(fp: string): string {
fp = clientSideSlug(fp)
let [cleanPath, anchor] = fp.split("#", 2)
anchor = anchor === undefined ? "" : "#" + anchor
fp = clientSideSlug(fp)
let [cleanPath, anchor] = fp.split("#", 2)
anchor = anchor === undefined ? "" : "#" + anchor
return cleanPath + anchor
return cleanPath + anchor
}
```
@ -71,11 +71,11 @@ Place a numeric range inside `{}`.
```ts {2-3,6}
export function trimPathSuffix(fp: string): string {
fp = clientSideSlug(fp)
let [cleanPath, anchor] = fp.split("#", 2)
anchor = anchor === undefined ? "" : "#" + anchor
fp = clientSideSlug(fp)
let [cleanPath, anchor] = fp.split("#", 2)
anchor = anchor === undefined ? "" : "#" + anchor
return cleanPath + anchor
return cleanPath + anchor
}
```
@ -107,11 +107,11 @@ Syntax highlighting has line numbers configured automatically. If you want to st
```ts showLineNumbers{20}
export function trimPathSuffix(fp: string): string {
fp = clientSideSlug(fp)
let [cleanPath, anchor] = fp.split("#", 2)
anchor = anchor === undefined ? "" : "#" + anchor
fp = clientSideSlug(fp)
let [cleanPath, anchor] = fp.split("#", 2)
anchor = anchor === undefined ? "" : "#" + anchor
return cleanPath + anchor
return cleanPath + anchor
}
```

4
docs/features/table of contents.md
View File

@ -1,8 +1,8 @@
---
title: "Table of Contents"
tags:
- component
- feature/transformer
- component
- feature/transformer
---
Quartz can automatically generate a table of contents (TOC) from a list of headings on each page. It will also show you your current scrolling position on the page by highlighting headings you've scrolled through with a different color.

28
docs/features/upcoming features.md
View File

@ -4,20 +4,20 @@ draft: true
## high priority backlog
- static dead link detection
- block links: 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
- docker support
- static dead link detection
- block links: 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
- docker support
## misc backlog
- breadcrumbs component
- cursor chat extension
- https://giscus.app/ extension
- sidenotes? https://github.com/capnfabs/paperesque
- direct match in search using double quotes
- https://help.obsidian.md/Advanced+topics/Using+Obsidian+URI
- audio/video embed styling
- Canvas
- parse all images in page: use this for page lists if applicable?
- CV mode? with print stylesheet
- breadcrumbs component
- cursor chat extension
- https://giscus.app/ extension
- sidenotes? https://github.com/capnfabs/paperesque
- direct match in search using double quotes
- https://help.obsidian.md/Advanced+topics/Using+Obsidian+URI
- audio/video embed styling
- Canvas
- parse all images in page: use this for page lists if applicable?
- CV mode? with print stylesheet

18
docs/features/wikilinks.md
View File

@ -10,15 +10,15 @@ This is enabled as a part of [[Obsidian compatibility]] and can be configured an
## Syntax
- `[[Path to file]]`: produces a link to `Path to file.md` (or `Path-to-file.md`) with the text `Path to file`
- `[[Path to file | Here's the title override]]`: produces a link to `Path to file.md` with the text `Here's the title override`
- `[[Path to file#Anchor]]`: produces a link to the anchor `Anchor` in the file `Path to file.md`
- `[[Path to file#^block-ref]]`: produces a link to the specific block `block-ref` in the file `Path to file.md`
- `[[Path to file]]`: produces a link to `Path to file.md` (or `Path-to-file.md`) with the text `Path to file`
- `[[Path to file | Here's the title override]]`: produces a link to `Path to file.md` with the text `Here's the title override`
- `[[Path to file#Anchor]]`: produces a link to the anchor `Anchor` in the file `Path to file.md`
- `[[Path to file#^block-ref]]`: produces a link to the specific block `block-ref` in the file `Path to file.md`
### Embeds
- `![[Path to image]]`: embeds an image into the page
- `![[Path to image|100x145]]`: embeds an image into the page with dimensions 100px by 145px
- `![[Path to file]]`: transclude an entire page
- `![[Path to file#Anchor]]`: transclude everything under the header `Anchor`
- `![[Path to file#^b15695]]`: transclude block with ID `^b15695`
- `![[Path to image]]`: embeds an image into the page
- `![[Path to image|100x145]]`: embeds an image into the page with dimensions 100px by 145px
- `![[Path to file]]`: transclude an entire page
- `![[Path to file#Anchor]]`: transclude everything under the header `Anchor`
- `![[Path to file#^b15695]]`: transclude block with ID `^b15695`

146
docs/hosting.md
View File

@ -40,48 +40,48 @@ In your local Quartz, create a new file `quartz/.github/workflows/deploy.yml`.
name: Deploy Quartz site to GitHub Pages
on:
push:
branches:
- v4
push:
branches:
- v4
permissions:
contents: read
pages: write
id-token: write
contents: read
pages: write
id-token: write
concurrency:
group: "pages"
cancel-in-progress: false
group: "pages"
cancel-in-progress: false
jobs:
build:
runs-on: ubuntu-22.04
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0 # Fetch all history for git info
- uses: actions/setup-node@v3
with:
node-version: 18.14
- name: Install Dependencies
run: npm ci
- name: Build Quartz
run: npx quartz build
- name: Upload artifact
uses: actions/upload-pages-artifact@v2
with:
path: public
build:
runs-on: ubuntu-22.04
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0 # Fetch all history for git info
- uses: actions/setup-node@v3
with:
node-version: 18.14
- name: Install Dependencies
run: npm ci
- name: Build Quartz
run: npx quartz build
- name: Upload artifact
uses: actions/upload-pages-artifact@v2
with:
path: public
deploy:
needs: build
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v2
deploy:
needs: build
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v2
```
Then:
@ -105,12 +105,12 @@ Here's how to add a custom domain to your GitHub pages deployment.
2. In the "Code and automation" section of the sidebar, click "Pages".
3. Under "Custom Domain", type your custom domain and click "Save".
4. This next step depends on whether you are using an apex domain (`example.com`) or a subdomain (`subdomain.example.com`).
- If you are using an apex domain, navigate to your DNS provider and create an `A` record that points your apex domain to GitHub's name servers which have the following IP addresses:
- `185.199.108.153`
- `185.199.109.153`
- `185.199.110.153`
- `185.199.111.153`
- If you are using a subdomain, navigate to your DNS provider and create a `CNAME` record that points your subdomain to the default domain for your site. For example, if you want to use the subdomain `quartz.example.com` for your user site, create a `CNAME` record that points `quartz.example.com` to `<github-username>.github.io`.
- If you are using an apex domain, navigate to your DNS provider and create an `A` record that points your apex domain to GitHub's name servers which have the following IP addresses:
- `185.199.108.153`
- `185.199.109.153`
- `185.199.110.153`
- `185.199.111.153`
- If you are using a subdomain, navigate to your DNS provider and create a `CNAME` record that points your subdomain to the default domain for your site. For example, if you want to use the subdomain `quartz.example.com` for your user site, create a `CNAME` record that points `quartz.example.com` to `<github-username>.github.io`.
![[dns records.png]]_The above shows a screenshot of Google Domains configured for both `jzhao.xyz` (an apex domain) and `quartz.jzhao.xyz` (a subdomain)._
@ -129,7 +129,7 @@ Before deploying to Vercel, a `vercel.json` file is required at the root of the
```json title="vercel.json"
{
"cleanUrls": true
"cleanUrls": true
}
```
@ -186,43 +186,43 @@ In your local Quartz, create a new file `.gitlab-ci.yaml`.
```yaml title=".gitlab-ci.yaml"
stages:
- build
- deploy
- build
- deploy
variables:
NODE_VERSION: "18.14"
NODE_VERSION: "18.14"
build:
stage: build
rules:
- if: '$CI_COMMIT_REF_NAME == "v4"'
before_script:
- apt-get update -q && apt-get install -y nodejs npm
- npm install -g n
- n $NODE_VERSION
- hash -r
- npm ci
script:
- npx quartz build
artifacts:
paths:
- public
cache:
paths:
- ~/.npm/
key: "${CI_COMMIT_REF_SLUG}-node-${CI_COMMIT_REF_NAME}"
tags:
- docker
stage: build
rules:
- if: '$CI_COMMIT_REF_NAME == "v4"'
before_script:
- apt-get update -q && apt-get install -y nodejs npm
- npm install -g n
- n $NODE_VERSION
- hash -r
- npm ci
script:
- npx quartz build
artifacts:
paths:
- public
cache:
paths:
- ~/.npm/
key: "${CI_COMMIT_REF_SLUG}-node-${CI_COMMIT_REF_NAME}"
tags:
- docker
pages:
stage: deploy
rules:
- if: '$CI_COMMIT_REF_NAME == "v4"'
script:
- echo "Deploying to GitLab Pages..."
artifacts:
paths:
- public
stage: deploy
rules:
- if: '$CI_COMMIT_REF_NAME == "v4"'
script:
- echo "Deploying to GitLab Pages..."
artifacts:
paths:
- public
```
When `.gitlab-ci.yaml` is committed, GitLab will build and deploy the website as a GitLab Page. You can find the url under `Deploy > Pages` in the sidebar.

10
docs/index.md
View File

@ -31,11 +31,11 @@ If you prefer instructions in a video format you can try following Nicole van de
## 🔧 Features
- [[Obsidian compatibility]], [[full-text search]], [[graph view]], note transclusion, [[wikilinks]], [[backlinks]], [[features/Latex|Latex]], [[syntax highlighting]], [[popover previews]], [[Docker Support]], [[i18n|internationalization]] and [many more](./features) right out of the box
- Hot-reload for both configuration and content
- Simple JSX layouts and [[creating components|page components]]
- [[SPA Routing|Ridiculously fast page loads]] and tiny bundle sizes
- Fully-customizable parsing, filtering, and page generation through [[making plugins|plugins]]
- [[Obsidian compatibility]], [[full-text search]], [[graph view]], note transclusion, [[wikilinks]], [[backlinks]], [[features/Latex|Latex]], [[syntax highlighting]], [[popover previews]], [[Docker Support]], [[i18n|internationalization]] and [many more](./features) right out of the box
- Hot-reload for both configuration and content
- Simple JSX layouts and [[creating components|page components]]
- [[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 about the _why_ behind these features on the [[philosophy]] page and a technical overview on the [[architecture]] page.

14
docs/layout.md
View File

@ -8,13 +8,13 @@ Each page is composed of multiple different sections which contain `QuartzCompon
```typescript title="quartz/cfg.ts"
export interface FullPageLayout {
head: QuartzComponent // single component
header: QuartzComponent[] // laid out horizontally
beforeBody: QuartzComponent[] // laid out vertically
pageBody: QuartzComponent // single component
left: QuartzComponent[] // vertical on desktop, horizontal on mobile
right: QuartzComponent[] // vertical on desktop, horizontal on mobile
footer: QuartzComponent // single component
head: QuartzComponent // single component
header: QuartzComponent[] // laid out horizontally
beforeBody: QuartzComponent[] // laid out vertically
pageBody: QuartzComponent // single component
left: QuartzComponent[] // vertical on desktop, horizontal on mobile
right: QuartzComponent[] // vertical on desktop, horizontal on mobile
footer: QuartzComponent // single component
}
```

14
docs/migrating from Quartz 3.md
View File

@ -32,10 +32,10 @@ When running `npx quartz create`, you will be prompted as to how to initialize y
## Things to update
- You will need to update your deploy scripts. See the [[hosting]] guide for more details.
- Ensure that your default branch on GitHub is updated from `hugo` to `v4`.
- [[folder and tag listings|Folder and tag listings]] have also changed.
- Folder descriptions should go under `content/<folder-name>/index.md` where `<folder-name>` is the name of the folder.
- Tag descriptions should go under `content/tags/<tag-name>.md` where `<tag-name>` is the name of the tag.
- Some HTML layout may not be the same between Quartz 3 and Quartz 4. If you depended on a particular HTML hierarchy or class names, you may need to update your custom CSS to reflect these changes.
- If you customized the layout of Quartz 3, you may need to translate these changes from Go templates back to JSX as Quartz 4 no longer uses Hugo. For components, check out the guide on [[creating components]] for more details on this.
- You will need to update your deploy scripts. See the [[hosting]] guide for more details.
- Ensure that your default branch on GitHub is updated from `hugo` to `v4`.
- [[folder and tag listings|Folder and tag listings]] have also changed.
- Folder descriptions should go under `content/<folder-name>/index.md` where `<folder-name>` is the name of the folder.
- Tag descriptions should go under `content/tags/<tag-name>.md` where `<tag-name>` is the name of the tag.
- Some HTML layout may not be the same between Quartz 3 and Quartz 4. If you depended on a particular HTML hierarchy or class names, you may need to update your custom CSS to reflect these changes.
- If you customized the layout of Quartz 3, you may need to translate these changes from Go templates back to JSX as Quartz 4 no longer uses Hugo. For components, check out the guide on [[creating components]] for more details on this.

14
docs/plugins/AliasRedirects.md
View File

@ -1,7 +1,7 @@
---
title: AliasRedirects
tags:
- plugin/emitter
- plugin/emitter
---
This plugin emits HTML redirect pages for aliases and permalinks defined in the frontmatter of content files.
@ -12,7 +12,7 @@ For example, A `foo.md` has the following frontmatter
---
title: "Foo"
alias:
- "bar"
- "bar"
---
```
@ -22,8 +22,8 @@ Note that these are permanent redirect.
The emitter supports the following aliases:
- `aliases`
- `alias`
- `aliases`
- `alias`
> [!note]
> For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page.
@ -32,6 +32,6 @@ This plugin has no configuration options.
## API
- Category: Emitter
- Function name: `Plugin.AliasRedirects()`.
- Source: [`quartz/plugins/emitters/aliases.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/aliases.ts).
- Category: Emitter
- Function name: `Plugin.AliasRedirects()`.
- Source: [`quartz/plugins/emitters/aliases.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/aliases.ts).

8
docs/plugins/Assets.md
View File

@ -1,7 +1,7 @@
---
title: Assets
tags:
- plugin/emitter
- plugin/emitter
---
This plugin emits all non-Markdown static assets in your content folder (like images, videos, HTML, etc). The plugin respects the `ignorePatterns` in the global [[configuration]].
@ -15,6 +15,6 @@ This plugin has no configuration options.
## API
- Category: Emitter
- Function name: `Plugin.Assets()`.
- Source: [`quartz/plugins/emitters/assets.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/assets.ts).
- Category: Emitter
- Function name: `Plugin.Assets()`.
- Source: [`quartz/plugins/emitters/assets.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/assets.ts).

8
docs/plugins/CNAME.md
View File

@ -1,7 +1,7 @@
---
title: CNAME
tags:
- plugin/emitter
- plugin/emitter
---
This plugin emits a `CNAME` record that points your subdomain to the default domain of your site.
@ -17,6 +17,6 @@ This plugin has no configuration options.
## API
- Category: Emitter
- Function name: `Plugin.CNAME()`.
- Source: [`quartz/plugins/emitters/cname.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/cname.ts).
- Category: Emitter
- Function name: `Plugin.CNAME()`.
- Source: [`quartz/plugins/emitters/cname.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/cname.ts).

8
docs/plugins/ComponentResources.md
View File

@ -1,7 +1,7 @@
---
title: ComponentResources
tags:
- plugin/emitter
- plugin/emitter
---
This plugin manages and emits the static resources required for the Quartz framework. This includes CSS stylesheets and JavaScript scripts that enhance the functionality and aesthetics of the generated site. See also the `cdnCaching` option in the `theme` section of the [[configuration]].
@ -13,6 +13,6 @@ This plugin has no configuration options.
## API
- Category: Emitter
- Function name: `Plugin.ComponentResources()`.
- Source: [`quartz/plugins/emitters/componentResources.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/componentResources.ts).
- Category: Emitter
- Function name: `Plugin.ComponentResources()`.
- Source: [`quartz/plugins/emitters/componentResources.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/componentResources.ts).

18
docs/plugins/ContentIndex.md
View File

@ -1,7 +1,7 @@
---
title: ContentIndex
tags:
- plugin/emitter
- plugin/emitter
---
This plugin emits both RSS and an XML sitemap for your site. The [[RSS Feed]] allows users to subscribe to content on your site and the sitemap allows search engines to better index your site. The plugin also emits a `contentIndex.json` file which is used by dynamic frontend components like search and graph.
@ -13,14 +13,14 @@ This plugin emits a comprehensive index of the site's content, generating additi
This plugin accepts the following configuration options:
- `enableSiteMap`: If `true` (default), generates a sitemap XML file (`sitemap.xml`) listing all site URLs for search engines in content discovery.
- `enableRSS`: If `true` (default), produces an RSS feed (`index.xml`) with recent content updates.
- `rssLimit`: Defines the maximum number of entries to include in the RSS feed, helping to focus on the most recent or relevant content. Defaults to `10`.
- `rssFullHtml`: If `true`, the RSS feed includes full HTML content. Otherwise it includes just summaries.
- `includeEmptyFiles`: If `true` (default), content files with no body text are included in the generated index and resources.
- `enableSiteMap`: If `true` (default), generates a sitemap XML file (`sitemap.xml`) listing all site URLs for search engines in content discovery.
- `enableRSS`: If `true` (default), produces an RSS feed (`index.xml`) with recent content updates.
- `rssLimit`: Defines the maximum number of entries to include in the RSS feed, helping to focus on the most recent or relevant content. Defaults to `10`.
- `rssFullHtml`: If `true`, the RSS feed includes full HTML content. Otherwise it includes just summaries.
- `includeEmptyFiles`: If `true` (default), content files with no body text are included in the generated index and resources.
## API
- Category: Emitter
- Function name: `Plugin.ContentIndex()`.
- Source: [`quartz/plugins/emitters/contentIndex.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/contentIndex.ts).
- Category: Emitter
- Function name: `Plugin.ContentIndex()`.
- Source: [`quartz/plugins/emitters/contentIndex.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/contentIndex.ts).

8
docs/plugins/ContentPage.md
View File

@ -1,7 +1,7 @@
---
title: ContentPage
tags:
- plugin/emitter
- plugin/emitter
---
This plugin is a core component of the Quartz framework. It generates the HTML pages for each piece of Markdown content. It emits the full-page [[layout]], including headers, footers, and body content, among others.
@ -13,6 +13,6 @@ This plugin has no configuration options.
## API
- Category: Emitter
- Function name: `Plugin.ContentPage()`.
- Source: [`quartz/plugins/emitters/contentPage.tsx`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/contentPage.tsx).
- Category: Emitter
- Function name: `Plugin.ContentPage()`.
- Source: [`quartz/plugins/emitters/contentPage.tsx`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/contentPage.tsx).

24
docs/plugins/CrawlLinks.md
View File

@ -1,7 +1,7 @@
---
title: CrawlLinks
tags:
- plugin/transformer
- plugin/transformer
---
This plugin parses links and processes them to point to the right places. It is also needed for embedded links (like images). See [[Obsidian compatibility]] for more information.
@ -11,20 +11,20 @@ This plugin parses links and processes them to point to the right places. It is
This plugin accepts the following configuration options:
- `markdownLinkResolution`: Sets the strategy for resolving Markdown paths, can be `"absolute"` (default), `"relative"` or `"shortest"`. You should use the same setting here as in [[Obsidian compatibility|Obsidian]].
- `absolute`: Path relative to the root of the content folder.
- `relative`: Path relative to the file you are linking from.
- `shortest`: Name of the file. If this isn't enough to identify the file, use the full absolute path.
- `prettyLinks`: If `true` (default), simplifies links by removing folder paths, making them more user friendly (e.g. `folder/deeply/nested/note` becomes `note`).
- `openLinksInNewTab`: If `true`, configures external links to open in a new tab. Defaults to `false`.
- `lazyLoad`: If `true`, adds lazy loading to resource elements (`img`, `video`, etc.) to improve page load performance. Defaults to `false`.
- `externalLinkIcon`: Adds an icon next to external links when `true` (default) to visually distinguishing them from internal links.
- `markdownLinkResolution`: Sets the strategy for resolving Markdown paths, can be `"absolute"` (default), `"relative"` or `"shortest"`. You should use the same setting here as in [[Obsidian compatibility|Obsidian]].
- `absolute`: Path relative to the root of the content folder.
- `relative`: Path relative to the file you are linking from.
- `shortest`: Name of the file. If this isn't enough to identify the file, use the full absolute path.
- `prettyLinks`: If `true` (default), simplifies links by removing folder paths, making them more user friendly (e.g. `folder/deeply/nested/note` becomes `note`).
- `openLinksInNewTab`: If `true`, configures external links to open in a new tab. Defaults to `false`.
- `lazyLoad`: If `true`, adds lazy loading to resource elements (`img`, `video`, etc.) to improve page load performance. Defaults to `false`.
- `externalLinkIcon`: Adds an icon next to external links when `true` (default) to visually distinguishing them from internal links.
> [!warning]
> Removing this plugin is _not_ recommended and will likely break the page.
## API
- Category: Transformer
- Function name: `Plugin.CrawlLinks()`.
- Source: [`quartz/plugins/transformers/links.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/links.ts).
- Category: Transformer
- Function name: `Plugin.CrawlLinks()`.
- Source: [`quartz/plugins/transformers/links.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/links.ts).

10
docs/plugins/CreatedModifiedDate.md
View File

@ -1,7 +1,7 @@
---
title: "CreatedModifiedDate"
tags:
- plugin/transformer
- plugin/transformer
---
This plugin determines the created, modified, and published dates for a document using three potential data sources: frontmatter metadata, Git history, and the filesystem. See [[authoring content#Syntax]] for more information.
@ -11,7 +11,7 @@ This plugin determines the created, modified, and published dates for a document
This plugin accepts the following configuration options:
- `priority`: The data sources to consult for date information. Highest priority first. Possible values are `"frontmatter"`, `"git"`, and `"filesystem"`. Defaults to `"frontmatter", "git", "filesystem"]`.
- `priority`: The data sources to consult for date information. Highest priority first. Possible values are `"frontmatter"`, `"git"`, and `"filesystem"`. Defaults to `"frontmatter", "git", "filesystem"]`.
> [!warning]
> If you rely on `git` for dates, make sure `defaultDateType` is set to `modified` in `quartz.config.ts`.
@ -20,6 +20,6 @@ This plugin accepts the following configuration options:
## API
- Category: Transformer
- Function name: `Plugin.CreatedModifiedDate()`.
- Source: [`quartz/plugins/transformers/lastmod.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/lastmod.ts).
- Category: Transformer
- Function name: `Plugin.CreatedModifiedDate()`.
- Source: [`quartz/plugins/transformers/lastmod.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/lastmod.ts).

12
docs/plugins/Description.md
View File

@ -1,7 +1,7 @@
---
title: Description
tags:
- plugin/transformer
- plugin/transformer
---
This plugin generates descriptions that are used as metadata for the HTML `head`, the [[RSS Feed]] and in [[folder and tag listings]] if there is no main body content, the description is used as the text between the title and the listing.
@ -13,11 +13,11 @@ If the frontmatter contains a `description` property, it is used (see [[authorin
This plugin accepts the following configuration options:
- `descriptionLength`: the maximum length of the generated description. Default is 150 characters. The cut off happens after the first _sentence_ that ends after the given length.
- `replaceExternalLinks`: If `true` (default), replace external links with their domain and path in the description (e.g. `https://domain.tld/some_page/another_page?query=hello&target=world` is replaced with `domain.tld/some_page/another_page`).
- `descriptionLength`: the maximum length of the generated description. Default is 150 characters. The cut off happens after the first _sentence_ that ends after the given length.
- `replaceExternalLinks`: If `true` (default), replace external links with their domain and path in the description (e.g. `https://domain.tld/some_page/another_page?query=hello&target=world` is replaced with `domain.tld/some_page/another_page`).
## API
- Category: Transformer
- Function name: `Plugin.Description()`.
- Source: [`quartz/plugins/transformers/description.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/description.ts).
- Category: Transformer
- Function name: `Plugin.Description()`.
- Source: [`quartz/plugins/transformers/description.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/description.ts).

8
docs/plugins/ExplicitPublish.md
View File

@ -1,7 +1,7 @@
---
title: ExplicitPublish
tags:
- plugin/filter
- plugin/filter
---
This plugin filters content based on an explicit `publish` flag in the frontmatter, allowing only content that is explicitly marked for publication to pass through. It's the opt-in version of [[RemoveDrafts]]. See [[private pages]] for more information.
@ -13,6 +13,6 @@ This plugin has no configuration options.
## API
- Category: Filter
- Function name: `Plugin.ExplicitPublish()`.
- Source: [`quartz/plugins/filters/explicit.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/filters/explicit.ts).
- Category: Filter
- Function name: `Plugin.ExplicitPublish()`.
- Source: [`quartz/plugins/filters/explicit.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/filters/explicit.ts).

8
docs/plugins/FolderPage.md
View File

@ -1,7 +1,7 @@
---
title: FolderPage
tags:
- plugin/emitter
- plugin/emitter
---
This plugin generates index pages for folders, creating a listing page for each folder that contains multiple content files. See [[folder and tag listings]] for more information.
@ -17,6 +17,6 @@ The pages are displayed using the `defaultListPageLayout` in `quartz.layouts.ts`
## API
- Category: Emitter
- Function name: `Plugin.FolderPage()`.
- Source: [`quartz/plugins/emitters/folderPage.tsx`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/folderPage.tsx).
- Category: Emitter
- Function name: `Plugin.FolderPage()`.
- Source: [`quartz/plugins/emitters/folderPage.tsx`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/folderPage.tsx).

12
docs/plugins/Frontmatter.md
View File

@ -1,7 +1,7 @@
---
title: "Frontmatter"
tags:
- plugin/transformer
- plugin/transformer
---
This plugin parses the frontmatter of the page using the [gray-matter](https://github.com/jonschlinkert/gray-matter) library. See [[authoring content#Syntax]], [[Obsidian compatibility]] and [[OxHugo compatibility]] for more information.
@ -11,14 +11,14 @@ This plugin parses the frontmatter of the page using the [gray-matter](https://g
This plugin accepts the following configuration options:
- `delimiters`: the delimiters to use for the frontmatter. Can have one value (e.g. `"---"`) or separate values for opening and closing delimiters (e.g. `["---", "~~~"]`). Defaults to `"---"`.
- `language`: the language to use for parsing the frontmatter. Can be `yaml` (default) or `toml`.
- `delimiters`: the delimiters to use for the frontmatter. Can have one value (e.g. `"---"`) or separate values for opening and closing delimiters (e.g. `["---", "~~~"]`). Defaults to `"---"`.
- `language`: the language to use for parsing the frontmatter. Can be `yaml` (default) or `toml`.
> [!warning]
> This plugin must not be removed, otherwise Quartz will break.
## API
- Category: Transformer
- Function name: `Plugin.Frontmatter()`.
- Source: [`quartz/plugins/transformers/frontmatter.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/frontmatter.ts).
- Category: Transformer
- Function name: `Plugin.Frontmatter()`.
- Source: [`quartz/plugins/transformers/frontmatter.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/frontmatter.ts).

12
docs/plugins/GitHubFlavoredMarkdown.md
View File

@ -1,7 +1,7 @@
---
title: GitHubFlavoredMarkdown
tags:
- plugin/transformer
- plugin/transformer
---
This plugin enhances Markdown processing to support GitHub Flavored Markdown (GFM) which adds features like autolink literals, footnotes, strikethrough, tables and tasklists.
@ -13,11 +13,11 @@ In addition, this plugin adds optional features for typographic refinement (such
This plugin accepts the following configuration options:
- `enableSmartyPants`: When true, enables typographic enhancements. Default is true.
- `linkHeadings`: When true, automatically adds links to headings. Default is true.
- `enableSmartyPants`: When true, enables typographic enhancements. Default is true.
- `linkHeadings`: When true, automatically adds links to headings. Default is true.
## API
- Category: Transformer
- Function name: `Plugin.GitHubFlavoredMarkdown()`.
- Source: [`quartz/plugins/transformers/gfm.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/gfm.ts).
- Category: Transformer
- Function name: `Plugin.GitHubFlavoredMarkdown()`.
- Source: [`quartz/plugins/transformers/gfm.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/gfm.ts).

8
docs/plugins/HardLineBreaks.md
View File

@ -1,7 +1,7 @@
---
title: HardLineBreaks
tags:
- plugin/transformer
- plugin/transformer
---
This plugin automatically converts single line breaks in Markdown text into hard line breaks in the HTML output. This plugin is not enabled by default as this doesn't follow the semantics of actual Markdown but you may enable it if you'd like parity with [[Obsidian compatibility|Obsidian]].
@ -13,6 +13,6 @@ This plugin has no configuration options.
## API
- Category: Transformer
- Function name: `Plugin.HardLineBreaks()`.
- Source: [`quartz/plugins/transformers/linebreaks.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/linebreaks.ts).
- Category: Transformer
- Function name: `Plugin.HardLineBreaks()`.
- Source: [`quartz/plugins/transformers/linebreaks.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/linebreaks.ts).

10
docs/plugins/Latex.md
View File

@ -1,7 +1,7 @@
---
title: "Latex"
tags:
- plugin/transformer
- plugin/transformer
---
This plugin adds LaTeX support to Quartz. See [[features/Latex|Latex]] for more information.
@ -11,10 +11,10 @@ This plugin adds LaTeX support to Quartz. See [[features/Latex|Latex]] for more
This plugin accepts the following configuration options:
- `renderEngine`: the engine to use to render LaTeX equations. Can be `"katex"` for [KaTeX](https://katex.org/) or `"mathjax"` for [MathJax](https://www.mathjax.org/) [SVG rendering](https://docs.mathjax.org/en/latest/output/svg.html). Defaults to KaTeX.
- `renderEngine`: the engine to use to render LaTeX equations. Can be `"katex"` for [KaTeX](https://katex.org/) or `"mathjax"` for [MathJax](https://www.mathjax.org/) [SVG rendering](https://docs.mathjax.org/en/latest/output/svg.html). Defaults to KaTeX.
## API
- Category: Transformer
- Function name: `Plugin.Latex()`.
- Source: [`quartz/plugins/transformers/latex.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/latex.ts).
- Category: Transformer
- Function name: `Plugin.Latex()`.
- Source: [`quartz/plugins/transformers/latex.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/latex.ts).

8
docs/plugins/NotFoundPage.md
View File

@ -1,7 +1,7 @@
---
title: NotFoundPage
tags:
- plugin/emitter
- plugin/emitter
---
This plugin emits a 404 (Not Found) page for broken or non-existent URLs.
@ -13,6 +13,6 @@ This plugin has no configuration options.
## API
- Category: Emitter
- Function name: `Plugin.NotFoundPage()`.
- Source: [`quartz/plugins/emitters/404.tsx`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/404.tsx).
- Category: Emitter
- Function name: `Plugin.NotFoundPage()`.
- Source: [`quartz/plugins/emitters/404.tsx`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/404.tsx).

32
docs/plugins/ObsidianFlavoredMarkdown.md
View File

@ -1,7 +1,7 @@
---
title: ObsidianFlavoredMarkdown
tags:
- plugin/transformer
- plugin/transformer
---
This plugin provides support for [[Obsidian compatibility]].
@ -11,24 +11,24 @@ This plugin provides support for [[Obsidian compatibility]].
This plugin accepts the following configuration options:
- `comments`: If `true` (default), enables parsing of `%%` style Obsidian comment blocks.
- `highlight`: If `true` (default), enables parsing of `==` style highlights within content.
- `wikilinks`:If `true` (default), turns [[wikilinks]] into regular links.
- `callouts`: If `true` (default), adds support for [[callouts|callout]] blocks for emphasizing content.
- `mermaid`: If `true` (default), enables [[Mermaid diagrams|Mermaid diagram]] rendering within Markdown files.
- `parseTags`: If `true` (default), parses and links tags within the content.
- `parseArrows`: If `true` (default), transforms arrow symbols into their HTML character equivalents.
- `parseBlockReferences`: If `true` (default), handles block references, linking to specific content blocks.
- `enableInHtmlEmbed`: If `true`, allows embedding of content directly within HTML. Defaults to `false`.
- `enableYouTubeEmbed`: If `true` (default), enables the embedding of YouTube videos and playlists using external image Markdown syntax.
- `enableVideoEmbed`: If `true` (default), enables the embedding of video files.
- `enableCheckbox`: If `true`, adds support for interactive checkboxes in content. Defaults to `false`.
- `comments`: If `true` (default), enables parsing of `%%` style Obsidian comment blocks.
- `highlight`: If `true` (default), enables parsing of `==` style highlights within content.
- `wikilinks`:If `true` (default), turns [[wikilinks]] into regular links.
- `callouts`: If `true` (default), adds support for [[callouts|callout]] blocks for emphasizing content.
- `mermaid`: If `true` (default), enables [[Mermaid diagrams|Mermaid diagram]] rendering within Markdown files.
- `parseTags`: If `true` (default), parses and links tags within the content.
- `parseArrows`: If `true` (default), transforms arrow symbols into their HTML character equivalents.
- `parseBlockReferences`: If `true` (default), handles block references, linking to specific content blocks.
- `enableInHtmlEmbed`: If `true`, allows embedding of content directly within HTML. Defaults to `false`.
- `enableYouTubeEmbed`: If `true` (default), enables the embedding of YouTube videos and playlists using external image Markdown syntax.
- `enableVideoEmbed`: If `true` (default), enables the embedding of video files.
- `enableCheckbox`: If `true`, adds support for interactive checkboxes in content. Defaults to `false`.
> [!warning]
> Don't remove this plugin if you're using [[Obsidian compatibility|Obsidian]] to author the content!
## API
- Category: Transformer
- Function name: `Plugin.ObsidianFlavoredMarkdown()`.
- Source: [`quartz/plugins/transformers/toc.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/toc.ts).
- Category: Transformer
- Function name: `Plugin.ObsidianFlavoredMarkdown()`.
- Source: [`quartz/plugins/transformers/toc.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/toc.ts).

18
docs/plugins/OxHugoFlavoredMarkdown.md
View File

@ -1,7 +1,7 @@
---
title: OxHugoFlavoredMarkdown
tags:
- plugin/transformer
- plugin/transformer
---
This plugin provides support for [ox-hugo](https://github.com/kaushalmodi/ox-hugo) compatibility. See [[OxHugo compatibility]] for more information.
@ -11,11 +11,11 @@ This plugin provides support for [ox-hugo](https://github.com/kaushalmodi/ox-hug
This plugin accepts the following configuration options:
- `wikilinks`: If `true` (default), converts Hugo `{{ relref }}` shortcodes to Quartz [[wikilinks]].
- `removePredefinedAnchor`: If `true` (default), strips predefined anchors from headings.
- `removeHugoShortcode`: If `true` (default), removes Hugo shortcode syntax (`{{}}`) from the content.
- `replaceFigureWithMdImg`: If `true` (default), replaces `<figure/>` with `![]()`.
- `replaceOrgLatex`: If `true` (default), converts Org-mode [[features/Latex|Latex]] fragments to Quartz-compatible LaTeX wrapped in `$` (for inline) and `$$` (for block equations).
- `wikilinks`: If `true` (default), converts Hugo `{{ relref }}` shortcodes to Quartz [[wikilinks]].
- `removePredefinedAnchor`: If `true` (default), strips predefined anchors from headings.
- `removeHugoShortcode`: If `true` (default), removes Hugo shortcode syntax (`{{}}`) from the content.
- `replaceFigureWithMdImg`: If `true` (default), replaces `<figure/>` with `![]()`.
- `replaceOrgLatex`: If `true` (default), converts Org-mode [[features/Latex|Latex]] fragments to Quartz-compatible LaTeX wrapped in `$` (for inline) and `$$` (for block equations).
> [!warning]
> While you can use this together with [[ObsidianFlavoredMarkdown]], it's not recommended because it might mutate the file in unexpected ways. Use with caution.
@ -24,6 +24,6 @@ This plugin accepts the following configuration options:
## API
- Category: Transformer
- Function name: `Plugin.OxHugoFlavoredMarkdown()`.
- Source: [`quartz/plugins/transformers/oxhugofm.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/oxhugofm.ts).
- Category: Transformer
- Function name: `Plugin.OxHugoFlavoredMarkdown()`.
- Source: [`quartz/plugins/transformers/oxhugofm.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/oxhugofm.ts).

8
docs/plugins/RemoveDrafts.md
View File

@ -1,7 +1,7 @@
---
title: RemoveDrafts
tags:
- plugin/filter
- plugin/filter
---
This plugin filters out content from your vault, so that only finalized content is made available. This prevents [[private pages]] from being published. By default, it filters out all pages with `draft: true` in the frontmatter and leaves all other pages intact.
@ -13,6 +13,6 @@ This plugin has no configuration options.
## API
- Category: Filter
- Function name: `Plugin.RemoveDrafts()`.
- Source: [`quartz/plugins/filters/draft.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/filters/draft.ts).
- Category: Filter
- Function name: `Plugin.RemoveDrafts()`.
- Source: [`quartz/plugins/filters/draft.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/filters/draft.ts).

8
docs/plugins/Static.md
View File

@ -1,7 +1,7 @@
---
title: Static
tags:
- plugin/emitter
- plugin/emitter
---
This plugin emits all static resources needed by Quartz. This is used, for example, for fonts and images that need a stable position, such as banners and icons. The plugin respects the `ignorePatterns` in the global [[configuration]].
@ -16,6 +16,6 @@ This plugin has no configuration options.
## API
- Category: Emitter
- Function name: `Plugin.Static()`.
- Source: [`quartz/plugins/emitters/static.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/static.ts).
- Category: Emitter
- Function name: `Plugin.Static()`.
- Source: [`quartz/plugins/emitters/static.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/static.ts).

12
docs/plugins/SyntaxHighlighting.md
View File

@ -1,7 +1,7 @@
---
title: "SyntaxHighlighting"
tags:
- plugin/transformer
- plugin/transformer
---
This plugin is used to add syntax highlighting to code blocks in Quartz. See [[syntax highlighting]] for more information.
@ -11,13 +11,13 @@ This plugin is used to add syntax highlighting to code blocks in Quartz. See [[s
This plugin accepts the following configuration options:
- `theme`: a separate id of one of the [themes bundled with Shikiji](https://shikiji.netlify.app/themes). One for light mode and one for dark mode. Defaults to `theme: { light: "github-light", dark: "github-dark" }`.
- `keepBackground`: If set to `true`, the background of the Shikiji theme will be used. With `false` (default) the Quartz theme color for background will be used instead.
- `theme`: a separate id of one of the [themes bundled with Shikiji](https://shikiji.netlify.app/themes). One for light mode and one for dark mode. Defaults to `theme: { light: "github-light", dark: "github-dark" }`.
- `keepBackground`: If set to `true`, the background of the Shikiji theme will be used. With `false` (default) the Quartz theme color for background will be used instead.
In addition, you can further override the colours in the `quartz/styles/syntax.scss` file.
## API
- Category: Transformer
- Function name: `Plugin.SyntaxHighlighting()`.
- Source: [`quartz/plugins/transformers/syntax.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/syntax.ts).
- Category: Transformer
- Function name: `Plugin.SyntaxHighlighting()`.
- Source: [`quartz/plugins/transformers/syntax.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/syntax.ts).

16
docs/plugins/TableOfContents.md
View File

@ -1,7 +1,7 @@
---
title: TableOfContents
tags:
- plugin/transformer
- plugin/transformer
---
This plugin generates a table of contents (TOC) for Markdown documents. See [[table of contents]] for more information.
@ -11,16 +11,16 @@ This plugin generates a table of contents (TOC) for Markdown documents. See [[ta
This plugin accepts the following configuration options:
- `maxDepth`: Limits the depth of headings included in the TOC, ranging from `1` (top level headings only) to `6` (all heading levels). Default is `3`.
- `minEntries`: The minimum number of heading entries required for the TOC to be displayed. Default is `1`.
- `showByDefault`: If `true` (default), the TOC should be displayed by default. Can be overridden by frontmatter settings.
- `collapseByDefault`: If `true`, the TOC will start in a collapsed state. Default is `false`.
- `maxDepth`: Limits the depth of headings included in the TOC, ranging from `1` (top level headings only) to `6` (all heading levels). Default is `3`.
- `minEntries`: The minimum number of heading entries required for the TOC to be displayed. Default is `1`.
- `showByDefault`: If `true` (default), the TOC should be displayed by default. Can be overridden by frontmatter settings.
- `collapseByDefault`: If `true`, the TOC will start in a collapsed state. Default is `false`.
> [!warning]
> This plugin needs the `Component.TableOfContents` component in `quartz.layout.ts` to determine where to display the TOC. Without it, nothing will be displayed. They should always be added or removed together.
## API
- Category: Transformer
- Function name: `Plugin.TableOfContents()`.
- Source: [`quartz/plugins/transformers/toc.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/toc.ts).
- Category: Transformer
- Function name: `Plugin.TableOfContents()`.
- Source: [`quartz/plugins/transformers/toc.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/toc.ts).

8
docs/plugins/TagPage.md
View File

@ -1,7 +1,7 @@
---
title: TagPage
tags:
- plugin/emitter
- plugin/emitter
---
This plugin emits dedicated pages for each tag used in the content. See [[folder and tag listings]] for more information.
@ -15,6 +15,6 @@ The pages are displayed using the `defaultListPageLayout` in `quartz.layouts.ts`
## API
- Category: Emitter
- Function name: `Plugin.TagPage()`.
- Source: [`quartz/plugins/emitters/tagPage.tsx`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/tagPage.tsx).
- Category: Emitter
- Function name: `Plugin.TagPage()`.
- Source: [`quartz/plugins/emitters/tagPage.tsx`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/tagPage.tsx).

10
docs/setting up your GitHub repository.md
View File

@ -41,8 +41,8 @@ In future updates, you can simply run `npx quartz sync` every time you want to p
>
> Most of these have sensible defaults but you can override them if you have a custom setup:
>
> - `-d` or `--directory`: the content folder. This is normally just `content`
> - `-v` or `--verbose`: print out extra logging information
> - `--commit` or `--no-commit`: whether to make a `git` commit for your changes
> - `--push` or `--no-push`: whether to push updates to your GitHub fork of Quartz
> - `--pull` or `--no-pull`: whether to try and pull in any updates from your GitHub fork (i.e. from other devices) before pushing
> - `-d` or `--directory`: the content folder. This is normally just `content`
> - `-v` or `--verbose`: print out extra logging information
> - `--commit` or `--no-commit`: whether to make a `git` commit for your changes
> - `--push` or `--no-push`: whether to push updates to your GitHub fork of Quartz
> - `--pull` or `--no-pull`: whether to try and pull in any updates from your GitHub fork (i.e. from other devices) before pushing

44
docs/showcase.md
View File

@ -4,27 +4,27 @@ title: "Quartz Showcase"
Want to see what Quartz can do? Here are some cool community gardens:
- [Quartz Documentation (this site!)](https://quartz.jzhao.xyz/)
- [Jacky Zhao's Garden](https://jzhao.xyz/)
- [Socratica Toolbox](https://toolbox.socratica.info/)
- [oldwinter の数字花园](https://garden.oldwinter.top/)
- [Aaron Pham's Garden](https://aarnphm.xyz/)
- [The Quantum Garden](https://quantumgardener.blog/)
- [Abhijeet's Math Wiki](https://abhmul.github.io/quartz/Math-Wiki/)
- [Matt Dunn's Second Brain](https://mattdunn.info/)
- [Pelayo Arbues' Notes](https://pelayoarbues.github.io/)
- [Vince Imbat's Talahardin](https://vinceimbat.com/)
- [🧠🌳 Chad's Mind Garden](https://www.chadly.net/)
- [Pedro MC Fernandes's Topo da Mente](https://www.pmcf.xyz/topo-da-mente/)
- [Mau Camargo's Notkesto](https://notes.camargomau.com/)
- [Caicai's Novels](https://imoko.cc/blog/caicai/)
- [🌊 Collapsed Wave](https://collapsedwave.com/)
- [Sideny's 3D Artist's Handbook](https://sidney-eliot.github.io/3d-artists-handbook/)
- [Mike's AI Garden 🤖🪴](https://mwalton.me/)
- [Brandon Boswell's Garden](https://brandonkboswell.com)
- [Scaling Synthesis - A hypertext research notebook](https://scalingsynthesis.com/)
- [Data Dictionary 🧠](https://glossary.airbyte.com/)
- [sspaeti.com's Second Brain](https://brain.sspaeti.com/)
- [🪴Aster's notebook](https://notes.asterhu.com)
- [Quartz Documentation (this site!)](https://quartz.jzhao.xyz/)
- [Jacky Zhao's Garden](https://jzhao.xyz/)
- [Socratica Toolbox](https://toolbox.socratica.info/)
- [oldwinter の数字花园](https://garden.oldwinter.top/)
- [Aaron Pham's Garden](https://aarnphm.xyz/)
- [The Quantum Garden](https://quantumgardener.blog/)
- [Abhijeet's Math Wiki](https://abhmul.github.io/quartz/Math-Wiki/)
- [Matt Dunn's Second Brain](https://mattdunn.info/)
- [Pelayo Arbues' Notes](https://pelayoarbues.github.io/)
- [Vince Imbat's Talahardin](https://vinceimbat.com/)
- [🧠🌳 Chad's Mind Garden](https://www.chadly.net/)
- [Pedro MC Fernandes's Topo da Mente](https://www.pmcf.xyz/topo-da-mente/)
- [Mau Camargo's Notkesto](https://notes.camargomau.com/)
- [Caicai's Novels](https://imoko.cc/blog/caicai/)
- [🌊 Collapsed Wave](https://collapsedwave.com/)
- [Sideny's 3D Artist's Handbook](https://sidney-eliot.github.io/3d-artists-handbook/)
- [Mike's AI Garden 🤖🪴](https://mwalton.me/)
- [Brandon Boswell's Garden](https://brandonkboswell.com)
- [Scaling Synthesis - A hypertext research notebook](https://scalingsynthesis.com/)
- [Data Dictionary 🧠](https://glossary.airbyte.com/)
- [sspaeti.com's Second Brain](https://brain.sspaeti.com/)
- [🪴Aster's notebook](https://notes.asterhu.com)
If you want to see your own on here, submit a [Pull Request adding yourself to this file](https://github.com/jackyzha0/quartz/blob/v4/docs/showcase.md)!

24
globals.d.ts vendored
View File

@ -1,13 +1,15 @@
export declare global {
interface Document {
addEventListener<K extends keyof CustomEventMap>(
type: K,
listener: (this: Document, ev: CustomEventMap[K]) => void,
): void
dispatchEvent<K extends keyof CustomEventMap>(ev: CustomEventMap[K] | UIEvent): void
}
interface Window {
spaNavigate(url: URL, isBack: boolean = false)
addCleanup(fn: (...args: any[]) => void)
}
interface Document {
addEventListener<K extends keyof CustomEventMap>(
type: K,
listener: (this: Document, ev: CustomEventMap[K]) => void,
): void
dispatchEvent<K extends keyof CustomEventMap>(
ev: CustomEventMap[K] | UIEvent,
): void
}
interface Window {
spaNavigate(url: URL, isBack: boolean = false)
addCleanup(fn: (...args: any[]) => void)
}
}

8
index.d.ts vendored
View File

@ -1,12 +1,12 @@
declare module "*.scss" {
const content: string
export = content
const content: string
export = content
}
// dom custom event
interface CustomEventMap {
nav: CustomEvent<{ url: FullSlug }>
themechange: CustomEvent<{ theme: "light" | "dark" }>
nav: CustomEvent<{ url: FullSlug }>
themechange: CustomEvent<{ theme: "light" | "dark" }>
}
declare const fetchData: Promise<ContentIndex>

222
package.json
View File

@ -1,113 +1,113 @@
{
"name": "@jackyzha0/quartz",
"description": "🌱 publish your digital garden and notes as a website",
"private": true,
"version": "4.2.3",
"type": "module",
"author": "jackyzha0 <j.zhao2k19@gmail.com>",
"license": "MIT",
"homepage": "https://quartz.jzhao.xyz",
"packageManager": "pnpm@8.15.1",
"repository": {
"type": "git",
"url": "https://github.com/jackyzha0/quartz.git"
},
"scripts": {
"docs": "npx quartz build --serve -d docs",
"check": "tsc --noEmit && npx prettier . --check",
"format": "npx prettier . --write",
"test": "tsx ./quartz/util/path.test.ts",
"profile": "0x -D prof ./quartz/bootstrap-cli.mjs build --concurrency=1",
"update": "npx quartz update",
"sync": "npx quartz sync",
"start": "npx quartz build --serve",
"build": "npx quartz build"
},
"engines": {
"npm": ">=9.3.1",
"node": ">=18.14"
},
"keywords": [
"site generator",
"ssg",
"digital-garden",
"markdown",
"blog",
"quartz"
],
"bin": {
"quartz": "./quartz/bootstrap-cli.mjs"
},
"dependencies": {
"@clack/prompts": "^0.7.0",
"@floating-ui/dom": "^1.6.3",
"@napi-rs/simple-git": "0.1.16",
"async-mutex": "^0.4.1",
"chalk": "^5.3.0",
"chokidar": "^3.6.0",
"cli-spinner": "^0.2.10",
"d3": "^7.8.5",
"esbuild-sass-plugin": "^2.16.1",
"flexsearch": "0.7.43",
"github-slugger": "^2.0.0",
"globby": "^14.0.1",
"gray-matter": "^4.0.3",
"hast-util-to-html": "^9.0.0",
"hast-util-to-jsx-runtime": "^2.3.0",
"hast-util-to-string": "^3.0.0",
"is-absolute-url": "^4.0.1",
"js-yaml": "^4.1.0",
"lightningcss": "^1.24.0",
"mdast-util-find-and-replace": "^3.0.1",
"mdast-util-to-hast": "^13.1.0",
"mdast-util-to-string": "^4.0.0",
"micromorph": "^0.4.5",
"preact": "^10.19.6",
"preact-render-to-string": "^6.4.0",
"pretty-bytes": "^6.1.1",
"pretty-time": "^1.1.0",
"reading-time": "^1.5.0",
"rehype-autolink-headings": "^7.1.0",
"rehype-katex": "^7.0.0",
"rehype-mathjax": "^6.0.0",
"rehype-pretty-code": "^0.13.0",
"rehype-raw": "^7.0.0",
"rehype-slug": "^6.0.0",
"remark": "^15.0.1",
"remark-breaks": "^4.0.0",
"remark-frontmatter": "^5.0.0",
"remark-gfm": "^4.0.0",
"remark-math": "^6.0.0",
"remark-parse": "^11.0.0",
"remark-rehype": "^11.1.0",
"remark-smartypants": "^2.1.0",
"rfdc": "^1.3.1",
"rimraf": "^5.0.5",
"serve-handler": "^6.1.5",
"shiki": "^1.1.7",
"source-map-support": "^0.5.21",
"to-vfile": "^8.0.0",
"toml": "^3.0.0",
"unified": "^11.0.4",
"unist-util-visit": "^5.0.0",
"vfile": "^6.0.1",
"workerpool": "^9.1.0",
"ws": "^8.16.0",
"yargs": "^17.7.2"
},
"devDependencies": {
"@types/cli-spinner": "^0.2.3",
"@types/d3": "^7.4.3",
"@types/hast": "^3.0.4",
"@types/js-yaml": "^4.0.9",
"@types/node": "^20.11.25",
"@types/pretty-time": "^1.1.5",
"@types/source-map-support": "^0.5.10",
"@types/ws": "^8.5.10",
"@types/yargs": "^17.0.32",
"esbuild": "^0.19.12",
"prettier": "^3.2.5",
"tsx": "^4.7.1",
"typescript": "^5.4.2"
}
"name": "@jackyzha0/quartz",
"description": "🌱 publish your digital garden and notes as a website",
"private": true,
"version": "4.2.3",
"type": "module",
"author": "jackyzha0 <j.zhao2k19@gmail.com>",
"license": "MIT",
"homepage": "https://quartz.jzhao.xyz",
"packageManager": "pnpm@8.15.1",
"repository": {
"type": "git",
"url": "https://github.com/jackyzha0/quartz.git"
},
"scripts": {
"docs": "npx quartz build --serve -d docs",
"check": "tsc --noEmit && npx prettier . --check",
"format": "npx prettier . --write",
"test": "tsx ./quartz/util/path.test.ts",
"profile": "0x -D prof ./quartz/bootstrap-cli.mjs build --concurrency=1",
"update": "npx quartz update",
"sync": "npx quartz sync",
"start": "npx quartz build --serve",
"build": "npx quartz build"
},
"engines": {
"npm": ">=9.3.1",
"node": ">=18.14"
},
"keywords": [
"site generator",
"ssg",
"digital-garden",
"markdown",
"blog",
"quartz"
],
"bin": {
"quartz": "./quartz/bootstrap-cli.mjs"
},
"dependencies": {
"@clack/prompts": "^0.7.0",
"@floating-ui/dom": "^1.6.3",
"@napi-rs/simple-git": "0.1.16",
"async-mutex": "^0.4.1",
"chalk": "^5.3.0",
"chokidar": "^3.6.0",
"cli-spinner": "^0.2.10",
"d3": "^7.8.5",
"esbuild-sass-plugin": "^2.16.1",
"flexsearch": "0.7.43",
"github-slugger": "^2.0.0",
"globby": "^14.0.1",
"gray-matter": "^4.0.3",
"hast-util-to-html": "^9.0.0",
"hast-util-to-jsx-runtime": "^2.3.0",
"hast-util-to-string": "^3.0.0",
"is-absolute-url": "^4.0.1",
"js-yaml": "^4.1.0",
"lightningcss": "^1.24.0",
"mdast-util-find-and-replace": "^3.0.1",
"mdast-util-to-hast": "^13.1.0",
"mdast-util-to-string": "^4.0.0",
"micromorph": "^0.4.5",
"preact": "^10.19.6",
"preact-render-to-string": "^6.4.0",
"pretty-bytes": "^6.1.1",
"pretty-time": "^1.1.0",
"reading-time": "^1.5.0",
"rehype-autolink-headings": "^7.1.0",
"rehype-katex": "^7.0.0",
"rehype-mathjax": "^6.0.0",
"rehype-pretty-code": "^0.13.0",
"rehype-raw": "^7.0.0",
"rehype-slug": "^6.0.0",
"remark": "^15.0.1",
"remark-breaks": "^4.0.0",
"remark-frontmatter": "^5.0.0",
"remark-gfm": "^4.0.0",
"remark-math": "^6.0.0",
"remark-parse": "^11.0.0",
"remark-rehype": "^11.1.0",
"remark-smartypants": "^2.1.0",
"rfdc": "^1.3.1",
"rimraf": "^5.0.5",
"serve-handler": "^6.1.5",
"shiki": "^1.1.7",
"source-map-support": "^0.5.21",
"to-vfile": "^8.0.0",
"toml": "^3.0.0",
"unified": "^11.0.4",
"unist-util-visit": "^5.0.0",
"vfile": "^6.0.1",
"workerpool": "^9.1.0",
"ws": "^8.16.0",
"yargs": "^17.7.2"
},
"devDependencies": {
"@types/cli-spinner": "^0.2.3",
"@types/d3": "^7.4.3",
"@types/hast": "^3.0.4",
"@types/js-yaml": "^4.0.9",
"@types/node": "^20.11.25",
"@types/pretty-time": "^1.1.5",
"@types/source-map-support": "^0.5.10",
"@types/ws": "^8.5.10",
"@types/yargs": "^17.0.32",
"esbuild": "^0.19.12",
"prettier": "^3.2.5",
"tsx": "^4.7.1",
"typescript": "^5.4.2"
}
}

136
quartz.config.ts
View File

@ -7,76 +7,78 @@ import * as Plugin from "./quartz/plugins"
* See https://quartz.jzhao.xyz/configuration for more information.
*/
const config: QuartzConfig = {
configuration: {
pageTitle: "Forgetful Notes",
enableSPA: true,
enablePopovers: true,
analytics: {
provider: "plausible",
},
locale: "en-US",
baseUrl: "forgetfulnotes.com",
ignorePatterns: ["private", "templates"],
defaultDateType: "modified",
theme: {
fontOrigin: "googleFonts",
cdnCaching: true,
typography: {
header: "Bitter", // Schibsted Grotesk
body: "Poppins", // Source Sans Pro, Poppins
code: "Fira Mono", // IBM Plex Mono
},
colors: {
lightMode: {
light: "#faf8f8", // bg
lightgray: "#e5e5e5", // borders
gray: "#8f8f8f", // graph links, heavy borders
darkgray: "#2e2e2e", // body text
dark: "#1c1c1c", // header text, icons
secondary: "#091217", // links, nodes
tertiary: "#AA336A", // hover states, visited
highlight: "rgba(143, 159, 169, 0.2)", // internal link bg
configuration: {
pageTitle: "Forgetful Notes",
enableSPA: true,
enablePopovers: true,
analytics: {
provider: "plausible",
},
darkMode: {
light: "#1e1e2e", // background
lightgray: "#6c7086", // borders
gray: "#a6adc8", // graph links, heavy borders
darkgray: "#cdd6f4", // body text
dark: "#cdd6f4", // header text, icons
secondary: "#9be895", // links, nodes
tertiary: "#c072c4", // hover states, visited
highlight: "rgba(143, 159, 169, 0.2)", // internal link background
locale: "en-US",
baseUrl: "forgetfulnotes.com",
ignorePatterns: ["private", "templates"],
defaultDateType: "modified",
theme: {
fontOrigin: "googleFonts",
cdnCaching: true,
typography: {
header: "Bitter", // Schibsted Grotesk
body: "Poppins", // Source Sans Pro, Poppins
code: "Fira Mono", // IBM Plex Mono
},
colors: {
lightMode: {
light: "#faf8f8", // bg
lightgray: "#e5e5e5", // borders
gray: "#8f8f8f", // graph links, heavy borders
darkgray: "#2e2e2e", // body text
dark: "#1c1c1c", // header text, icons
secondary: "#091217", // links, nodes
tertiary: "#AA336A", // hover states, visited
highlight: "rgba(143, 159, 169, 0.2)", // internal link bg
},
darkMode: {
light: "#1e1e2e", // background
lightgray: "#6c7086", // borders
gray: "#a6adc8", // graph links, heavy borders
darkgray: "#cdd6f4", // body text
dark: "#cdd6f4", // header text, icons
secondary: "#9be895", // links, nodes
tertiary: "#c072c4", // hover states, visited
highlight: "rgba(143, 159, 169, 0.2)", // internal link background
},
},
},
},
},
},
plugins: {
transformers: [
Plugin.FrontMatter(),
Plugin.CreatedModifiedDate({ priority: ["frontmatter", "filesystem"] }),
Plugin.SyntaxHighlighting(),
Plugin.ObsidianFlavoredMarkdown(),
Plugin.GitHubFlavoredMarkdown(),
Plugin.TableOfContents(),
Plugin.CrawlLinks({ markdownLinkResolution: "shortest" }),
Plugin.Description(),
],
filters: [Plugin.RemoveDrafts()],
emitters: [
Plugin.AliasRedirects(),
Plugin.ComponentResources(),
Plugin.ContentPage(),
Plugin.FolderPage(),
Plugin.TagPage(),
Plugin.ContentIndex({
enableSiteMap: true,
enableRSS: true,
}),
Plugin.Assets(),
Plugin.Static(),
Plugin.NotFoundPage(),
],
},
plugins: {
transformers: [
Plugin.FrontMatter(),
Plugin.CreatedModifiedDate({
priority: ["frontmatter", "filesystem"],
}),
Plugin.SyntaxHighlighting(),
Plugin.ObsidianFlavoredMarkdown(),
Plugin.GitHubFlavoredMarkdown(),
Plugin.TableOfContents(),
Plugin.CrawlLinks({ markdownLinkResolution: "shortest" }),
Plugin.Description(),
],
filters: [Plugin.RemoveDrafts()],
emitters: [
Plugin.AliasRedirects(),
Plugin.ComponentResources(),
Plugin.ContentPage(),
Plugin.FolderPage(),
Plugin.TagPage(),
Plugin.ContentIndex({
enableSiteMap: true,
enableRSS: true,
}),
Plugin.Assets(),
Plugin.Static(),
Plugin.NotFoundPage(),
],
},
}
export default config

84
quartz.layout.ts
View File

@ -3,52 +3,56 @@ import * as Component from "./quartz/components"
// components shared across all pages
export const sharedPageComponents: SharedLayout = {
head: Component.Head(),
header: [],
footer: Component.Footer({
links: {
About: "/About",
Blog: "https://miguelpimentel.do/",
Meta: "/Meta",
GitHub: "https://github.com/semanticdata/",
Source: "https://github.com/semanticdata/forgetful-notes/",
// Tags: "/tags",
},
}),
head: Component.Head(),
header: [],
footer: Component.Footer({
links: {
About: "/About",
Blog: "https://miguelpimentel.do/",
Meta: "/Meta",
GitHub: "https://github.com/semanticdata/",
Source: "https://github.com/semanticdata/forgetful-notes/",
// Tags: "/tags",
},
}),
}
// components for pages that display a single page (e.g. a single note)
export const defaultContentPageLayout: PageLayout = {
beforeBody: [
// Component.Breadcrumbs(),
Component.ArticleTitle(),
// Component.ContentMeta(),
// Component.TagList(),
Component.MobileOnly(Component.Spacer()),
],
left: [
Component.PageTitle(),
Component.MobileOnly(Component.Spacer()),
Component.Search(),
Component.Darkmode(),
Component.DesktopOnly(Component.Explorer()),
],
right: [
Component.Graph(),
Component.DesktopOnly(Component.TableOfContents()),
Component.MobileOnly(Component.Backlinks()),
],
beforeBody: [
// Component.Breadcrumbs(),
Component.ArticleTitle(),
// Component.ContentMeta(),
// Component.TagList(),
Component.MobileOnly(Component.Spacer()),
],
left: [
Component.PageTitle(),
Component.MobileOnly(Component.Spacer()),
Component.Search(),
Component.Darkmode(),
Component.DesktopOnly(Component.Explorer()),
],
right: [
Component.Graph(),
Component.DesktopOnly(Component.TableOfContents()),
Component.MobileOnly(Component.Backlinks()),
],
}
// components for pages that display lists of pages (e.g. tags or folders)
export const defaultListPageLayout: PageLayout = {
beforeBody: [Component.Breadcrumbs(), Component.ArticleTitle(), Component.ContentMeta()],
left: [
Component.PageTitle(),
Component.MobileOnly(Component.Spacer()),
Component.Search(),
Component.Darkmode(),
Component.DesktopOnly(Component.Explorer()),
],
right: [],
beforeBody: [
Component.Breadcrumbs(),
Component.ArticleTitle(),
Component.ContentMeta(),
],
left: [
Component.PageTitle(),
Component.MobileOnly(Component.Spacer()),
Component.Search(),
Component.Darkmode(),
Component.DesktopOnly(Component.Explorer()),
],
right: [],
}

79
quartz/bootstrap-cli.mjs
View File

@ -2,40 +2,55 @@
import yargs from "yargs"
import { hideBin } from "yargs/helpers"
import {
handleBuild,
handleCreate,
handleUpdate,
handleRestore,
handleSync,
handleBuild,
handleCreate,
handleUpdate,
handleRestore,
handleSync,
} from "./cli/handlers.js"
import { CommonArgv, BuildArgv, CreateArgv, SyncArgv } from "./cli/args.js"
import { version } from "./cli/constants.js"
yargs(hideBin(process.argv))
.scriptName("quartz")
.version(version)
.usage("$0 <cmd> [args]")
.command("create", "Initialize Quartz", CreateArgv, async (argv) => {
await handleCreate(argv)
})
.command("update", "Get the latest Quartz updates", CommonArgv, async (argv) => {
await handleUpdate(argv)
})
.command(
"restore",
"Try to restore your content folder from the cache",
CommonArgv,
async (argv) => {
await handleRestore(argv)
},
)
.command("sync", "Sync your Quartz to and from GitHub.", SyncArgv, async (argv) => {
await handleSync(argv)
})
.command("build", "Build Quartz into a bundle of static HTML files", BuildArgv, async (argv) => {
await handleBuild(argv)
})
.showHelpOnFail(false)
.help()
.strict()
.demandCommand().argv
.scriptName("quartz")
.version(version)
.usage("$0 <cmd> [args]")
.command("create", "Initialize Quartz", CreateArgv, async (argv) => {
await handleCreate(argv)
})
.command(
"update",
"Get the latest Quartz updates",
CommonArgv,
async (argv) => {
await handleUpdate(argv)
},
)
.command(
"restore",
"Try to restore your content folder from the cache",
CommonArgv,
async (argv) => {
await handleRestore(argv)
},
)
.command(
"sync",
"Sync your Quartz to and from GitHub.",
SyncArgv,
async (argv) => {
await handleSync(argv)
},
)
.command(
"build",
"Build Quartz into a bundle of static HTML files",
BuildArgv,
async (argv) => {
await handleBuild(argv)
},
)
.showHelpOnFail(false)
.help()
.strict()
.demandCommand().argv

2
quartz/bootstrap-worker.mjs
View File

@ -3,5 +3,5 @@ import workerpool from "workerpool"
const cacheFile = "./.quartz-cache/transpiled-worker.mjs"
const { parseFiles } = await import(cacheFile)
workerpool.worker({
parseFiles,
parseFiles,
})

749
quartz/build.ts
View File

@ -23,389 +23,452 @@ import { getStaticResourcesFromPlugins } from "./plugins"
type Dependencies = Record<string, DepGraph<FilePath> | null>
type BuildData = {
ctx: BuildCtx
ignored: GlobbyFilterFunction
mut: Mutex
initialSlugs: FullSlug[]
// TODO merge contentMap and trackedAssets
contentMap: Map<FilePath, ProcessedContent>
trackedAssets: Set<FilePath>
toRebuild: Set<FilePath>
toRemove: Set<FilePath>
lastBuildMs: number
dependencies: Dependencies
ctx: BuildCtx
ignored: GlobbyFilterFunction
mut: Mutex
initialSlugs: FullSlug[]
// TODO merge contentMap and trackedAssets
contentMap: Map<FilePath, ProcessedContent>
trackedAssets: Set<FilePath>
toRebuild: Set<FilePath>
toRemove: Set<FilePath>
lastBuildMs: number
dependencies: Dependencies
}
type FileEvent = "add" | "change" | "delete"
async function buildQuartz(argv: Argv, mut: Mutex, clientRefresh: () => void) {
const ctx: BuildCtx = {
argv,
cfg,
allSlugs: [],
}
const perf = new PerfTimer()
const output = argv.output
const pluginCount = Object.values(cfg.plugins).flat().length
const pluginNames = (key: "transformers" | "filters" | "emitters") =>
cfg.plugins[key].map((plugin) => plugin.name)
if (argv.verbose) {
console.log(`Loaded ${pluginCount} plugins`)
console.log(` Transformers: ${pluginNames("transformers").join(", ")}`)
console.log(` Filters: ${pluginNames("filters").join(", ")}`)
console.log(` Emitters: ${pluginNames("emitters").join(", ")}`)
}
const release = await mut.acquire()
perf.addEvent("clean")
await rimraf(path.join(output, "*"), { glob: true })
console.log(`Cleaned output directory \`${output}\` in ${perf.timeSince("clean")}`)
perf.addEvent("glob")
const allFiles = await glob("**/*.*", argv.directory, cfg.configuration.ignorePatterns)
const fps = allFiles.filter((fp) => fp.endsWith(".md")).sort()
console.log(
`Found ${fps.length} input files from \`${argv.directory}\` in ${perf.timeSince("glob")}`,
)
const filePaths = fps.map((fp) => joinSegments(argv.directory, fp) as FilePath)
ctx.allSlugs = allFiles.map((fp) => slugifyFilePath(fp as FilePath))
const parsedFiles = await parseMarkdown(ctx, filePaths)
const filteredContent = filterContent(ctx, parsedFiles)
const dependencies: Record<string, DepGraph<FilePath> | null> = {}
// Only build dependency graphs if we're doing a fast rebuild
if (argv.fastRebuild) {
const staticResources = getStaticResourcesFromPlugins(ctx)
for (const emitter of cfg.plugins.emitters) {
dependencies[emitter.name] =
(await emitter.getDependencyGraph?.(ctx, filteredContent, staticResources)) ?? null
const ctx: BuildCtx = {
argv,
cfg,
allSlugs: [],
}
}
await emitContent(ctx, filteredContent)
console.log(chalk.green(`Done processing ${fps.length} files in ${perf.timeSince()}`))
release()
const perf = new PerfTimer()
const output = argv.output
if (argv.serve) {
return startServing(ctx, mut, parsedFiles, clientRefresh, dependencies)
}
const pluginCount = Object.values(cfg.plugins).flat().length
const pluginNames = (key: "transformers" | "filters" | "emitters") =>
cfg.plugins[key].map((plugin) => plugin.name)
if (argv.verbose) {
console.log(`Loaded ${pluginCount} plugins`)
console.log(` Transformers: ${pluginNames("transformers").join(", ")}`)
console.log(` Filters: ${pluginNames("filters").join(", ")}`)
console.log(` Emitters: ${pluginNames("emitters").join(", ")}`)
}
const release = await mut.acquire()
perf.addEvent("clean")
await rimraf(path.join(output, "*"), { glob: true })
console.log(
`Cleaned output directory \`${output}\` in ${perf.timeSince("clean")}`,
)
perf.addEvent("glob")
const allFiles = await glob(
"**/*.*",
argv.directory,
cfg.configuration.ignorePatterns,
)
const fps = allFiles.filter((fp) => fp.endsWith(".md")).sort()
console.log(
`Found ${fps.length} input files from \`${argv.directory}\` in ${perf.timeSince("glob")}`,
)
const filePaths = fps.map(
(fp) => joinSegments(argv.directory, fp) as FilePath,
)
ctx.allSlugs = allFiles.map((fp) => slugifyFilePath(fp as FilePath))
const parsedFiles = await parseMarkdown(ctx, filePaths)
const filteredContent = filterContent(ctx, parsedFiles)
const dependencies: Record<string, DepGraph<FilePath> | null> = {}
// Only build dependency graphs if we're doing a fast rebuild
if (argv.fastRebuild) {
const staticResources = getStaticResourcesFromPlugins(ctx)
for (const emitter of cfg.plugins.emitters) {
dependencies[emitter.name] =
(await emitter.getDependencyGraph?.(
ctx,
filteredContent,
staticResources,
)) ?? null
}
}
await emitContent(ctx, filteredContent)
console.log(
chalk.green(
`Done processing ${fps.length} files in ${perf.timeSince()}`,
),
)
release()
if (argv.serve) {
return startServing(ctx, mut, parsedFiles, clientRefresh, dependencies)
}
}
// setup watcher for rebuilds
async function startServing(
ctx: BuildCtx,
mut: Mutex,
initialContent: ProcessedContent[],
clientRefresh: () => void,
dependencies: Dependencies, // emitter name: dep graph
ctx: BuildCtx,
mut: Mutex,
initialContent: ProcessedContent[],
clientRefresh: () => void,
dependencies: Dependencies, // emitter name: dep graph
) {
const { argv } = ctx
const { argv } = ctx
// cache file parse results
const contentMap = new Map<FilePath, ProcessedContent>()
for (const content of initialContent) {
const [_tree, vfile] = content
contentMap.set(vfile.data.filePath!, content)
}
// cache file parse results
const contentMap = new Map<FilePath, ProcessedContent>()
for (const content of initialContent) {
const [_tree, vfile] = content
contentMap.set(vfile.data.filePath!, content)
}
const buildData: BuildData = {
ctx,
mut,
dependencies,
contentMap,
ignored: await isGitIgnored(),
initialSlugs: ctx.allSlugs,
toRebuild: new Set<FilePath>(),
toRemove: new Set<FilePath>(),
trackedAssets: new Set<FilePath>(),
lastBuildMs: 0,
}
const buildData: BuildData = {
ctx,
mut,
dependencies,
contentMap,
ignored: await isGitIgnored(),
initialSlugs: ctx.allSlugs,
toRebuild: new Set<FilePath>(),
toRemove: new Set<FilePath>(),
trackedAssets: new Set<FilePath>(),
lastBuildMs: 0,
}
const watcher = chokidar.watch(".", {
persistent: true,
cwd: argv.directory,
ignoreInitial: true,
})
const watcher = chokidar.watch(".", {
persistent: true,
cwd: argv.directory,
ignoreInitial: true,
})
const buildFromEntry = argv.fastRebuild ? partialRebuildFromEntrypoint : rebuildFromEntrypoint
watcher
.on("add", (fp) => buildFromEntry(fp, "add", clientRefresh, buildData))
.on("change", (fp) => buildFromEntry(fp, "change", clientRefresh, buildData))
.on("unlink", (fp) => buildFromEntry(fp, "delete", clientRefresh, buildData))
const buildFromEntry = argv.fastRebuild
? partialRebuildFromEntrypoint
: rebuildFromEntrypoint
watcher
.on("add", (fp) => buildFromEntry(fp, "add", clientRefresh, buildData))
.on("change", (fp) =>
buildFromEntry(fp, "change", clientRefresh, buildData),
)
.on("unlink", (fp) =>
buildFromEntry(fp, "delete", clientRefresh, buildData),
)
return async () => {
await watcher.close()
}
return async () => {
await watcher.close()
}
}
async function partialRebuildFromEntrypoint(
filepath: string,
action: FileEvent,
clientRefresh: () => void,
buildData: BuildData, // note: this function mutates buildData
filepath: string,
action: FileEvent,
clientRefresh: () => void,
buildData: BuildData, // note: this function mutates buildData
) {
const { ctx, ignored, dependencies, contentMap, mut, toRemove } = buildData
const { argv, cfg } = ctx
const { ctx, ignored, dependencies, contentMap, mut, toRemove } = buildData
const { argv, cfg } = ctx
// don't do anything for gitignored files
if (ignored(filepath)) {
return
}
// don't do anything for gitignored files
if (ignored(filepath)) {
return
}
const buildStart = new Date().getTime()
buildData.lastBuildMs = buildStart
const release = await mut.acquire()
if (buildData.lastBuildMs > buildStart) {
const buildStart = new Date().getTime()
buildData.lastBuildMs = buildStart
const release = await mut.acquire()
if (buildData.lastBuildMs > buildStart) {
release()
return
}
const perf = new PerfTimer()
console.log(chalk.yellow("Detected change, rebuilding..."))
// UPDATE DEP GRAPH
const fp = joinSegments(argv.directory, toPosixPath(filepath)) as FilePath
const staticResources = getStaticResourcesFromPlugins(ctx)
let processedFiles: ProcessedContent[] = []
switch (action) {
case "add":
// add to cache when new file is added
processedFiles = await parseMarkdown(ctx, [fp])
processedFiles.forEach(([tree, vfile]) =>
contentMap.set(vfile.data.filePath!, [tree, vfile]),
)
// update the dep graph by asking all emitters whether they depend on this file
for (const emitter of cfg.plugins.emitters) {
const emitterGraph =
(await emitter.getDependencyGraph?.(
ctx,
processedFiles,
staticResources,
)) ?? null
if (emitterGraph) {
const existingGraph = dependencies[emitter.name]
if (existingGraph !== null) {
existingGraph.mergeGraph(emitterGraph)
} else {
// might be the first time we're adding a mardown file
dependencies[emitter.name] = emitterGraph
}
}
}
break
case "change":
// invalidate cache when file is changed
processedFiles = await parseMarkdown(ctx, [fp])
processedFiles.forEach(([tree, vfile]) =>
contentMap.set(vfile.data.filePath!, [tree, vfile]),
)
// only content files can have added/removed dependencies because of transclusions
if (path.extname(fp) === ".md") {
for (const emitter of cfg.plugins.emitters) {
// get new dependencies from all emitters for this file
const emitterGraph =
(await emitter.getDependencyGraph?.(
ctx,
processedFiles,
staticResources,
)) ?? null
// only update the graph if the emitter plugin uses the changed file
// eg. Assets plugin ignores md files, so we skip updating the graph
if (emitterGraph?.hasNode(fp)) {
// merge the new dependencies into the dep graph
dependencies[emitter.name]?.updateIncomingEdgesForNode(
emitterGraph,
fp,
)
}
}
}
break
case "delete":
toRemove.add(fp)
break
}
if (argv.verbose) {
console.log(`Updated dependency graphs in ${perf.timeSince()}`)
}
// EMIT
perf.addEvent("rebuild")
let emittedFiles = 0
for (const emitter of cfg.plugins.emitters) {
const depGraph = dependencies[emitter.name]
// emitter hasn't defined a dependency graph. call it with all processed files
if (depGraph === null) {
if (argv.verbose) {
console.log(
`Emitter ${emitter.name} doesn't define a dependency graph. Calling it with all files...`,
)
}
const files = [...contentMap.values()].filter(
([_node, vfile]) => !toRemove.has(vfile.data.filePath!),
)
const emittedFps = await emitter.emit(ctx, files, staticResources)
if (ctx.argv.verbose) {
for (const file of emittedFps) {
console.log(`[emit:${emitter.name}] ${file}`)
}
}
emittedFiles += emittedFps.length
continue
}
// only call the emitter if it uses this file
if (depGraph.hasNode(fp)) {
// re-emit using all files that are needed for the downstream of this file
// eg. for ContentIndex, the dep graph could be:
// a.md --> contentIndex.json
// b.md ------^
//
// if a.md changes, we need to re-emit contentIndex.json,
// and supply [a.md, b.md] to the emitter
const upstreams = [
...depGraph.getLeafNodeAncestors(fp),
] as FilePath[]
const upstreamContent = upstreams
// filter out non-markdown files
.filter((file) => contentMap.has(file))
// if file was deleted, don't give it to the emitter
.filter((file) => !toRemove.has(file))
.map((file) => contentMap.get(file)!)
const emittedFps = await emitter.emit(
ctx,
upstreamContent,
staticResources,
)
if (ctx.argv.verbose) {
for (const file of emittedFps) {
console.log(`[emit:${emitter.name}] ${file}`)
}
}
emittedFiles += emittedFps.length
}
}
console.log(
`Emitted ${emittedFiles} files to \`${argv.output}\` in ${perf.timeSince("rebuild")}`,
)
// CLEANUP
const destinationsToDelete = new Set<FilePath>()
for (const file of toRemove) {
// remove from cache
contentMap.delete(file)
Object.values(dependencies).forEach((depGraph) => {
// remove the node from dependency graphs
depGraph?.removeNode(file)
// remove any orphan nodes. eg if a.md is deleted, a.html is orphaned and should be removed
const orphanNodes = depGraph?.removeOrphanNodes()
orphanNodes?.forEach((node) => {
// only delete files that are in the output directory
if (node.startsWith(argv.output)) {
destinationsToDelete.add(node)
}
})
})
}
await rimraf([...destinationsToDelete])
console.log(chalk.green(`Done rebuilding in ${perf.timeSince()}`))
toRemove.clear()
release()
return
}
const perf = new PerfTimer()
console.log(chalk.yellow("Detected change, rebuilding..."))
// UPDATE DEP GRAPH
const fp = joinSegments(argv.directory, toPosixPath(filepath)) as FilePath
const staticResources = getStaticResourcesFromPlugins(ctx)
let processedFiles: ProcessedContent[] = []
switch (action) {
case "add":
// add to cache when new file is added
processedFiles = await parseMarkdown(ctx, [fp])
processedFiles.forEach(([tree, vfile]) => contentMap.set(vfile.data.filePath!, [tree, vfile]))
// update the dep graph by asking all emitters whether they depend on this file
for (const emitter of cfg.plugins.emitters) {
const emitterGraph =
(await emitter.getDependencyGraph?.(ctx, processedFiles, staticResources)) ?? null
if (emitterGraph) {
const existingGraph = dependencies[emitter.name]
if (existingGraph !== null) {
existingGraph.mergeGraph(emitterGraph)
} else {
// might be the first time we're adding a mardown file
dependencies[emitter.name] = emitterGraph
}
}
}
break
case "change":
// invalidate cache when file is changed
processedFiles = await parseMarkdown(ctx, [fp])
processedFiles.forEach(([tree, vfile]) => contentMap.set(vfile.data.filePath!, [tree, vfile]))
// only content files can have added/removed dependencies because of transclusions
if (path.extname(fp) === ".md") {
for (const emitter of cfg.plugins.emitters) {
// get new dependencies from all emitters for this file
const emitterGraph =
(await emitter.getDependencyGraph?.(ctx, processedFiles, staticResources)) ?? null
// only update the graph if the emitter plugin uses the changed file
// eg. Assets plugin ignores md files, so we skip updating the graph
if (emitterGraph?.hasNode(fp)) {
// merge the new dependencies into the dep graph
dependencies[emitter.name]?.updateIncomingEdgesForNode(emitterGraph, fp)
}
}
}
break
case "delete":
toRemove.add(fp)
break
}
if (argv.verbose) {
console.log(`Updated dependency graphs in ${perf.timeSince()}`)
}
// EMIT
perf.addEvent("rebuild")
let emittedFiles = 0
for (const emitter of cfg.plugins.emitters) {
const depGraph = dependencies[emitter.name]
// emitter hasn't defined a dependency graph. call it with all processed files
if (depGraph === null) {
if (argv.verbose) {
console.log(
`Emitter ${emitter.name} doesn't define a dependency graph. Calling it with all files...`,
)
}
const files = [...contentMap.values()].filter(
([_node, vfile]) => !toRemove.has(vfile.data.filePath!),
)
const emittedFps = await emitter.emit(ctx, files, staticResources)
if (ctx.argv.verbose) {
for (const file of emittedFps) {
console.log(`[emit:${emitter.name}] ${file}`)
}
}
emittedFiles += emittedFps.length
continue
}
// only call the emitter if it uses this file
if (depGraph.hasNode(fp)) {
// re-emit using all files that are needed for the downstream of this file
// eg. for ContentIndex, the dep graph could be:
// a.md --> contentIndex.json
// b.md ------^
//
// if a.md changes, we need to re-emit contentIndex.json,
// and supply [a.md, b.md] to the emitter
const upstreams = [...depGraph.getLeafNodeAncestors(fp)] as FilePath[]
const upstreamContent = upstreams
// filter out non-markdown files
.filter((file) => contentMap.has(file))
// if file was deleted, don't give it to the emitter
.filter((file) => !toRemove.has(file))
.map((file) => contentMap.get(file)!)
const emittedFps = await emitter.emit(ctx, upstreamContent, staticResources)
if (ctx.argv.verbose) {
for (const file of emittedFps) {
console.log(`[emit:${emitter.name}] ${file}`)
}
}
emittedFiles += emittedFps.length
}
}
console.log(`Emitted ${emittedFiles} files to \`${argv.output}\` in ${perf.timeSince("rebuild")}`)
// CLEANUP
const destinationsToDelete = new Set<FilePath>()
for (const file of toRemove) {
// remove from cache
contentMap.delete(file)
Object.values(dependencies).forEach((depGraph) => {
// remove the node from dependency graphs
depGraph?.removeNode(file)
// remove any orphan nodes. eg if a.md is deleted, a.html is orphaned and should be removed
const orphanNodes = depGraph?.removeOrphanNodes()
orphanNodes?.forEach((node) => {
// only delete files that are in the output directory
if (node.startsWith(argv.output)) {
destinationsToDelete.add(node)
}
})
})
}
await rimraf([...destinationsToDelete])
console.log(chalk.green(`Done rebuilding in ${perf.timeSince()}`))
toRemove.clear()
release()
clientRefresh()
clientRefresh()
}
async function rebuildFromEntrypoint(
fp: string,
action: FileEvent,
clientRefresh: () => void,
buildData: BuildData, // note: this function mutates buildData
fp: string,
action: FileEvent,
clientRefresh: () => void,
buildData: BuildData, // note: this function mutates buildData
) {
const { ctx, ignored, mut, initialSlugs, contentMap, toRebuild, toRemove, trackedAssets } =
buildData
const {
ctx,
ignored,
mut,
initialSlugs,
contentMap,
toRebuild,
toRemove,
trackedAssets,
} = buildData
const { argv } = ctx
const { argv } = ctx
// don't do anything for gitignored files
if (ignored(fp)) {
return
}
// don't do anything for gitignored files
if (ignored(fp)) {
return
}
// dont bother rebuilding for non-content files, just track and refresh
fp = toPosixPath(fp)
const filePath = joinSegments(argv.directory, fp) as FilePath
if (path.extname(fp) !== ".md") {
if (action === "add" || action === "change") {
trackedAssets.add(filePath)
} else if (action === "delete") {
trackedAssets.delete(filePath)
}
clientRefresh()
return
}
// dont bother rebuilding for non-content files, just track and refresh
fp = toPosixPath(fp)
const filePath = joinSegments(argv.directory, fp) as FilePath
if (path.extname(fp) !== ".md") {
if (action === "add" || action === "change") {
trackedAssets.add(filePath)
toRebuild.add(filePath)
} else if (action === "delete") {
trackedAssets.delete(filePath)
toRemove.add(filePath)
}
clientRefresh()
return
}
if (action === "add" || action === "change") {
toRebuild.add(filePath)
} else if (action === "delete") {
toRemove.add(filePath)
}
const buildStart = new Date().getTime()
buildData.lastBuildMs = buildStart
const release = await mut.acquire()
const buildStart = new Date().getTime()
buildData.lastBuildMs = buildStart
const release = await mut.acquire()
// there's another build after us, release and let them do it
if (buildData.lastBuildMs > buildStart) {
release()
return
}
const perf = new PerfTimer()
console.log(chalk.yellow("Detected change, rebuilding..."))
try {
const filesToRebuild = [...toRebuild].filter((fp) => !toRemove.has(fp))
const trackedSlugs = [
...new Set([...contentMap.keys(), ...toRebuild, ...trackedAssets]),
]
.filter((fp) => !toRemove.has(fp))
.map((fp) =>
slugifyFilePath(
path.posix.relative(argv.directory, fp) as FilePath,
),
)
ctx.allSlugs = [...new Set([...initialSlugs, ...trackedSlugs])]
const parsedContent = await parseMarkdown(ctx, filesToRebuild)
for (const content of parsedContent) {
const [_tree, vfile] = content
contentMap.set(vfile.data.filePath!, content)
}
for (const fp of toRemove) {
contentMap.delete(fp)
}
const parsedFiles = [...contentMap.values()]
const filteredContent = filterContent(ctx, parsedFiles)
// TODO: we can probably traverse the link graph to figure out what's safe to delete here
// instead of just deleting everything
await rimraf(path.join(argv.output, ".*"), { glob: true })
await emitContent(ctx, filteredContent)
console.log(chalk.green(`Done rebuilding in ${perf.timeSince()}`))
} catch (err) {
console.log(
chalk.yellow(
`Rebuild failed. Waiting on a change to fix the error...`,
),
)
if (argv.verbose) {
console.log(chalk.red(err))
}
}
// there's another build after us, release and let them do it
if (buildData.lastBuildMs > buildStart) {
release()
return
}
const perf = new PerfTimer()
console.log(chalk.yellow("Detected change, rebuilding..."))
try {
const filesToRebuild = [...toRebuild].filter((fp) => !toRemove.has(fp))
const trackedSlugs = [...new Set([...contentMap.keys(), ...toRebuild, ...trackedAssets])]
.filter((fp) => !toRemove.has(fp))
.map((fp) => slugifyFilePath(path.posix.relative(argv.directory, fp) as FilePath))
ctx.allSlugs = [...new Set([...initialSlugs, ...trackedSlugs])]
const parsedContent = await parseMarkdown(ctx, filesToRebuild)
for (const content of parsedContent) {
const [_tree, vfile] = content
contentMap.set(vfile.data.filePath!, content)
}
for (const fp of toRemove) {
contentMap.delete(fp)
}
const parsedFiles = [...contentMap.values()]
const filteredContent = filterContent(ctx, parsedFiles)
// TODO: we can probably traverse the link graph to figure out what's safe to delete here
// instead of just deleting everything
await rimraf(path.join(argv.output, ".*"), { glob: true })
await emitContent(ctx, filteredContent)
console.log(chalk.green(`Done rebuilding in ${perf.timeSince()}`))
} catch (err) {
console.log(chalk.yellow(`Rebuild failed. Waiting on a change to fix the error...`))
if (argv.verbose) {
console.log(chalk.red(err))
}
}
release()
clientRefresh()
toRebuild.clear()
toRemove.clear()
clientRefresh()
toRebuild.clear()
toRemove.clear()
}
export default async (argv: Argv, mut: Mutex, clientRefresh: () => void) => {
try {
return await buildQuartz(argv, mut, clientRefresh)
} catch (err) {
trace("\nExiting Quartz due to a fatal error", err as Error)
}
try {
return await buildQuartz(argv, mut, clientRefresh)
} catch (err) {
trace("\nExiting Quartz due to a fatal error", err as Error)
}
}

108
quartz/cfg.ts
View File

@ -5,68 +5,68 @@ import { PluginTypes } from "./plugins/types"
import { Theme } from "./util/theme"
export type Analytics =
| null
| {
provider: "plausible"
host?: string
}
| {
provider: "google"
tagId: string
}
| {
provider: "umami"
websiteId: string
host?: string
}
| {
provider: "goatcounter"
websiteId: string
host?: string
scriptSrc?: string
}
| null
| {
provider: "plausible"
host?: string
}
| {
provider: "google"
tagId: string
}
| {
provider: "umami"
websiteId: string
host?: string
}
| {
provider: "goatcounter"
websiteId: string
host?: string
scriptSrc?: string
}
export interface GlobalConfiguration {
pageTitle: string
/** Whether to enable single-page-app style rendering. this prevents flashes of unstyled content and improves smoothness of Quartz */
enableSPA: boolean
/** Whether to display Wikipedia-style popovers when hovering over links */
enablePopovers: boolean
/** Analytics mode */
analytics: Analytics
/** Glob patterns to not search */
ignorePatterns: string[]
/** Whether to use created, modified, or published as the default type of date */
defaultDateType: ValidDateType
/** Base URL to use for CNAME files, sitemaps, and RSS feeds that require an absolute URL.
* Quartz will avoid using this as much as possible and use relative URLs most of the time
*/
baseUrl?: string
theme: Theme
/**
* Allow to translate the date in the language of your choice.
* Also used for UI translation (default: en-US)
* Need to be formated following BCP 47: https://en.wikipedia.org/wiki/IETF_language_tag
* The first part is the language (en) and the second part is the script/region (US)
* Language Codes: https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes
* Region Codes: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
*/
locale: ValidLocale
pageTitle: string
/** Whether to enable single-page-app style rendering. this prevents flashes of unstyled content and improves smoothness of Quartz */
enableSPA: boolean
/** Whether to display Wikipedia-style popovers when hovering over links */
enablePopovers: boolean
/** Analytics mode */
analytics: Analytics
/** Glob patterns to not search */
ignorePatterns: string[]
/** Whether to use created, modified, or published as the default type of date */
defaultDateType: ValidDateType
/** Base URL to use for CNAME files, sitemaps, and RSS feeds that require an absolute URL.
* Quartz will avoid using this as much as possible and use relative URLs most of the time
*/
baseUrl?: string
theme: Theme
/**
* Allow to translate the date in the language of your choice.
* Also used for UI translation (default: en-US)
* Need to be formated following BCP 47: https://en.wikipedia.org/wiki/IETF_language_tag
* The first part is the language (en) and the second part is the script/region (US)
* Language Codes: https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes
* Region Codes: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
*/
locale: ValidLocale
}
export interface QuartzConfig {
configuration: GlobalConfiguration
plugins: PluginTypes
configuration: GlobalConfiguration
plugins: PluginTypes
}
export interface FullPageLayout {
head: QuartzComponent
header: QuartzComponent[]
beforeBody: QuartzComponent[]
pageBody: QuartzComponent
left: QuartzComponent[]
right: QuartzComponent[]
footer: QuartzComponent
head: QuartzComponent
header: QuartzComponent[]
beforeBody: QuartzComponent[]
pageBody: QuartzComponent
left: QuartzComponent[]
right: QuartzComponent[]
footer: QuartzComponent
}
export type PageLayout = Pick<FullPageLayout, "beforeBody" | "left" | "right">

195
quartz/cli/args.js
View File

@ -1,108 +1,109 @@
export const CommonArgv = {
directory: {
string: true,
alias: ["d"],
default: "content",
describe: "directory to look for content files",
},
verbose: {
boolean: true,
alias: ["v"],
default: false,
describe: "print out extra logging information",
},
directory: {
string: true,
alias: ["d"],
default: "content",
describe: "directory to look for content files",
},
verbose: {
boolean: true,
alias: ["v"],
default: false,
describe: "print out extra logging information",
},
}
export const CreateArgv = {
...CommonArgv,
source: {
string: true,
alias: ["s"],
describe: "source directory to copy/create symlink from",
},
strategy: {
string: true,
alias: ["X"],
choices: ["new", "copy", "symlink"],
describe: "strategy for content folder setup",
},
links: {
string: true,
alias: ["l"],
choices: ["absolute", "shortest", "relative"],
describe: "strategy to resolve links",
},
...CommonArgv,
source: {
string: true,
alias: ["s"],
describe: "source directory to copy/create symlink from",
},
strategy: {
string: true,
alias: ["X"],
choices: ["new", "copy", "symlink"],
describe: "strategy for content folder setup",
},
links: {
string: true,
alias: ["l"],
choices: ["absolute", "shortest", "relative"],
describe: "strategy to resolve links",
},
}
export const SyncArgv = {
...CommonArgv,
commit: {
boolean: true,
default: true,
describe: "create a git commit for your unsaved changes",
},
message: {
string: true,
alias: ["m"],
describe: "option to override the default Quartz commit message",
},
push: {
boolean: true,
default: true,
describe: "push updates to your Quartz fork",
},
pull: {
boolean: true,
default: true,
describe: "pull updates from your Quartz fork",
},
...CommonArgv,
commit: {
boolean: true,
default: true,
describe: "create a git commit for your unsaved changes",
},
message: {
string: true,
alias: ["m"],
describe: "option to override the default Quartz commit message",
},
push: {
boolean: true,
default: true,
describe: "push updates to your Quartz fork",
},
pull: {
boolean: true,
default: true,
describe: "pull updates from your Quartz fork",
},
}
export const BuildArgv = {
...CommonArgv,
output: {
string: true,
alias: ["o"],
default: "public",
describe: "output folder for files",
},
serve: {
boolean: true,
default: false,
describe: "run a local server to live-preview your Quartz",
},
fastRebuild: {
boolean: true,
default: false,
describe: "[experimental] rebuild only the changed files",
},
baseDir: {
string: true,
default: "",
describe: "base path to serve your local server on",
},
port: {
number: true,
default: 8080,
describe: "port to serve Quartz on",
},
wsPort: {
number: true,
default: 3001,
describe: "port to use for WebSocket-based hot-reload notifications",
},
remoteDevHost: {
string: true,
default: "",
describe: "A URL override for the websocket connection if you are not developing on localhost",
},
bundleInfo: {
boolean: true,
default: false,
describe: "show detailed bundle information",
},
concurrency: {
number: true,
describe: "how many threads to use to parse notes",
},
...CommonArgv,
output: {
string: true,
alias: ["o"],
default: "public",
describe: "output folder for files",
},
serve: {
boolean: true,
default: false,
describe: "run a local server to live-preview your Quartz",
},
fastRebuild: {
boolean: true,
default: false,
describe: "[experimental] rebuild only the changed files",
},
baseDir: {
string: true,
default: "",
describe: "base path to serve your local server on",
},
port: {
number: true,
default: 8080,
describe: "port to serve Quartz on",
},
wsPort: {
number: true,
default: 3001,
describe: "port to use for WebSocket-based hot-reload notifications",
},
remoteDevHost: {
string: true,
default: "",
describe:
"A URL override for the websocket connection if you are not developing on localhost",
},
bundleInfo: {
boolean: true,
default: false,
describe: "show detailed bundle information",
},
concurrency: {
number: true,
describe: "how many threads to use to parse notes",
},
}

960
quartz/cli/handlers.js
View File

File diff suppressed because it is too large Load Diff

78
quartz/cli/helpers.js
View File

@ -5,50 +5,60 @@ import { spawnSync } from "child_process"
import fs from "fs"
export function escapePath(fp) {
return fp
.replace(/\\ /g, " ") // unescape spaces
.replace(/^".*"$/, "$1")
.replace(/^'.*"$/, "$1")
.trim()
return fp
.replace(/\\ /g, " ") // unescape spaces
.replace(/^".*"$/, "$1")
.replace(/^'.*"$/, "$1")
.trim()
}
export function exitIfCancel(val) {
if (isCancel(val)) {
outro(chalk.red("Exiting"))
process.exit(0)
} else {
return val
}
if (isCancel(val)) {
outro(chalk.red("Exiting"))
process.exit(0)
} else {
return val
}
}
export async function stashContentFolder(contentFolder) {
await fs.promises.rm(contentCacheFolder, { force: true, recursive: true })
await fs.promises.cp(contentFolder, contentCacheFolder, {
force: true,
recursive: true,
verbatimSymlinks: true,
preserveTimestamps: true,
})
await fs.promises.rm(contentFolder, { force: true, recursive: true })
await fs.promises.rm(contentCacheFolder, { force: true, recursive: true })
await fs.promises.cp(contentFolder, contentCacheFolder, {
force: true,
recursive: true,
verbatimSymlinks: true,
preserveTimestamps: true,
})
await fs.promises.rm(contentFolder, { force: true, recursive: true })
}
export function gitPull(origin, branch) {
const flags = ["--no-rebase", "--autostash", "-s", "recursive", "-X", "ours", "--no-edit"]
const out = spawnSync("git", ["pull", ...flags, origin, branch], { stdio: "inherit" })
if (out.stderr) {
throw new Error(chalk.red(`Error while pulling updates: ${out.stderr}`))
} else if (out.status !== 0) {
throw new Error(chalk.red("Error while pulling updates"))
}
const flags = [
"--no-rebase",
"--autostash",
"-s",
"recursive",
"-X",
"ours",
"--no-edit",
]
const out = spawnSync("git", ["pull", ...flags, origin, branch], {
stdio: "inherit",
})
if (out.stderr) {
throw new Error(chalk.red(`Error while pulling updates: ${out.stderr}`))
} else if (out.status !== 0) {
throw new Error(chalk.red("Error while pulling updates"))
}
}
export async function popContentFolder(contentFolder) {
await fs.promises.rm(contentFolder, { force: true, recursive: true })
await fs.promises.cp(contentCacheFolder, contentFolder, {
force: true,
recursive: true,
verbatimSymlinks: true,
preserveTimestamps: true,
})
await fs.promises.rm(contentCacheFolder, { force: true, recursive: true })
await fs.promises.rm(contentFolder, { force: true, recursive: true })
await fs.promises.cp(contentCacheFolder, contentFolder, {
force: true,
recursive: true,
verbatimSymlinks: true,
preserveTimestamps: true,
})
await fs.promises.rm(contentCacheFolder, { force: true, recursive: true })
}

25
quartz/components/ArticleTitle.tsx
View File

@ -1,13 +1,22 @@
import { QuartzComponent, QuartzComponentConstructor, QuartzComponentProps } from "./types"
import {
QuartzComponent,
QuartzComponentConstructor,
QuartzComponentProps,
} from "./types"
import { classNames } from "../util/lang"
const ArticleTitle: QuartzComponent = ({ fileData, displayClass }: QuartzComponentProps) => {
const title = fileData.frontmatter?.title
if (title) {
return <h1 class={classNames(displayClass, "article-title")}>{title}</h1>
} else {
return null
}
const ArticleTitle: QuartzComponent = ({
fileData,
displayClass,
}: QuartzComponentProps) => {
const title = fileData.frontmatter?.title
if (title) {
return (
<h1 class={classNames(displayClass, "article-title")}>{title}</h1>
)
} else {
return null
}
}
ArticleTitle.css = `

Some files were not shown because too many files have changed in this diff Show More