Decluttering quarto artifacts (e.g., sitemap, *.html) in git, seeking workflow advice

[dikiprawisuda]

Description

Hi everyone, I hope this post finds you all well.

I'm relatively new to web development with Quarto (or at all), and I'm trying to refine my Git workflow. Here's a little background, along with some lessons that might be useful for others.

Lesson 1: Organize articles in date-based folders

My website is a basic blog featuring work in R and/or Python with a reproducible workflow. I organize all my content into ./articles/<date>/ folders, which keeps assets like images neatly contained. I learned that you can do wonders with an index.qmd inside a directory — this way, article URIs end with */<date>/ instead of */<date>.html, which is much cleaner and less limiting.

Lesson 2: Render locally to preserve date-modified

I use GitLab Pages to host my website. Previously, I used GitLab's CI/CD to render remotely after every push. Not only did deployment take a while, but it also scrambled all the date-modified information — untouched articles would get an updated date-modified, which is undesirable. I switched to rendering locally and configured Quarto to output to /public/:

# Inside `_quarto.yml`
project:
  type: website
  output-dir: public  # Important for GitLab Pages
# etc...

The problem: Git noise from rendered output

When working on blog subfolders and running quarto preview, I notice a lot of noise in my Git status — folders like public/ and _freeze/. I fully recognize that these artifacts are essential for the browser to render the site and for GitLab Pages to serve it; however, they are rendered artifacts, not the source files (.qmd) I actually care about tracking.

I've been working this way for a while, so the noise is likely already baked into my Git history. I'm worried it's cluttering things and making past changes hard to review.

Ideally, whenever I change a .qmd and peek at the results with quarto preview, I'd like to commit only the changed .qmd with a meaningful commit message — almost like the "version history" feature in Google Docs so that I can focus on the writing part. I'd also like to minimize re-rendering by only rebuilding what has actually changed.

Questions

For those of you managing Quarto sites, especially if you've been at it for a while:

1. What is your Git strategy? Do you ignore rendered HTML entirely, or commit it for hosting purposes (e.g., GitLab Pages)? I'd be open to something like committing only .qmd files and using hooks to render before pushing.
2. How do you use _freeze and caching? Any tips for minimizing unnecessary re-renders?
3. Cleaning up history: If you started by committing everything (like I did), did you bother cleaning the history, or just start ignoring the files going forward?

I'm looking for a sustainable best practice that keeps things tidy without too much overhead.

Thanks for any insights!

[mcanouil]

1. quarto preview and quarto render should cleanup your workspace, unless you killed it.

2. See the documentation about freeze and cache.

3. Not sure to get what you mean. Quarto creates a .gitignore file with a default ignore list that should cover standard usage. If you want to rewrite your whole Git history, do so. It really depends on what you want.