quartz/content/notes/config.md

title	tags
Configuration	setup

Configuration

Quartz is designed to be extremely configurable. You can find the bulk of the configuration scattered throughout the repository depending on how in-depth you'd like to get.

The majority of configuration can be found under data/config.yaml. An annotated example configuration is shown below.

name: Your name here! # Shows in the footer
enableToc: true # Whether to show a Table of Contents
enableLinkPreview: true # whether to render card previews for links
enableCodeBlockTitle: true # whether to render titles for code blocks
description: Page description to show to search engines
page_title: Quartz Example Page # Default Page Title

links: # Links to show in footer
  - link_name: Twitter
    link: https://twitter.com/_jzhao
  - link_name: Github
    link: https://github.com/jackyzha0

Code Block Titles

Quartz relies on Hugo's code highlighter, Chroma, which happens to be "really, really fast". As fast as it is, it does leave much to be desired, such as code block titles. In Obsidian, there's a plugin which provides this feature, called Obsidian Better Code Block. The idea behind the syntax is similar to Hugo's, although unfortunately not identical (stay tuned for a Quartz binary). To add code titles with Quartz:

1. Ensure that code block titles are enabled in Quartz's configuration:

   enableCodeBlockTitle: true
   

2. Add the title attribute to the desired code block. Note there are two ways of defining code blocks in Hugo.

   • Highlight Shortcode: Example not included as Hugo will insist on attempting to render it.

   • Highlight Code Fences: Example provided intentionally omits a single back quote.

     ```yaml {title="data/config.yaml"}
     enableCodeBlockTitle: true  # step 1 example
     ``
     

Note that if {title=<my-title>} is included, and code titles are not enabled, no errors will occur and the title attribute will be ignored. Furthermore, by enabling code blocks, the header of each page will contain a script which will automatically attempt to find code blocks, and render their titles. In other words, if you don't have any code blocks (with titles), rather disable this feature in the configuration. For more information on syntax see Hugo's syntax highlighting. Finally, you can style the code block titles with the assets/styles/code-title.scss file.

HTML Favicons

A Favicon is most commonly seen as the image preceding the URL in a browser. Some other examples include (but are not limited to) bookmarks, search history, and app icons (i.e. "save page to home screen" on mobile devices). File format support and the use of favicons differ across the combination of platforms and browsers.

If you would like to customize the favicons of your quartz-based website, you can add them to the data/config.yaml file. The default without any set favicon key is:

<link rel="shortcut icon" href="icon.png" type="image/png">

The default can be overridden by defining a value to the favicon key in your data/config.yaml file. Here is a List[Dictionary] example format, which is equivalent to the default:

favicon:
  - { rel: "shortcut icon", href: "icon.png", type: "image/png" }
#  - { ... } # Repeat for each additional favicon you want to add

In this format, the following keys are available:

• rel: The rel attribute of the <link> tag.
• type: The type attribute of the <link> tag.
• href (optional): The href attribute of the <link> tag.
• sizes (optional): The sizes attribute of the <link> tag.

If you plan to add multiple favicons generated by a website (see list below), it may be easier to define it as HTML. Here is an example which appends the Apple touch icon to quartz's default favicon:

favicon: |
  <link rel="shortcut icon" href="icon.png" type="image/png">
  <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">  

This second favicon will now be used as a web page icon when someone adds your webpage to the home screen of their Apple device. If you are interested in more information about the current, and past, standards of favicons, you can read this article.

Some websites that generate favicons for you (ordered alphabetically) include:

• favicon.io
• realfavicongenerator.net
• www.favicon.cc

These sites will take a base image and generate a set of favicons for you, one of which will be, for example, the apple-touch-icon favicon. These sites will often also provide the HTML for the favicon, which can be simply added to the data/config.yaml using the HTML format of the favicon argument.

Note that all generated favicon paths, defined by the href attribute, are relative to the static/ directory.

Graph View

To customize the Interactive Graph view, you can poke around data/graphConfig.yaml.

enableLegend: false # automatically generate a legend
enableDrag: true # allow dragging nodes in the graph
enableZoom: true # allow zooming and panning the graph
depth: -1 # how many neighbours of the current node to show (-1 is all nodes)
paths: # colour specific nodes path off of their path
  - /moc: "#4388cc"

Styling

Want to go even more in-depth? You can add custom CSS styling and change existing colours through editing assets/styles/custom.scss. If you'd like to target specific parts of the site, you can add ids and classes to the HTML partials in /layouts/partials.

Partials

Partials are what dictate what actually gets rendered to the page. Want to change how pages are styled and structured? You can edit the appropriate layout in /layouts.

For example, the structure of the home page can be edited through /layouts/index.html. To customize the footer, you can edit /layouts/partials/footer.html

More info about partials on Hugo's website.

Still having problems? Checkout our FAQ and Troubleshooting guide.

Multilingual

CJK + Latex Support (测试) comes out of the box with Quartz.

Want to support languages that read from right-to-left (like Arabic)? Hugo (and by proxy, Quartz) supports this natively.

Follow the steps Hugo provides here and modify your config.toml

For example:

defaultContentLanguage = 'ar'
[languages]
  [languages.ar]
    languagedirection = 'rtl'
    title = 'مدونتي'
    weight = 1