diff --git a/docs/features/breadcrumbs.md b/docs/features/breadcrumbs.md index 20c3b8d65605c..a241aac41a054 100644 --- a/docs/features/breadcrumbs.md +++ b/docs/features/breadcrumbs.md @@ -20,6 +20,7 @@ Component.Breadcrumbs({ 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, // wether to display the current page in the breadcrumbs }) ``` diff --git a/docs/hosting.md b/docs/hosting.md index a4ca1ea98bbc9..9761e5b45baa4 100644 --- a/docs/hosting.md +++ b/docs/hosting.md @@ -4,7 +4,10 @@ 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.) +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]]. > [!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! @@ -26,12 +29,10 @@ 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/). -## 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]]. +> 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 In your local Quartz, create a new file `quartz/.github/workflows/deploy.yml`. @@ -93,6 +94,9 @@ 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. @@ -167,9 +171,16 @@ 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 -## GitLab Pages +## Netlify -You can configure GitLab CI to build and deploy a Quartz 4 project. +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 In your local Quartz, create a new file `.gitlab-ci.yaml`. @@ -192,8 +203,6 @@ build: - hash -r - npm ci script: - - npx prettier --write . - - npm run check - npx quartz build artifacts: paths: @@ -216,6 +225,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 new file mode 100644 index 0000000000000..dd88931576194 Binary files /dev/null and b/docs/images/github-init-repo-options.png differ diff --git a/docs/images/github-quick-setup.png b/docs/images/github-quick-setup.png new file mode 100644 index 0000000000000..5be333f133387 Binary files /dev/null and b/docs/images/github-quick-setup.png differ diff --git a/docs/index.md b/docs/index.md index 85afee1f07101..655f5c39bcd69 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, wikis, 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, websites, 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|Author content]] in Quartz +1. [[authoring content|Writing 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 new file mode 100644 index 0000000000000..41655179d7bcf --- /dev/null +++ b/docs/setting up your GitHub repository.md @@ -0,0 +1,31 @@ +--- +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/docs/showcase.md b/docs/showcase.md index ed9df9f572ae1..a5ed89bc90a51 100644 --- a/docs/showcase.md +++ b/docs/showcase.md @@ -20,5 +20,6 @@ Want to see what Quartz can do? Here are some cool community gardens: - [🧠🌳 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/) 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)! diff --git a/package-lock.json b/package-lock.json index a879078977376..7c12e7146da5d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@jackyzha0/quartz", - "version": "4.0.11", + "version": "4.1.2", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@jackyzha0/quartz", - "version": "4.0.11", + "version": "4.1.2", "license": "MIT", "dependencies": { "@clack/prompts": "^0.6.3", @@ -85,7 +85,8 @@ "typescript": "^5.0.4" }, "engines": { - "node": ">=18.14" + "node": ">=18.14", + "npm": ">=9.3.1" } }, "node_modules/@clack/core": { diff --git a/package.json b/package.json index aa6324366aa4e..0a746dc3f512c 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.1", + "version": "4.1.2", "type": "module", "author": "jackyzha0 ", "license": "MIT", diff --git a/quartz/cli/handlers.js b/quartz/cli/handlers.js index 96ee9bc88ba5a..7a83c5d8fb6bb 100644 --- a/quartz/cli/handlers.js +++ b/quartz/cli/handlers.js @@ -196,6 +196,11 @@ 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/Breadcrumbs.tsx b/quartz/components/Breadcrumbs.tsx index 29c73a81b58b1..8998c406498a1 100644 --- a/quartz/components/Breadcrumbs.tsx +++ b/quartz/components/Breadcrumbs.tsx @@ -25,6 +25,10 @@ interface BreadcrumbOptions { * Wether to display breadcrumbs on root `index.md` */ hideOnRoot: boolean + /** + * Wether to display the current page in the breadcrumbs. + */ + showCurrentPage: boolean } const defaultOptions: BreadcrumbOptions = { @@ -32,6 +36,7 @@ const defaultOptions: BreadcrumbOptions = { rootName: "Home", resolveFrontmatterTitle: true, hideOnRoot: true, + showCurrentPage: true, } function formatCrumb(displayName: string, baseSlug: FullSlug, currentSlug: SimpleSlug): CrumbData { @@ -95,10 +100,12 @@ export default ((opts?: Partial) => { } // Add current file to crumb (can directly use frontmatter title) - crumbs.push({ - displayName: fileData.frontmatter!.title, - path: "", - }) + if (options.showCurrentPage) { + crumbs.push({ + displayName: fileData.frontmatter!.title, + path: "", + }) + } } return (