Quartz is an easy static site generator that you can use in tandem with Obsidian (a free markdown writing program) to quickly and easily create webpages without having to do a lot of coding. After setting it up, you just write your articles in obsidian, put in two commands and your site is published to the web.
It is recommended (by me at least) to have a basic understanding of CSS and the very basics of JavaScript formatting before starting as it well help you a lot with any troubleshooting that you may need to do.
Quartz Documentation - Follow the Quartz setup guide first.
Commands
Building:
npx quartz build --serve - Builds your pages and creates local preview. Remove --serve to only build without hosting a local preview.
NOTE
You need to make sure you put in this command every time before you do the sync command, otherwise it won’t build the HTML for any of your new articles and nothing will happen when you sync with github.
Sync:
npx quartz sync - syncs with github. Add --no-pull on the end to stop it from pulling from github if needed.
Private Pages
To make a page private and not publish it, add draft: - true to the frontmatter/properties of your page in Obsidian.
- I have yet to test if this works, I actually have two digital gardens/obsidian vaults and any pages I don’t want added to this site, I just don’t add to this vault.
Deploy to Neocities
In order to get your site to deploy to Neocities every time you push to github, you need to create a file in your .github/workflows directory called neocities.yaml and inside of that, you need to add the code from here into that file.
NOTE
Side note: If your yaml/yma file is not working, make sure that hidden file extensions is turned off on windows otherwise it will still be a .txt file. I had that issue and I couldn’t figure out why it wasn’t working.
Then, after making that file, you need to also go into your github’s repo’s secrets and make a new secret called NEOCITIES_API_TOKEN and add in your Neocities API key as the secret.
Then, every time files are put into your public folder in your github repo, they will be put up on your neocities site as well.
Check the deploy-to-neocities site for more info on that.
How it works
I am still trying to figure out how it all works together, I don’t really understand Javascript or SCSS, but this is what I have figured out on my own so far:
Components
In order to change the layout of the pages or add extra things, you need to play around with the components.
You can add or remove certain components, like the graph, page explorer, search bar, etc to get your desired page layout.
I have yet to figure out how to do that on a page-by page basis yet though… Like if I wanted one thing only on the index page, how would I make it so it’s only on that one page and not all of them? I need to try and figure that out.
In order to add a new component, you need three files:
quartz/components/NAMEHERE.tsx
quartz/components/styles/NAMEHERE.scss
quartz/components/scripts/NAMEHERE.inline.ts
These three files make up the component.
and then, in your quartz/components/index.ts file you need to add two things:
-
import NAMEHERE from "./NAMEHERE"(NAMEHERE being the name of your component) -
And in the ‘export’ section of the file you need to add the name of the component you want to add as well.
That is how I added the page randomizer component by t-schreibs But I have no idea how to customise it just yet. I would like to add some text to it, but I cannot figure out how to just yet.
Font and colors
You can easily change the colours for both light and dark mode in the quartz.config.ts file.
However, adding you own extra custom colors to this config file has proven too confusing for me at the moment. I cannot figure out how to add my own extra colors for custom things to these light and dark modes. I can only do it in the custom.scss file which makes it the same for both light and dark mode.
Personal Customizations I made
Spoiler Blur that goes away on hover
I created this spoiler blur effect that goes away when you hover over it. It was very easy to make.
You put this around any of the text you wish to blur out:
<span class="spoiler"></span>
Then, in the
quartz/custom.scss file just add
.spoiler { filter: blur(4px); transition: 0.2s; } and
.spoiler:hover { filter: blur(0px); transition: 0.5s; }
then you have a spoiler!
There is probably a better way to do it, but with my limited knowledge, this was the easiest way I could figure out how to do it!~