diff --git a/docs/features/graph view.md b/docs/features/graph view.md index c7ddb03e0..4f905c78d 100644 --- a/docs/features/graph view.md +++ b/docs/features/graph view.md @@ -34,6 +34,8 @@ Component.Graph({ 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, @@ -45,6 +47,8 @@ Component.Graph({ linkDistance: 30, fontSize: 0.6, opacityScale: 1, + removeTags: [], // what tags to remove from the graph + showTags: true, // whether to show tags in the graph }, }) ``` diff --git a/docs/features/wikilinks.md b/docs/features/wikilinks.md index 50bbb1bb6..1b005327c 100644 --- a/docs/features/wikilinks.md +++ b/docs/features/wikilinks.md @@ -14,3 +14,11 @@ This is enabled as a part of [[Obsidian compatibility]] and can be configured an - `[[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` diff --git a/docs/philosophy.md b/docs/philosophy.md index b8af845fb..af5510aac 100644 --- a/docs/philosophy.md +++ b/docs/philosophy.md @@ -8,7 +8,9 @@ title: Philosophy of Quartz > > _(The Garden and the Stream)_ -The problem with the file cabinet is that it focuses on efficiency of access and interoperability rather than generativity and creativity. Thinking is not linear, nor is it hierarchical. In fact, not many things are linear or hierarchical at all. Then why is it that most tools and thinking strategies assume a nice chronological or hierarchical order for my thought processes? The ideal tool for thought for me would embrace the messiness of my mind, and organically help insights emerge from chaos instead of forcing an artificial order. A rhizomatic, not arboresecent, form of note taking. +The problem with the file cabinet is that it focuses on efficiency of access and interoperability rather than generativity and creativity. Thinking is not linear, nor is it hierarchical. In fact, not many things are linear or hierarchical at all. Then why is it that most tools and thinking strategies assume a nice chronological or hierarchical order for my thought processes? + +The ideal tool for thought for me would embrace the messiness of my mind, and organically help insights emerge from chaos instead of forcing an artificial order. A rhizomatic, not arboresecent, form of note taking. My goal with a digital garden is not purely as an organizing system and information store (though it works nicely for that). I want my digital garden to be a playground for new ways ideas can connect together. As a result, existing formal organizing systems like Zettelkasten or the hierarchical folder structures of Notion don’t work well for me. There is way too much upfront friction that by the time I’ve thought about how to organize my thought into folders categories, I’ve lost it. @@ -25,4 +27,21 @@ Quartz is designed first and foremost as a tool for publishing [digital gardens] > “[One] who works with the door open gets all kinds of interruptions, but [they] also occasionally gets clues as to what the world is and what might be important.” > — Richard Hamming -**The goal of Quartz is to make sharing your digital garden free and simple.** At its core, Quartz is designed to be easy to use enough for non-technical people to get going but also powerful enough that senior developers can tweak it to work how they'd like it to work. +**The goal of Quartz is to make sharing your digital garden free and simple.** + +--- + +## A garden should be your own + +At its core, Quartz is designed to be easy to use enough for non-technical people to get going but also powerful enough that senior developers can tweak it to work how they'd like it to work. + +1. If you like the default configuration of Quartz and just want to change the content, the only thing that you need to change is the contents of the `content` folder. +2. If you'd like to make basic configuration tweaks but don't want to edit source code, one can tweak the plugins and components in `quartz.config.ts` and `quartz.layout.ts` in a guided manner to their liking. +3. If you'd like to tweak the actual source code of the underlying plugins, components, or even build process, Quartz purposefully ships its full source code to the end user to allow customization at this level too. + +Most software either confines you to either + +1. Makes it easy to tweak content but not the presentation +2. Gives you too many knobs to tune the presentation without good opinionated defaults + +**Quartz should feel powerful but ultimately be an intuitive tool fully within your control.** It should be a piece of [agentic software](https://jzhao.xyz/posts/agentic-computing). Ultimately, it should have the right affordances to nudge users towards good defaults but never dictate what the 'correct' way of using it is. diff --git a/docs/setting up your GitHub repository.md b/docs/setting up your GitHub repository.md index 41655179d..1b5461b51 100644 --- a/docs/setting up your GitHub repository.md +++ b/docs/setting up your GitHub repository.md @@ -12,10 +12,14 @@ At the top of your repository on GitHub.com's Quick Setup page, click the clipb ![[github-quick-setup.png]] -In your terminal of choice, navigate to the root of your Quartz folder. Then, run the following command, replacing `REMOTE-URL` with the URL you just copied from the previous step. +In your terminal of choice, navigate to the root of your Quartz folder. Then, run the following commands, replacing `REMOTE-URL` with the URL you just copied from the previous step. ```bash +# add your repository git remote add origin REMOTE-URL + +# track the main quartz repository for updates +git remote add upstream https://github.com/jackyzha0/quartz.git ``` To verify that you set the remote URL correctly, run the following command. @@ -27,5 +31,9 @@ git remote -v Then, you can sync the content to upload it to your repository. ```bash -npx quartz sync +npx quartz sync --no-pull ``` + +> [!hint] +> If `npx quartz sync` fails with `fatal: --[no-]autostash option is only valid with --rebase`, you +> may have an outdated version of `git`. Updating `git` should fix this issue. diff --git a/docs/showcase.md b/docs/showcase.md index a5ed89bc9..1e2ef56ae 100644 --- a/docs/showcase.md +++ b/docs/showcase.md @@ -6,9 +6,9 @@ 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/) - [Brandon Boswell's Garden](https://brandonkboswell.com) - [Scaling Synthesis - A hypertext research notebook](https://scalingsynthesis.com/) -- [AWAGMI Intern Notes](https://notes.awagmi.xyz/) - [Data Dictionary 🧠](https://glossary.airbyte.com/) - [sspaeti.com's Second Brain](https://brain.sspaeti.com/) - [oldwinter の数字花园](https://garden.oldwinter.top/) diff --git a/quartz/build.ts b/quartz/build.ts index 5752caa46..0ebc52928 100644 --- a/quartz/build.ts +++ b/quartz/build.ts @@ -152,10 +152,10 @@ async function startServing( console.log(chalk.yellow(`Rebuild failed. Waiting on a change to fix the error...`)) } + release() clientRefresh() toRebuild.clear() toRemove.clear() - release() } const watcher = chokidar.watch(".", { diff --git a/quartz/cli/handlers.js b/quartz/cli/handlers.js index 7a83c5d8f..586881af9 100644 --- a/quartz/cli/handlers.js +++ b/quartz/cli/handlers.js @@ -443,11 +443,23 @@ export async function handleUpdate(argv) { console.log( "Pulling updates... you may need to resolve some `git` conflicts if you've made changes to components or plugins.", ) - gitPull(UPSTREAM_NAME, QUARTZ_SOURCE_BRANCH) + + try { + gitPull(UPSTREAM_NAME, QUARTZ_SOURCE_BRANCH) + } catch { + console.log(chalk.red("An error occured above while pulling updates.")) + await popContentFolder(contentFolder) + return + } + await popContentFolder(contentFolder) console.log("Ensuring dependencies are up to date") - spawnSync("npm", ["i"], { stdio: "inherit" }) - console.log(chalk.green("Done!")) + const res = spawnSync("npm", ["i"], { stdio: "inherit" }) + if (res.status === 0) { + console.log(chalk.green("Done!")) + } else { + console.log(chalk.red("An error occurred above while installing dependencies.")) + } } /** @@ -504,13 +516,25 @@ export async function handleSync(argv) { console.log( "Pulling updates from your repository. You may need to resolve some `git` conflicts if you've made changes to components or plugins.", ) - gitPull(ORIGIN_NAME, QUARTZ_SOURCE_BRANCH) + try { + gitPull(ORIGIN_NAME, QUARTZ_SOURCE_BRANCH) + } catch { + console.log(chalk.red("An error occured above while pulling updates.")) + await popContentFolder(contentFolder) + return + } } await popContentFolder(contentFolder) if (argv.push) { console.log("Pushing your changes") - spawnSync("git", ["push", "-f", ORIGIN_NAME, QUARTZ_SOURCE_BRANCH], { stdio: "inherit" }) + const res = spawnSync("git", ["push", "-uf", ORIGIN_NAME, QUARTZ_SOURCE_BRANCH], { + stdio: "inherit", + }) + if (res.status !== 0) { + console.log(chalk.red(`An error occurred above while pushing to remote ${ORIGIN_NAME}.`)) + return + } } console.log(chalk.green("Done!")) diff --git a/quartz/cli/helpers.js b/quartz/cli/helpers.js index b07d19e3c..702a1b71d 100644 --- a/quartz/cli/helpers.js +++ b/quartz/cli/helpers.js @@ -36,7 +36,9 @@ 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(`Error while pulling updates: ${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")) } } diff --git a/quartz/components/pages/TagContent.tsx b/quartz/components/pages/TagContent.tsx index a495af5c3..890755bbc 100644 --- a/quartz/components/pages/TagContent.tsx +++ b/quartz/components/pages/TagContent.tsx @@ -28,7 +28,11 @@ function TagContent(props: QuartzComponentProps) { : htmlToJsx(fileData.filePath!, tree) if (tag === "/") { - const tags = [...new Set(allFiles.flatMap((data) => data.frontmatter?.tags ?? []))] + const tags = [ + ...new Set( + allFiles.flatMap((data) => data.frontmatter?.tags ?? []).flatMap(getAllSegmentPrefixes), + ), + ].sort((a, b) => a.localeCompare(b)) const tagItemMap: Map = new Map() for (const tag of tags) { tagItemMap.set(tag, allPagesWithTag(tag)) diff --git a/quartz/plugins/emitters/tagPage.tsx b/quartz/plugins/emitters/tagPage.tsx index ad5e1d649..566911983 100644 --- a/quartz/plugins/emitters/tagPage.tsx +++ b/quartz/plugins/emitters/tagPage.tsx @@ -40,6 +40,7 @@ export const TagPage: QuartzEmitterPlugin = (userOpts) => { const tags: Set = new Set( allFiles.flatMap((data) => data.frontmatter?.tags ?? []).flatMap(getAllSegmentPrefixes), ) + // add base tag tags.add("index") diff --git a/quartz/plugins/transformers/frontmatter.ts b/quartz/plugins/transformers/frontmatter.ts index 04b1105c3..22b1cc6ec 100644 --- a/quartz/plugins/transformers/frontmatter.ts +++ b/quartz/plugins/transformers/frontmatter.ts @@ -4,15 +4,18 @@ import { QuartzTransformerPlugin } from "../types" import yaml from "js-yaml" import toml from "toml" import { slugTag } from "../../util/path" +import { QuartzPluginData } from "../vfile" export interface Options { delims: string | string[] language: "yaml" | "toml" + oneLineTagDelim: string } const defaultOptions: Options = { delims: "---", language: "yaml", + oneLineTagDelim: ",", } export const FrontMatter: QuartzTransformerPlugin | undefined> = (userOpts) => { @@ -20,6 +23,8 @@ export const FrontMatter: QuartzTransformerPlugin | undefined> return { name: "FrontMatter", markdownPlugins() { + const { oneLineTagDelim } = opts + return [ [remarkFrontmatter, ["yaml", "toml"]], () => { @@ -40,12 +45,14 @@ export const FrontMatter: QuartzTransformerPlugin | undefined> // coerce title to string if (data.title) { data.title = data.title.toString() + } else if (data.title === null || data.title === undefined) { + data.title = file.stem ?? "Untitled" } if (data.tags && !Array.isArray(data.tags)) { data.tags = data.tags .toString() - .split(",") + .split(oneLineTagDelim) .map((tag: string) => tag.trim()) } @@ -53,11 +60,7 @@ export const FrontMatter: QuartzTransformerPlugin | undefined> data.tags = [...new Set(data.tags?.map((tag: string) => slugTag(tag)))] ?? [] // fill in frontmatter - file.data.frontmatter = { - title: file.stem ?? "Untitled", - tags: [], - ...data, - } + file.data.frontmatter = data as QuartzPluginData["frontmatter"] } }, ] diff --git a/quartz/plugins/transformers/ofm.ts b/quartz/plugins/transformers/ofm.ts index 4c6a6dbed..c1bec16af 100644 --- a/quartz/plugins/transformers/ofm.ts +++ b/quartz/plugins/transformers/ofm.ts @@ -121,8 +121,8 @@ const calloutRegex = new RegExp(/^\[\!(\w+)\]([+-]?)/) const calloutLineRegex = new RegExp(/^> *\[\!\w+\][+-]?.*$/, "gm") // (?:^| ) -> non-capturing group, tag should start be separated by a space or be the start of the line // #(...) -> capturing group, tag itself must start with # -// (?:[-_\p{L}])+ -> non-capturing group, non-empty string of (Unicode-aware) alpha-numeric characters, hyphens and/or underscores -// (?:\/[-_\p{L}]+)*) -> non-capturing group, matches an arbitrary number of tag strings separated by "/" +// (?:[-_\p{L}\d\p{Z}])+ -> non-capturing group, non-empty string of (Unicode-aware) alpha-numeric characters and symbols, hyphens and/or underscores +// (?:\/[-_\p{L}\d\p{Z}]+)*) -> non-capturing group, matches an arbitrary number of tag strings separated by "/" const tagRegex = new RegExp(/(?:^| )#((?:[-_\p{L}\d])+(?:\/[-_\p{L}\d]+)*)/, "gu") const blockReferenceRegex = new RegExp(/\^([A-Za-z0-9]+)$/, "g") @@ -405,6 +405,7 @@ export const ObsidianFlavoredMarkdown: QuartzTransformerPlugin if (/^\d+$/.test(tag)) { return false } + tag = slugTag(tag) if (file.data.frontmatter && !file.data.frontmatter.tags.includes(tag)) { file.data.frontmatter.tags.push(tag) diff --git a/quartz/styles/base.scss b/quartz/styles/base.scss index 2e5edec15..f65ab4511 100644 --- a/quartz/styles/base.scss +++ b/quartz/styles/base.scss @@ -64,11 +64,17 @@ a { color: var(--tertiary) !important; } - &.internal:not(:has(> img)) { + &.internal { text-decoration: none; background-color: var(--highlight); padding: 0 0.1rem; border-radius: 5px; + + &:has(> img) { + background-color: none; + border-radius: 0; + padding: 0; + } } } @@ -94,8 +100,6 @@ a { } & article { - position: relative; - & > h1 { font-size: 2rem; } diff --git a/quartz/util/path.ts b/quartz/util/path.ts index 5cf54b803..92cfabe49 100644 --- a/quartz/util/path.ts +++ b/quartz/util/path.ts @@ -1,4 +1,4 @@ -import { slug } from "github-slugger" +import { slug as slugAnchor } from "github-slugger" import type { Element as HastElement } from "hast" // this file must be isomorphic so it can't use node libs (e.g. path) @@ -43,6 +43,14 @@ export function getFullSlug(window: Window): FullSlug { return res } +function sluggify(s: string): string { + return s + .split("/") + .map((segment) => segment.replace(/\s/g, "-").replace(/%/g, "-percent").replace(/\?/g, "-q")) // slugify all segments + .join("/") // always use / as sep + .replace(/\/$/, "") +} + export function slugifyFilePath(fp: FilePath, excludeExt?: boolean): FullSlug { fp = _stripSlashes(fp) as FilePath let ext = _getFileExtension(fp) @@ -51,11 +59,7 @@ export function slugifyFilePath(fp: FilePath, excludeExt?: boolean): FullSlug { ext = "" } - let slug = withoutFileExt - .split("/") - .map((segment) => segment.replace(/\s/g, "-").replace(/%/g, "-percent").replace(/\?/g, "-q")) // slugify all segments - .join("/") // always use / as sep - .replace(/\/$/, "") // remove trailing slash + let slug = sluggify(withoutFileExt) // treat _index as index if (_endsWith(slug, "_index")) { @@ -156,14 +160,10 @@ export function splitAnchor(link: string): [string, string] { return [fp, anchor] } -export function slugAnchor(anchor: string) { - return slug(anchor) -} - export function slugTag(tag: string) { return tag .split("/") - .map((tagSegment) => slug(tagSegment)) + .map((tagSegment) => sluggify(tagSegment)) .join("/") }