mobile fixes, fix bug when linking to anchor on home, docs
This commit is contained in:
Jacky Zhao
parent
db6054a8c1
commit
028bcec62c
@ -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
|
||||
@ -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 `<head>` [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.
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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]]
|
||||
|
||||
@ -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.
|
||||
BIN
content/quartz-layout.png
Normal file
BIN
content/quartz-layout.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 62 KiB |
@ -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({
|
||||
|
||||
@ -45,3 +45,4 @@ export interface FullPageLayout {
|
||||
}
|
||||
|
||||
export type PageLayout = Pick<FullPageLayout, "beforeBody" | "left" | "right">
|
||||
export type SharedLayout = Pick<FullPageLayout, "head" | "header" | "footer">
|
||||
|
||||
@ -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)
|
||||
}
|
||||
|
||||
@ -2,6 +2,7 @@ import { QuartzTransformerPlugin } from "../types"
|
||||
import {
|
||||
CanonicalSlug,
|
||||
RelativeURL,
|
||||
_stripSlashes,
|
||||
canonicalizeServer,
|
||||
joinSegments,
|
||||
pathToRoot,
|
||||
@ -35,7 +36,7 @@ export const CrawlLinks: QuartzTransformerPlugin<Partial<Options> | 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
|
||||
|
||||
@ -225,7 +225,6 @@ export const ObsidianFlavoredMarkdown: QuartzTransformerPlugin<Partial<Options>
|
||||
}
|
||||
|
||||
// internal link
|
||||
// const url = transformInternalLink(fp + anchor)
|
||||
const url = fp + anchor
|
||||
return {
|
||||
type: "link",
|
||||
|
||||
@ -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 {
|
||||
|
||||
Loading…
Reference in New Issue
Block a user