note formatting

This commit is contained in:
Jacky Zhao 2023-08-06 19:54:11 -07:00
parent 3adc73a703
commit 075ac33474
5 changed files with 35 additions and 33 deletions

View File

@ -16,10 +16,11 @@ Once you're happy with it, let's see how to [[hosting|deploy Quartz to the web]]
> [!hint] Flags and options > [!hint] Flags and options
> For full help options, you can run `npx quartz build --help`. > 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: > 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` > - `-d` or `--directory`: the content folder. This is normally just `content`
> - `-v` or `--verbose`: print out extra logging information > - `-v` or `--verbose`: print out extra logging information
> - `-o` or `--output`: the output folder. This is normally just `public` > - `-o` or `--output`: the output folder. This is normally just `public`
> - `--serve`: run a local hot-reloading server to preview your Quartz > - `--serve`: run a local hot-reloading server to preview your Quartz
> - `--port`: what port to run the local preview server on > - `--port`: what port to run the local preview server on

View File

@ -86,13 +86,13 @@ Each page is composed of multiple different sections which contain `QuartzCompon
```typescript title="quartz/cfg.ts" ```typescript title="quartz/cfg.ts"
export interface FullPageLayout { export interface FullPageLayout {
head: QuartzComponent // single component head: QuartzComponent // single component
header: QuartzComponent[] // laid out horizontally header: QuartzComponent[] // laid out horizontally
beforeBody: QuartzComponent[] // laid out vertically beforeBody: QuartzComponent[] // laid out vertically
pageBody: QuartzComponent // single component pageBody: QuartzComponent // single component
left: QuartzComponent[] // vertical on desktop, horizontal on mobile left: QuartzComponent[] // vertical on desktop, horizontal on mobile
right: QuartzComponent[] // vertical on desktop, horizontal on mobile right: QuartzComponent[] // vertical on desktop, horizontal on mobile
footer: QuartzComponent // single component footer: QuartzComponent // single component
} }
``` ```
@ -101,22 +101,24 @@ These correspond to following parts of the page:
![[quartz-layout.png|800]] ![[quartz-layout.png|800]]
> [!note] > [!note]
> There are two additional layout fields that are *not* shown in the above diagram. > 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. > 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`. > 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. 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. See [a list of all the components](./tags/component) for all available components along with their configuration options.
### Style ### Style
Most meaningful style changes like colour scheme and font can be done simply through the [[#General Configuration|general configuration]] options above.
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. 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`. You can see the base style sheet in `quartz/styles/base.scss` and write your own in `quartz/styles/custom.scss`.
> [!note] > [!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. > 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. When you're ready, see how [[build|build and preview]] Quartz locally.

View File

@ -12,12 +12,12 @@ However, if you'd like to publish your site to the world, you need a way to host
2. In Account Home, select **Workers & Pages** > **Create application** > **Pages** > **Connect to Git**. 2. In Account Home, select **Workers & Pages** > **Create application** > **Pages** > **Connect to Git**.
3. Select the new GitHub repository that you created and, in the **Set up builds and deployments** section, provide the following information: 3. Select the new GitHub repository that you created and, in the **Set up builds and deployments** section, provide the following information:
|Configuration option|Value| | Configuration option | Value |
|---|---| | ---------------------- | ------------------ |
|Production branch|`v4-alpha`| | Production branch | `v4-alpha` |
|Framework preset|`None`| | Framework preset | `None` |
|Build command|`npx quartz build`| | Build command | `npx quartz build` |
|Build output directory|`public`| | Build output directory | `public` |
Press "Save and deploy" and Cloudflare should have a deployed version of your site in about a minute. Then, every time you sync your Quartz changes to GitHub, your site should be updated. Press "Save and deploy" and Cloudflare should have a deployed version of your site in about a minute. Then, every time you sync your Quartz changes to GitHub, your site should be updated.
@ -80,26 +80,25 @@ jobs:
Then, commit these changes by doing `npx quartz sync`. This should deploy your site to `<github-username>.github.io/<repository-name>`. Then, commit these changes by doing `npx quartz sync`. This should deploy your site to `<github-username>.github.io/<repository-name>`.
### Custom Domain ### Custom Domain
Here's how to add a custom domain to your GitHub pages deployment. Here's how to add a custom domain to your GitHub pages deployment.
1. Head to the "Settings" tab of your forked repository. 1. Head to the "Settings" tab of your forked repository.
2. In the "Code and automation" section of the sidebar, click "Pages". 2. In the "Code and automation" section of the sidebar, click "Pages".
3. Under "Custom Domain", type your custom domain and click "Save". 3. Under "Custom Domain", type your custom domain and click "Save".
4. This next step depends on whether you are using an apex domain (`example.com`) or a subdomain (`subdomain.example.com`). 4. This next step depends on whether you are using an apex domain (`example.com`) or a subdomain (`subdomain.example.com`).
- If you are using an apex domain, navigate to your DNS provider and create an `A` record that points your apex domain to GitHub's name servers which have the following IP addresses: - If you are using an apex domain, navigate to your DNS provider and create an `A` record that points your apex domain to GitHub's name servers which have the following IP addresses:
- `185.199.108.153` - `185.199.108.153`
- `185.199.109.153` - `185.199.109.153`
- `185.199.110.153` - `185.199.110.153`
- `185.199.111.153` - `185.199.111.153`
- If you are using a subdomain, navigate to your DNS provider and create a `CNAME` record that points your subdomain to the default domain for your site. For example, if you want to use the subdomain `quartz.example.com` for your user site, create a `CNAME` record that points `quartz.example.com` to `<github-username>.github.io`. - If you are using a subdomain, navigate to your DNS provider and create a `CNAME` record that points your subdomain to the default domain for your site. For example, if you want to use the subdomain `quartz.example.com` for your user site, create a `CNAME` record that points `quartz.example.com` to `<github-username>.github.io`.
![[dns-records.png]]_The above shows a screenshot of Google Domains configured for both `jzhao.xyz` (an apex domain) and `quartz.jzhao.xyz` (a subdomain)._
![[dns-records.png]]*The above shows a screenshot of Google Domains configured for both `jzhao.xyz` (an apex domain) and `quartz.jzhao.xyz` (a subdomain).* See the [GitHub documentation](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site#configuring-a-subdomain) for more detail about how to setup your own custom domain with GitHub Pages.
See the [GitHub documentation](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site#configuring-a-subdomain) for more detail about how to setup your own custom domain with GitHub Pages.
> [!question] Why aren't my changes showing up? > [!question] Why aren't my changes showing up?
> There could be many different reasons why your changes aren't showing up but the most likely reason is that you forgot to push your changes to GitHub. > There could be many different reasons why your changes aren't showing up but the most likely reason is that you forgot to push your changes to GitHub.
> >
> Make sure you save your changes to Git and sync it to GitHub by doing `npx quartz sync`. This will also make sure to pull any updates you may have made from other devices so you have them locally. > Make sure you save your changes to Git and sync it to GitHub by doing `npx quartz sync`. This will also make sure to pull any updates you may have made from other devices so you have them locally.

View File

@ -23,4 +23,4 @@ When running `npx quartz create`, you will be prompted as to how to initialize y
- 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. - 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. - 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. - You will also need to update your deploy scripts. See the [[hosting]] guide for more details.

View File

@ -3,4 +3,4 @@ title: "Upgrading Quartz"
--- ---
> [!note] > [!note]
> This is specifically a guide for upgrading Quartz 4 version to a more recent update. If you are coming from Quartz 3, check out the [[migrating from Quartz 3|migration guide]] for more info. > This is specifically a guide for upgrading Quartz 4 version to a more recent update. If you are coming from Quartz 3, check out the [[migrating from Quartz 3|migration guide]] for more info.