mirror of https://github.com/logos-co/roadmap.git
229 lines
7.3 KiB
Markdown
229 lines
7.3 KiB
Markdown
---
|
|
title: "Configuration"
|
|
tags:
|
|
- setup
|
|
weight: 0
|
|
---
|
|
|
|
## 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.
|
|
|
|
```yaml {title="data/config.yaml"}
|
|
# The name to display in the footer
|
|
name: Jacky Zhao
|
|
|
|
# whether to globally show the table of contents on each page
|
|
# this can be turned off on a per-page basis by adding this to the
|
|
# front-matter of that note
|
|
enableToc: true
|
|
|
|
# whether to by-default open or close the table of contents on each page
|
|
openToc: false
|
|
|
|
# whether to display on-hover link preview cards
|
|
enableLinkPreview: true
|
|
|
|
# whether to render titles for code blocks
|
|
enableCodeBlockTitle: true
|
|
|
|
# whether to render copy buttons for code blocks
|
|
enableCodeBlockCopy: true
|
|
|
|
# whether to render callouts
|
|
enableCallouts: true
|
|
|
|
# whether to try to process Latex
|
|
enableLatex: true
|
|
|
|
# whether to enable single-page-app style rendering
|
|
# this prevents flashes of unstyled content and improves
|
|
# smoothness of Quartz. More info in issue #109 on GitHub
|
|
enableSPA: true
|
|
|
|
# whether to render a footer
|
|
enableFooter: true
|
|
|
|
# whether backlinks of pages should show the context in which
|
|
# they were mentioned
|
|
enableContextualBacklinks: true
|
|
|
|
# whether to show a section of recent notes on the home page
|
|
enableRecentNotes: false
|
|
|
|
# whether to display an 'edit' button next to the last edited field
|
|
# that links to github
|
|
enableGitHubEdit: true
|
|
GitHubLink: https://github.com/jackyzha0/quartz/tree/hugo/content
|
|
|
|
# whether to render mermaid diagrams
|
|
enableMermaid: true
|
|
|
|
# whether to use Operand to power semantic search
|
|
# IMPORTANT: replace this API key with your own if you plan on using
|
|
# Operand search!
|
|
search:
|
|
enableSemanticSearch: false
|
|
operandApiKey: "REPLACE-WITH-YOUR-OPERAND-API-KEY"
|
|
operandIndexId: "REPLACE-WITH-YOUR-OPERAND-INDEX-ID"
|
|
|
|
# page description used for SEO
|
|
description:
|
|
Host your second brain and digital garden for free. Quartz features extremely fast full-text search,
|
|
Wikilink support, backlinks, local graph, tags, and link previews.
|
|
|
|
# title of the home page (also for SEO)
|
|
page_title:
|
|
"🪴 Quartz 3.3"
|
|
|
|
# links to show in the footer
|
|
links:
|
|
- link_name: Twitter
|
|
link: https://twitter.com/_jzhao
|
|
- link_name: Github
|
|
link: https://github.com/jackyzha0
|
|
```
|
|
|
|
### Code Block Titles
|
|
To add code block titles with Quartz:
|
|
|
|
1. Ensure that code block titles are enabled in Quartz's configuration:
|
|
|
|
```yaml {title="data/config.yaml", linenos=false}
|
|
enableCodeBlockTitle: true
|
|
```
|
|
|
|
2. Add the `title` attribute to the desired [code block
|
|
fence](https://gohugo.io/content-management/syntax-highlighting/#highlighting-in-code-fences):
|
|
|
|
```markdown {linenos=false}
|
|
```yaml {title="data/config.yaml"}
|
|
enableCodeBlockTitle: true # example from step 1
|
|
```
|
|
```
|
|
|
|
**Note** that if `{title=<my-title>}` is included, and code block titles are not
|
|
enabled, no errors will occur, and the title attribute will be ignored.
|
|
|
|
### HTML Favicons
|
|
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:
|
|
|
|
```html {title="layouts/partials/head.html", linenostart=15}
|
|
<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. For example, here is a `List[Dictionary]` example format, which is
|
|
equivalent to the default:
|
|
|
|
```yaml {title="data/config.yaml", linenos=false}
|
|
favicon:
|
|
- { rel: "shortcut icon", href: "icon.png", type: "image/png" }
|
|
# - { ... } # Repeat for each additional favicon you want to add
|
|
```
|
|
|
|
In this format, the keys are identical to their HTML representations.
|
|
|
|
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:
|
|
|
|
```yaml {title="data/config.yaml", linenos=false}
|
|
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](https://www.emergeinteractive.com/insights/detail/the-essentials-of-favicons/).
|
|
|
|
**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`.
|
|
|
|
```yaml {title="data/graphConfig.yaml"}
|
|
# if true, a Global Graph will be shown on home page with full width, no backlink.
|
|
# A different set of Local Graphs will be shown on sub pages.
|
|
# if false, Local Graph will be default on every page as usual
|
|
enableGlobalGraph: false
|
|
|
|
### Local Graph ###
|
|
localGraph:
|
|
# whether automatically generate a legend
|
|
enableLegend: false
|
|
|
|
# whether to allow dragging nodes in the graph
|
|
enableDrag: true
|
|
|
|
# whether to allow zooming and panning the graph
|
|
enableZoom: true
|
|
|
|
# how many neighbours of the current node to show (-1 is all nodes)
|
|
depth: 1
|
|
|
|
# initial zoom factor of the graph
|
|
scale: 1.2
|
|
|
|
# how strongly nodes should repel each other
|
|
repelForce: 2
|
|
|
|
# how strongly should nodes be attracted to the center of gravity
|
|
centerForce: 1
|
|
|
|
# what the default link length should be
|
|
linkDistance: 1
|
|
|
|
# how big the node labels should be
|
|
fontSize: 0.6
|
|
|
|
# scale at which to start fading the labes on nodes
|
|
opacityScale: 3
|
|
|
|
### Global Graph ###
|
|
globalGraph:
|
|
# same settings as above
|
|
|
|
### For all graphs ###
|
|
# colour specific nodes path off of their path
|
|
paths:
|
|
- /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 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.](https://gohugo.io/templates/partials/)
|
|
|
|
Still having problems? Checkout our [FAQ and Troubleshooting guide](notes/troubleshooting.md).
|
|
|
|
## Language Support
|
|
[CJK + Latex Support (测试)](notes/CJK%20+%20Latex%20Support%20(测试).md) 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](https://gohugo.io/content-management/multilingual/#configure-languages) and modify your `config.toml`
|
|
|
|
For example:
|
|
|
|
```toml
|
|
defaultContentLanguage = 'ar'
|
|
[languages]
|
|
[languages.ar]
|
|
languagedirection = 'rtl'
|
|
title = 'مدونتي'
|
|
weight = 1
|
|
```
|