diff --git a/content/build.md b/content/build.md index 28570571..ac6a410e 100644 --- a/content/build.md +++ b/content/build.md @@ -1,3 +1,25 @@ --- title: "Building your Quartz" --- + +Once you've [[index#🪴 Get Started|initialized]] Quartz, let's see what it looks like locally. + +```bash +npx quartz build --serve +``` + +Then, open a web browser and visit `http://localhost:8080/` to view it! + +Want to change how Quartz looks? You can edit `quartz.config.ts` to customize and configure your Quartz, including styles, layout, and more. Read the [[configuration]] page for more information on what each field in the configuration does. + +Once you're happy with it, let's see how to [[hosting|deploy Quartz to the web]]. + +> [!hint] Flags and options +> For full help options, you can run `npx quartz build --help`. +> +> 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 \ No newline at end of file diff --git a/content/configuration.md b/content/configuration.md index e31dbc2d..ef0bf9b2 100644 --- a/content/configuration.md +++ b/content/configuration.md @@ -4,11 +4,12 @@ title: Configuration Quartz is meant to be extremely configurable, even if you don't know any coding. Most of the configuration you should need can be done by just editing `quartz.config.ts`. -If you edit this file using a text-editor that has TypeScript language support like VSCode, it will warn you when you you've made an error in your configuration. +> [!tip] +> If you edit this file using a text-editor that has TypeScript language support like VSCode, it will warn you when you you've made an error in your configuration, helping you avoid configuration mistakes! This configuration can be broken down into two main parts: -```ts +```ts title="quartz.config.ts" const config: QuartzConfig = { configuration: { ... }, plugins: { ... }, @@ -81,24 +82,41 @@ If you'd like to make your own plugins, read the guide on [[making plugins]] for Certain emitters may also output [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML) files. To enable easy customization, these emitters allow you to fully rearrange the layout of the page. The default page layouts can be found in `quartz.layout.ts`. -Ultimately, each page is composed of multiple different sections which contain `QuartzComponents`. The following code snippet lists all of the valid sections that you can add components to: +Each page is composed of multiple different sections which contain `QuartzComponents`. The following code snippet lists all of the valid sections that you can add components to: ```typescript title="quartz/cfg.ts" export interface FullPageLayout { - head: QuartzComponent - header: QuartzComponent[] - beforeBody: QuartzComponent[] - pageBody: QuartzComponent - left: QuartzComponent[] - right: QuartzComponent[] - footer: QuartzComponent + 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 } ``` These correspond to following parts of the page: -### Components +![[quartz-layout.png|800]] -See [a list of all the components](./tags/component) for all available components. +> [!note] +> There are two additional layout fields that are *not* shown in the above diagram. +> 1. `head` is a single component that renders the `` [tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head) in the HTML. This doesn't appear visually on the page and is only is responsible for metadata about the document like the tab title, scripts, and styles. +> 2. `header` is a set of components that are laid out horizontally and appears *before* the `beforeBody` section. This enables you to replicate the old Quartz 3 header bar where the title, search bar, and dark mode toggle. By default, Quartz 4 doesn't place any components in the `header`. + +Quartz **components**, like plugins, can take in additional properties as configuration options. If you're familiar with React terminology, you can think of them as Higher-order Components. + +See [a list of all the components](./tags/component) for all available components along with their configuration options. ### Style +Most meaningful style changes like colour scheme and font can be done simply through the [[#General Configuration|general configuration]] options above. + +However, if you'd like to make more involved style changes, you can do this by writing your own styles. Quartz 4, like Quartz 3, uses [Sass](https://sass-lang.com/guide/) for styling. + +You can see the base style sheet in `quartz/styles/base.scss` and write your own in `quartz/styles/custom.scss`. + +> [!note] +> Some components may provide their own styling as well! For example, `quartz/components/Darkmode.tsx` imports its styles from `quartz/components/styles/darkmode.scss`. If you'd like to customize styling for a specific component, double check the component definition to see how its styles are defined. + +When you're ready, see how [[build|build and preview]] Quartz locally. \ No newline at end of file diff --git a/content/features/popover previews.md b/content/features/popover previews.md index 7bf608e0..f8822240 100644 --- a/content/features/popover previews.md +++ b/content/features/popover previews.md @@ -2,7 +2,7 @@ title: Popover Previews --- -Like Wikipedia, when you hover over a link in Quartz, there is a popup of a page preview that you can scroll to see the entire content. +Like Wikipedia, when you hover over a link in Quartz, there is a popup of a page preview that you can scroll to see the entire content. Links to headers will also scroll the popup to show that specific header in view. By default, Quartz only fetches previews for pages inside your vault due to [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS). It does this by selecting all HTML elements with the `popover-hint` class. For most pages, this includes the page title, page metadata like words and time to read, tags, and the actual page content. diff --git a/content/features/upcoming features.md b/content/features/upcoming features.md index 46390bd8..8ab75202 100644 --- a/content/features/upcoming features.md +++ b/content/features/upcoming features.md @@ -7,6 +7,7 @@ draft: true - 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 - static dead link detection +- docker support ## misc diff --git a/content/hosting.md b/content/hosting.md index a7043137..f644e4d6 100644 --- a/content/hosting.md +++ b/content/hosting.md @@ -2,6 +2,49 @@ 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 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.) ## GitHub Pages +Like Quartz 3, you can deploy the site generated by Quartz 4 via GitHub Pages. + +In your local Quartz, create a new file `quartz/.github/workflows/deploy.yaml`: + +```yaml title="quartz/.github/workflows/deploy.yaml" +name: Deploy to GitHub Pages + +on: + push: + branches: + - v4-alpha + +jobs: + deploy: + runs-on: ubuntu-22.04 + steps: + - uses: actions/checkout@v2 + 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: Deploy + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./public + publish_branch: master # deploying branch + cname: quartz.jzhao.xyz +``` + +Then, the next time you ## Cloudflare Pages diff --git a/content/index.md b/content/index.md index 77f14e1a..0659e881 100644 --- a/content/index.md +++ b/content/index.md @@ -18,11 +18,7 @@ npm i npx quartz create ``` -This will guide you through initializing your Quartz with content. - -When you're ready, you can edit `quartz.config.ts` to customize and configure Quartz more. Read the [[configuration]] page for more information on what each field in the configuration does. - -Then, when you're ready, see how to [[build]] and [[hosting|host]] Quartz. +This will guide you through initializing your Quartz with content. Once you've done so, see how to [[build]] and [[hosting|host]] Quartz. > [!info] > Coming from Quartz 3? See the [[migrating from Quartz 3|migration guide]] for the differences between Quartz 3 and Quartz 4 and how to migrate. @@ -30,6 +26,7 @@ Then, when you're ready, see how to [[build]] and [[hosting|host]] Quartz. ## 🔧 Features - [[full-text search|Full-text search]], [[graph view]], [[backlinks]], [[Latex]], [[syntax highlighting]], [[popover previews]], and many more right out of the box +- Hot-reload for both configuration and content - Simple JSX [[creating components|layouts and page components]] - [[SPA Routing|Ridiculously fast page loads]] and tiny bundle sizes - Fully-customizable parsing, filtering, and page generation through [[making plugins|plugins]] diff --git a/content/migrating from Quartz 3.md b/content/migrating from Quartz 3.md index e69de29b..c2e4c4eb 100644 --- a/content/migrating from Quartz 3.md +++ b/content/migrating from Quartz 3.md @@ -0,0 +1,26 @@ +--- +title: "Migrating from Quartz 3" +--- + +As you already have Quartz locally, you don't need to fork or clone it again. Simply just checkout the alpha branch, install the dependencies, and import your old vault. + +```bash +git checkout v4-alpha +npm i +npx quartz create +``` + +When running `npx quartz create`, you will be prompted as to how to initialize your content folder. Here, you can choose to import or link your previous content folder and Quartz should work just as you expect it to. + +## Key changes + +1. **Removing Hugo and `hugo-obsidian`**: Hugo worked well for earlier versions of Quartz but it also made it hard for people outside of the Golang and Hugo communities to fully understand what Quartz was doing under the hood and be able to properly customize it to their needs. Quartz 4 now uses a Node-based static-site generation process which should lead to a much more helpful error messages and an overall smoother user experience. +2. **Full-hot reload**: The many rough edges of how `hugo-obsidian` integrated with Hugo meant that watch mode didn't re-trigger `hugo-obsidian` to update the content index. This lead to a lot of weird cases where the watch mode output wasn't accurate. Quartz 4 now uses a cohesive parse, filter, and emit pipeline which gets run on every change so hot-reloads are always accurate. +3. **Replacing Go template syntax with JSX**: Quartz 3 used [Go templates](https://pkg.go.dev/text/template) to create layouts for pages. However, the syntax isn't great for doing any sort of complex rendering (like [text processing](https://github.com/jackyzha0/quartz/blob/hugo/layouts/partials/textprocessing.html)) and it got very difficult to make any meaningful layout changes to Quartz 3. Quartz 4 uses an extension of JavaScript syntax called JSX which allows you to write layout code that looks like HTML in JavaScript which is significantly easier to understand and maintain. +4. **A new extensible [[configuration]] and [[configuration#Plugins|plugin]] system**: Quartz 3 was hard to configure without technical knowledge of how Hugo's partials worked. Extensions were even hard to make. Quartz 4's configuration and plugin system is designed to be extended by users while making updating to new versions of Quartz easy. + +## Things to update + +- 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 also need to update your deploy scripts. See the [[hosting]] guide for more details. \ No newline at end of file diff --git a/content/quartz-layout.png b/content/quartz-layout.png new file mode 100644 index 00000000..4767b549 Binary files /dev/null and b/content/quartz-layout.png differ diff --git a/quartz.layout.ts b/quartz.layout.ts index f47b2249..1a3f99fa 100644 --- a/quartz.layout.ts +++ b/quartz.layout.ts @@ -1,8 +1,8 @@ -import { PageLayout } from "./quartz/cfg" +import { PageLayout, SharedLayout } from "./quartz/cfg" import * as Component from "./quartz/components" // components shared across all pages -export const sharedPageComponents = { +export const sharedPageComponents: SharedLayout = { head: Component.Head(), header: [], footer: Component.Footer({ diff --git a/quartz/cfg.ts b/quartz/cfg.ts index d8a14a32..3c9613b7 100644 --- a/quartz/cfg.ts +++ b/quartz/cfg.ts @@ -45,3 +45,4 @@ export interface FullPageLayout { } export type PageLayout = Pick +export type SharedLayout = Pick diff --git a/quartz/path.ts b/quartz/path.ts index 494d3c5d..9af5c7bf 100644 --- a/quartz/path.ts +++ b/quartz/path.ts @@ -228,7 +228,7 @@ function _isRelativeSegment(s: string): boolean { return /^\.{0,2}$/.test(s) } -function _stripSlashes(s: string): string { +export function _stripSlashes(s: string): string { if (s.startsWith("/")) { s = s.substring(1) } diff --git a/quartz/plugins/transformers/links.ts b/quartz/plugins/transformers/links.ts index 07650621..9a9195bb 100644 --- a/quartz/plugins/transformers/links.ts +++ b/quartz/plugins/transformers/links.ts @@ -2,6 +2,7 @@ import { QuartzTransformerPlugin } from "../types" import { CanonicalSlug, RelativeURL, + _stripSlashes, canonicalizeServer, joinSegments, pathToRoot, @@ -35,7 +36,7 @@ export const CrawlLinks: QuartzTransformerPlugin | undefined> = return (tree, file) => { const curSlug = canonicalizeServer(file.data.slug!) const transformLink = (target: string): RelativeURL => { - const targetSlug = transformInternalLink(target).slice("./".length) + const targetSlug = _stripSlashes(transformInternalLink(target).slice(".".length)) let [targetCanonical, targetAnchor] = splitAnchor(targetSlug) if (opts.markdownLinkResolution === "relative") { return targetSlug as RelativeURL diff --git a/quartz/plugins/transformers/ofm.ts b/quartz/plugins/transformers/ofm.ts index 8d8d4573..0904ed12 100644 --- a/quartz/plugins/transformers/ofm.ts +++ b/quartz/plugins/transformers/ofm.ts @@ -225,7 +225,6 @@ export const ObsidianFlavoredMarkdown: QuartzTransformerPlugin } // internal link - // const url = transformInternalLink(fp + anchor) const url = fp + anchor return { type: "link", diff --git a/quartz/styles/base.scss b/quartz/styles/base.scss index 72919396..6bed7ca2 100644 --- a/quartz/styles/base.scss +++ b/quartz/styles/base.scss @@ -81,7 +81,9 @@ a { .page { @media all and (max-width: $fullPageWidth) { - margin: 0 5vw; + margin: 0 auto; + padding: 0 1rem; + max-width: 800px; } & article {