diff --git a/docs/hosting.md b/docs/hosting.md index 9761e5b..a4ca1ea 100644 --- a/docs/hosting.md +++ b/docs/hosting.md @@ -4,10 +4,7 @@ title: Hosting Quartz effectively turns your Markdown files and other resources into a bundle of HTML, JS, and CSS files (a website!). -However, if you'd like to publish your site to the world, you need a way to host it online. This guide will detail how to deploy with common hosting providers but any service that allows you to deploy static HTML should work as well. - -> [!warning] -> The rest of this guide assumes that you've already created your own GitHub repository for Quartz. If you haven't already, [[setting up your GitHub repository|make sure you do so]]. +However, if you'd like to publish your site to the world, you need a way to host it online. This guide will detail how to deploy with either GitHub Pages or Cloudflare pages but any service that allows you to deploy static HTML should work as well (e.g. Netlify, Replit, etc.) > [!hint] > Some Quartz features (like [[RSS Feed]] and sitemap generation) require `baseUrl` to be configured properly in your [[configuration]] to work properly. Make sure you set this before deploying! @@ -29,11 +26,13 @@ Press "Save and deploy" and Cloudflare should have a deployed version of your si To add a custom domain, check out [Cloudflare's documentation](https://developers.cloudflare.com/pages/platform/custom-domains/). -> [!warning] -> Cloudflare Pages only allows shallow `git` clones so if you rely on `git` for timestamps, it is recommended you either add dates to your frontmatter (see [[authoring content#Syntax]]) or use another hosting provider. - ## GitHub Pages +Like Quartz 3, you can deploy the site generated by Quartz 4 via GitHub Pages. + +> [!warning] +> Quartz generates files in the format of `file.html` instead of `file/index.html` which means the trailing slashes for _non-folder paths_ are dropped. As GitHub pages does not do this redirect, this may cause existing links to your site that use trailing slashes to break. If not breaking existing links is important to you, consider using [[#Cloudflare Pages]]. + In your local Quartz, create a new file `quartz/.github/workflows/deploy.yml`. ```yaml title="quartz/.github/workflows/deploy.yml" @@ -94,9 +93,6 @@ Then: > > You can do this by going to your Settings page on your GitHub fork and going to the Environments tab and pressing the trash icon. The GitHub action will recreate the environment for you correctly the next time you sync your Quartz. -> [!info] -> Quartz generates files in the format of `file.html` instead of `file/index.html` which means the trailing slashes for _non-folder paths_ are dropped. As GitHub pages does not do this redirect, this may cause existing links to your site that use trailing slashes to break. If not breaking existing links is important to you (e.g. you are migrating from Quartz 3), consider using [[#Cloudflare Pages]]. - ### Custom Domain Here's how to add a custom domain to your GitHub pages deployment. @@ -171,17 +167,10 @@ Using `docs.example.com` is an example of a subdomain. They're a simple way of c 4. Go to the Settings tab and then click Domains in the sidebar 5. Enter your subdomain into the field and press Add -## Netlify - -1. Log in to the [Netlify dashboard](https://app.netlify.com/) and click "Add new site". -2. Select your Git provider and repository containing your Quartz project. -3. Under "Build command", enter `npx quartz build`. -4. Under "Publish directory", enter `public`. -5. Press Deploy. Once it's live, you'll have a `*.netlify.app` URL to view the page. -6. To add a custom domain, check "Domain management" in the left sidebar, just like with Vercel. - ## GitLab Pages +You can configure GitLab CI to build and deploy a Quartz 4 project. + In your local Quartz, create a new file `.gitlab-ci.yaml`. ```yaml title=".gitlab-ci.yaml" @@ -203,6 +192,8 @@ build: - hash -r - npm ci script: + - npx prettier --write . + - npm run check - npx quartz build artifacts: paths: @@ -225,6 +216,6 @@ pages: - public ``` -When `.gitlab-ci.yaml` is commited, GitLab will build and deploy the website as a GitLab Page. You can find the url under `Deploy > Pages` in the sidebar. +When `.gitlab-ci.yaml` is commited, GitLab will build and deploy the website as a GitLab Page. You can find the url under `Deploy` -> `Pages` in the sidebar. By default, the page is private and only visible when logged in to a GitLab account with access to the repository but can be opened in the settings under `Deploy` -> `Pages`. diff --git a/docs/images/github-init-repo-options.png b/docs/images/github-init-repo-options.png deleted file mode 100644 index dd88931..0000000 Binary files a/docs/images/github-init-repo-options.png and /dev/null differ diff --git a/docs/images/github-quick-setup.png b/docs/images/github-quick-setup.png deleted file mode 100644 index 5be333f..0000000 Binary files a/docs/images/github-quick-setup.png and /dev/null differ diff --git a/docs/index.md b/docs/index.md index 655f5c3..85afee1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,7 +2,7 @@ title: Welcome to Quartz 4 --- -Quartz is a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites. Thousands of students, developers, and teachers are [[showcase|already using Quartz]] to publish personal notes, websites, and [digital gardens](https://jzhao.xyz/posts/networked-thought) to the web. +Quartz is a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites. Thousands of students, developers, and teachers are [[showcase|already using Quartz]] to publish personal notes, wikis, and [digital gardens](https://jzhao.xyz/posts/networked-thought) to the web. ## 🪴 Get Started @@ -19,7 +19,7 @@ npx quartz create This will guide you through initializing your Quartz with content. Once you've done so, see how to: -1. [[authoring content|Writing content]] in Quartz +1. [[authoring content|Author content]] in Quartz 2. [[configuration|Configure]] Quartz's behaviour 3. Change Quartz's [[layout]] 4. [[build|Build and preview]] Quartz diff --git a/docs/setting up your GitHub repository.md b/docs/setting up your GitHub repository.md deleted file mode 100644 index 4165517..0000000 --- a/docs/setting up your GitHub repository.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Setting up your GitHub repository ---- - -First, make sure you have Quartz [[index#🪴 Get Started|cloned and setup locally]]. - -Then, create a new repository on GitHub.com. Do **not** initialize the new repository with `README`, license, or `gitignore` files. - -![[github-init-repo-options.png]] - -At the top of your repository on GitHub.com's Quick Setup page, click the clipboard to copy the remote repository URL. - -![[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. - -```bash -git remote add origin REMOTE-URL -``` - -To verify that you set the remote URL correctly, run the following command. - -```bash -git remote -v -``` - -Then, you can sync the content to upload it to your repository. - -```bash -npx quartz sync -``` diff --git a/package-lock.json b/package-lock.json index 7c12e71..a879078 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@jackyzha0/quartz", - "version": "4.1.2", + "version": "4.0.11", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@jackyzha0/quartz", - "version": "4.1.2", + "version": "4.0.11", "license": "MIT", "dependencies": { "@clack/prompts": "^0.6.3", @@ -85,8 +85,7 @@ "typescript": "^5.0.4" }, "engines": { - "node": ">=18.14", - "npm": ">=9.3.1" + "node": ">=18.14" } }, "node_modules/@clack/core": { diff --git a/package.json b/package.json index 0a746dc..aa63243 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "@jackyzha0/quartz", "description": "🌱 publish your digital garden and notes as a website", "private": true, - "version": "4.1.2", + "version": "4.1.1", "type": "module", "author": "jackyzha0 ", "license": "MIT", diff --git a/quartz/cli/handlers.js b/quartz/cli/handlers.js index 7a83c5d..96ee9bc 100644 --- a/quartz/cli/handlers.js +++ b/quartz/cli/handlers.js @@ -196,11 +196,6 @@ See the [documentation](https://quartz.jzhao.xyz) for how to get started. ) await fs.promises.writeFile(configFilePath, configContent) - // setup remote - execSync( - `git remote show upstream || git remote add upstream https://github.com/jackyzha0/quartz.git`, - ) - outro(`You're all set! Not sure what to do next? Try: • Customizing Quartz a bit more by editing \`quartz.config.ts\` • Running \`npx quartz build --serve\` to preview your Quartz locally diff --git a/quartz/components/pages/TagContent.tsx b/quartz/components/pages/TagContent.tsx index a495af5..4a068c6 100644 --- a/quartz/components/pages/TagContent.tsx +++ b/quartz/components/pages/TagContent.tsx @@ -27,7 +27,7 @@ function TagContent(props: QuartzComponentProps) { ? fileData.description : htmlToJsx(fileData.filePath!, tree) - if (tag === "/") { + if (tag === "") { const tags = [...new Set(allFiles.flatMap((data) => data.frontmatter?.tags ?? []))] const tagItemMap: Map = new Map() for (const tag of tags) { diff --git a/quartz/components/renderPage.tsx b/quartz/components/renderPage.tsx index 305f511..5cb39d9 100644 --- a/quartz/components/renderPage.tsx +++ b/quartz/components/renderPage.tsx @@ -3,10 +3,9 @@ import { QuartzComponent, QuartzComponentProps } from "./types" import HeaderConstructor from "./Header" import BodyConstructor from "./Body" import { JSResourceToScriptElement, StaticResources } from "../util/resources" -import { FullSlug, RelativeURL, joinSegments, normalizeHastElement } from "../util/path" +import { FullSlug, RelativeURL, joinSegments } from "../util/path" import { visit } from "unist-util-visit" import { Root, Element, ElementContent } from "hast" -import { QuartzPluginData } from "../plugins/vfile" interface RenderComponents { head: QuartzComponent @@ -50,18 +49,6 @@ export function pageResources( } } -let pageIndex: Map | undefined = undefined -function getOrComputeFileIndex(allFiles: QuartzPluginData[]): Map { - if (!pageIndex) { - pageIndex = new Map() - for (const file of allFiles) { - pageIndex.set(file.slug!, file) - } - } - - return pageIndex -} - export function renderPage( slug: FullSlug, componentData: QuartzComponentProps, @@ -75,15 +62,17 @@ export function renderPage( if (classNames.includes("transclude")) { const inner = node.children[0] as Element const transcludeTarget = inner.properties?.["data-slug"] as FullSlug - const page = getOrComputeFileIndex(componentData.allFiles).get(transcludeTarget) + + // TODO: avoid this expensive find operation and construct an index ahead of time + const page = componentData.allFiles.find((f) => f.slug === transcludeTarget) if (!page) { return } let blockRef = node.properties?.dataBlock as string | undefined - if (blockRef?.startsWith("#^")) { + if (blockRef?.startsWith("^")) { // block transclude - blockRef = blockRef.slice("#^".length) + blockRef = blockRef.slice(1) let blockNode = page.blocks?.[blockRef] if (blockNode) { if (blockNode.tagName === "li") { @@ -95,7 +84,7 @@ export function renderPage( } node.children = [ - normalizeHastElement(blockNode, slug, transcludeTarget), + blockNode, { type: "element", tagName: "a", @@ -128,9 +117,7 @@ export function renderPage( } node.children = [ - ...(page.htmlAst.children.slice(startIdx, endIdx) as ElementContent[]).map((child) => - normalizeHastElement(child as Element, slug, transcludeTarget), - ), + ...(page.htmlAst.children.slice(startIdx, endIdx) as ElementContent[]), { type: "element", tagName: "a", @@ -148,9 +135,7 @@ export function renderPage( { type: "text", value: page.frontmatter?.title ?? `Transclude of ${page.slug}` }, ], }, - ...(page.htmlAst.children as ElementContent[]).map((child) => - normalizeHastElement(child as Element, slug, transcludeTarget), - ), + ...(page.htmlAst.children as ElementContent[]), { type: "element", tagName: "a", diff --git a/quartz/components/scripts/graph.inline.ts b/quartz/components/scripts/graph.inline.ts index bddcfa4..1aff138 100644 --- a/quartz/components/scripts/graph.inline.ts +++ b/quartz/components/scripts/graph.inline.ts @@ -1,4 +1,4 @@ -import type { ContentDetails, ContentIndex } from "../../plugins/emitters/contentIndex" +import type { ContentDetails } from "../../plugins/emitters/contentIndex" import * as d3 from "d3" import { registerEscapeHandler, removeAllChildren } from "./util" import { FullSlug, SimpleSlug, getFullSlug, resolveRelative, simplifySlug } from "../../util/path" @@ -46,22 +46,20 @@ async function renderGraph(container: string, fullSlug: FullSlug) { showTags, } = JSON.parse(graph.dataset["cfg"]!) - const data: Map = new Map( - Object.entries(await fetchData).map(([k, v]) => [ - simplifySlug(k as FullSlug), - v, - ]), - ) + const data = await fetchData + const links: LinkData[] = [] const tags: SimpleSlug[] = [] - const validLinks = new Set(data.keys()) - for (const [source, details] of data.entries()) { + const validLinks = new Set(Object.keys(data).map((slug) => simplifySlug(slug as FullSlug))) + + for (const [src, details] of Object.entries(data)) { + const source = simplifySlug(src as FullSlug) const outgoing = details.links ?? [] for (const dest of outgoing) { if (validLinks.has(dest)) { - links.push({ source: source, target: dest }) + links.push({ source, target: dest }) } } @@ -73,7 +71,7 @@ async function renderGraph(container: string, fullSlug: FullSlug) { tags.push(...localTags.filter((tag) => !tags.includes(tag))) for (const tag of localTags) { - links.push({ source: source, target: tag }) + links.push({ source, target: tag }) } } } @@ -95,17 +93,17 @@ async function renderGraph(container: string, fullSlug: FullSlug) { } } } else { - validLinks.forEach((id) => neighbourhood.add(id)) + Object.keys(data).forEach((id) => neighbourhood.add(simplifySlug(id as FullSlug))) if (showTags) tags.forEach((tag) => neighbourhood.add(tag)) } const graphData: { nodes: NodeData[]; links: LinkData[] } = { nodes: [...neighbourhood].map((url) => { - const text = url.startsWith("tags/") ? "#" + url.substring(5) : data.get(url)?.title ?? url + const text = url.startsWith("tags/") ? "#" + url.substring(5) : data[url]?.title ?? url return { id: url, text: text, - tags: data.get(url)?.tags ?? [], + tags: data[url]?.tags ?? [], } }), links: links.filter((l) => neighbourhood.has(l.source) && neighbourhood.has(l.target)), @@ -202,7 +200,7 @@ async function renderGraph(container: string, fullSlug: FullSlug) { window.spaNavigate(new URL(targ, window.location.toString())) }) .on("mouseover", function (_, d) { - const neighbours: SimpleSlug[] = data.get(slug)?.links ?? [] + const neighbours: SimpleSlug[] = data[fullSlug].links ?? [] const neighbourNodes = d3 .selectAll(".node") .filter((d) => neighbours.includes(d.id)) diff --git a/quartz/components/scripts/popover.inline.ts b/quartz/components/scripts/popover.inline.ts index 4d51e2a..371563b 100644 --- a/quartz/components/scripts/popover.inline.ts +++ b/quartz/components/scripts/popover.inline.ts @@ -7,10 +7,6 @@ async function mouseEnterHandler( { clientX, clientY }: { clientX: number; clientY: number }, ) { const link = this - if (link.dataset.noPopover === "true") { - return - } - async function setPosition(popoverElement: HTMLElement) { const { x, y } = await computePosition(link, popoverElement, { middleware: [inline({ x: clientX, y: clientY }), shift(), flip()], @@ -36,6 +32,8 @@ async function mouseEnterHandler( const hash = targetUrl.hash targetUrl.hash = "" targetUrl.search = "" + // prevent hover of the same page + if (thisUrl.toString() === targetUrl.toString()) return const contents = await fetch(`${targetUrl}`) .then((res) => res.text()) diff --git a/quartz/plugins/emitters/tagPage.tsx b/quartz/plugins/emitters/tagPage.tsx index ad5e1d6..6afde2f 100644 --- a/quartz/plugins/emitters/tagPage.tsx +++ b/quartz/plugins/emitters/tagPage.tsx @@ -45,7 +45,7 @@ export const TagPage: QuartzEmitterPlugin = (userOpts) => { const tagDescriptions: Record = Object.fromEntries( [...tags].map((tag) => { - const title = tag === "index" ? "Tag Index" : `Tag: #${tag}` + const title = tag === "" ? "Tag Index" : `Tag: #${tag}` return [ tag, defaultProcessedContent({ diff --git a/quartz/plugins/transformers/frontmatter.ts b/quartz/plugins/transformers/frontmatter.ts index 017d3d1..04b1105 100644 --- a/quartz/plugins/transformers/frontmatter.ts +++ b/quartz/plugins/transformers/frontmatter.ts @@ -8,13 +8,11 @@ import { slugTag } from "../../util/path" export interface Options { delims: string | string[] language: "yaml" | "toml" - oneLineTagDelim: string } const defaultOptions: Options = { delims: "---", language: "yaml", - oneLineTagDelim: ",", } export const FrontMatter: QuartzTransformerPlugin | undefined> = (userOpts) => { @@ -22,8 +20,6 @@ export const FrontMatter: QuartzTransformerPlugin | undefined> return { name: "FrontMatter", markdownPlugins() { - const { oneLineTagDelim } = opts - return [ [remarkFrontmatter, ["yaml", "toml"]], () => { @@ -49,7 +45,7 @@ export const FrontMatter: QuartzTransformerPlugin | undefined> if (data.tags && !Array.isArray(data.tags)) { data.tags = data.tags .toString() - .split(oneLineTagDelim) + .split(",") .map((tag: string) => tag.trim()) } diff --git a/quartz/plugins/transformers/gfm.ts b/quartz/plugins/transformers/gfm.ts index 40c2205..62624aa 100644 --- a/quartz/plugins/transformers/gfm.ts +++ b/quartz/plugins/transformers/gfm.ts @@ -31,11 +31,6 @@ export const GitHubFlavoredMarkdown: QuartzTransformerPlugin | rehypeAutolinkHeadings, { behavior: "append", - properties: { - ariaHidden: true, - tabIndex: -1, - "data-no-popover": true, - }, content: { type: "text", value: " §", diff --git a/quartz/plugins/transformers/links.ts b/quartz/plugins/transformers/links.ts index 3072959..eec473c 100644 --- a/quartz/plugins/transformers/links.ts +++ b/quartz/plugins/transformers/links.ts @@ -81,16 +81,14 @@ export const CrawlLinks: QuartzTransformerPlugin | undefined> = // WHATWG equivalent https://nodejs.dev/en/api/v18/url/#urlresolvefrom-to const url = new URL(dest, `https://base.com/${curSlug}`) const canonicalDest = url.pathname - let [destCanonical, _destAnchor] = splitAnchor(canonicalDest) - if (destCanonical.endsWith("/")) { - destCanonical += "index" - } + const [destCanonical, _destAnchor] = splitAnchor(canonicalDest) // need to decodeURIComponent here as WHATWG URL percent-encodes everything - const full = decodeURIComponent(_stripSlashes(destCanonical, true)) as FullSlug - const simple = simplifySlug(full) + const simple = decodeURIComponent( + simplifySlug(destCanonical as FullSlug), + ) as SimpleSlug outgoing.add(simple) - node.properties["data-slug"] = full + node.properties["data-slug"] = simple } // rewrite link internals if prettylinks is on diff --git a/quartz/plugins/transformers/ofm.ts b/quartz/plugins/transformers/ofm.ts index 4c6a6db..2e47ced 100644 --- a/quartz/plugins/transformers/ofm.ts +++ b/quartz/plugins/transformers/ofm.ts @@ -182,8 +182,7 @@ export const ObsidianFlavoredMarkdown: QuartzTransformerPlugin const [rawFp, rawHeader, rawAlias] = capture const fp = rawFp ?? "" const anchor = rawHeader?.trim().replace(/^#+/, "") - const blockRef = Boolean(anchor?.startsWith("^")) ? "^" : "" - const displayAnchor = anchor ? `#${blockRef}${slugAnchor(anchor)}` : "" + const displayAnchor = anchor ? `#${slugAnchor(anchor)}` : "" const displayAlias = rawAlias ?? rawHeader?.replace("#", "|") ?? "" const embedDisplay = value.startsWith("!") ? "!" : "" return `${embedDisplay}[[${fp}${displayAnchor}${displayAlias}]]` diff --git a/quartz/util/path.test.ts b/quartz/util/path.test.ts index 18edc94..8bbb58d 100644 --- a/quartz/util/path.test.ts +++ b/quartz/util/path.test.ts @@ -83,7 +83,7 @@ describe("transforms", () => { test("simplifySlug", () => { asserts( [ - ["index", "/"], + ["index", ""], ["abc", "abc"], ["abc/index", "abc/"], ["abc/def", "abc/def"], diff --git a/quartz/util/path.ts b/quartz/util/path.ts index 5cf54b8..e450339 100644 --- a/quartz/util/path.ts +++ b/quartz/util/path.ts @@ -1,5 +1,4 @@ import { slug } 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) export const QUARTZ = "quartz" @@ -25,7 +24,7 @@ export function isFullSlug(s: string): s is FullSlug { /** Shouldn't be a relative path and shouldn't have `/index` as an ending or a file extension. It _can_ however have a trailing slash to indicate a folder path. */ export type SimpleSlug = SlugLike<"simple"> export function isSimpleSlug(s: string): s is SimpleSlug { - const validStart = !(s.startsWith(".") || (s.length > 1 && s.startsWith("/"))) + const validStart = !(s.startsWith(".") || s.startsWith("/")) const validEnding = !(s.endsWith("/index") || s === "index") return validStart && !_containsForbiddenCharacters(s) && validEnding && !_hasFileExtension(s) } @@ -66,8 +65,7 @@ export function slugifyFilePath(fp: FilePath, excludeExt?: boolean): FullSlug { } export function simplifySlug(fp: FullSlug): SimpleSlug { - const res = _stripSlashes(_trimSuffix(fp, "index"), true) - return (res.length === 0 ? "/" : res) as SimpleSlug + return _stripSlashes(_trimSuffix(fp, "index"), true) as SimpleSlug } export function transformInternalLink(link: string): RelativeURL { @@ -88,47 +86,20 @@ export function transformInternalLink(link: string): RelativeURL { // from micromorph/src/utils.ts // https://github.com/natemoo-re/micromorph/blob/main/src/utils.ts#L5 -const _rebaseHtmlElement = (el: Element, attr: string, newBase: string | URL) => { - const rebased = new URL(el.getAttribute(attr)!, newBase) - el.setAttribute(attr, rebased.pathname + rebased.hash) -} export function normalizeRelativeURLs(el: Element | Document, destination: string | URL) { + const rebase = (el: Element, attr: string, newBase: string | URL) => { + const rebased = new URL(el.getAttribute(attr)!, newBase) + el.setAttribute(attr, rebased.pathname + rebased.hash) + } + el.querySelectorAll('[href^="./"], [href^="../"]').forEach((item) => - _rebaseHtmlElement(item, "href", destination), + rebase(item, "href", destination), ) el.querySelectorAll('[src^="./"], [src^="../"]').forEach((item) => - _rebaseHtmlElement(item, "src", destination), + rebase(item, "src", destination), ) } -const _rebaseHastElement = ( - el: HastElement, - attr: string, - curBase: FullSlug, - newBase: FullSlug, -) => { - if (el.properties?.[attr]) { - if (!isRelativeURL(String(el.properties[attr]))) { - return - } - - const rel = joinSegments(resolveRelative(curBase, newBase), "..", el.properties[attr] as string) - el.properties[attr] = rel - } -} - -export function normalizeHastElement(el: HastElement, curBase: FullSlug, newBase: FullSlug) { - _rebaseHastElement(el, "src", curBase, newBase) - _rebaseHastElement(el, "href", curBase, newBase) - if (el.children) { - el.children = el.children.map((child) => - normalizeHastElement(child as HastElement, curBase, newBase), - ) - } - - return el -} - // resolve /a/b/c to ../.. export function pathToRoot(slug: FullSlug): RelativeURL { let rootPath = slug