تنظیمات سفارشی من برای کوارتز

در طول استفاده از کوارتز، به مرور زمان تغییرات و اصلاحات مختلفی رو برای شخصی‌سازی سایت انجام دادم. اینجا فهرستی از این تغییرات رو ثبت کردم. این موارد رو بیشتر به عنوان یک مرجع شخصی درست کردم، تا اگر خواستم تنظیمات رو تغییر بدم بهش مراجعه کنم.

البته اگر شما هم میخوایید سایت تون رو شخصی سازی کنید میتونید از این تنظیمات استفاده کنید.

🚀 آپدیت به ورژن 4.5.0

نسخه قبلی کوارتز من 4.2.5 بود. 26 اردیبهشت به ورژن 4.5.0 آپدیتش کردم. توی این آپدیت تنظیمات سفارشی خودم رو بهینه تر کردم. قبلا مستقیما کد های اصلی رو ویرایش کرده بودم. الان اغلب سعی کردم تغییرات رو طوری انجام بدم که کد های اصلی کمترین تغییر رو داشته باشن. اینطوری موقع آپدیت با تضاد های کمتری مواجه میشه.

تغییرات قبلی که مربوط به نسخه 4.2.5 کوارتز بود رو توی یادداشت زیر نوشته بودم و تصمیم گرفتم حذفش نکنم. شاید یه روز به کار بیاد:

گورستان سفارشی سازی کوراتز - ورژن 4.2.5

بخش اول: رابط کاربری

قبل از هر چیز باید جهت صفحه رو راستچین (RTL) کنیم تا برای فارسی مناسب باشه. برای اینکار باید فایل renderPage.tsx رو ویرایش کنید. به این شکل:

components/renderPage.tsx

<html dir="rtl" lang={lang}>

چینش محتویات صفحه در فایل quartz.layout.ts انجام میشه. من اینطوری تنظیمش کردم:

هدر: پیج تایتل، جستجو، دارک مود
سایدبار چپ: گراف ویو
سایدبار راست: فهرست مطالب
افتربادی: بک لینک، تگ لیست، کامنت

یک استایل خاص هم برای عنصر های اصلی در نظر گرفتم:

هدر رو به حالت navbar تبدیل کردم.
به title page یک تصویر اضافه کردم به عنوان لوگوی سایت.
بک گراند رو خاکستری کردم و به المان های اصلی(بادی، سایدبار و فوتر) بوردر و بک گراند سفید دادم که متمایز باشه.
توی فهرست مطالب یک خط سمت راست تیتر های فرعی اضافه کردم که از تیتر اصلی جدا شه.
به لینک های فوتر آیکون اضافه کردم. با همون روشی که به لینک های خارجی فاوآیکون اضافه کردم. (اینجا توضیح دادم) متن لینک ها رو هم از فایل Footer.tsx مخفی کردم.

برای اینکه این استایل بهتر روی کار بشینه مجبور شدم فایل renderPage.tsx رو ویرایش کنم و یک تگ والد به عنصر page-header و popover-hint اضافه کنم. چون تفکیک این دوتا جالب نمیشد و باید توی یک بخش قرار می‌گرفتند.

از طرف دیگه نمیخواستم کل المان های موجود در عنصر center ( یعنی متن یادداشت، بک لینک، تگ لیست و کامنت) توی یک بخش قرار بگیرند. میخواستم از هم تفکیک بشه. به خاطر همین لازم بود یک تگ والد برای اونا درنظر بگیرم تا بتونم با هم دیگه سلکتشون کنم و بهشون استایل بدم.

اگر میخوایید از این صفحه بندی و استایل استفاده کنید این مراحل رو انجام بدید:

طبق فایل quartz.layout.ts المان ها رو بچینید. (یا اینکه این فایل را دانلود کرده و جایگزین فایل خودتان کنید)
فایل renderPage.tsx رو دانلود کنید و جایگزین فایل خود در مسیر quartz/components کنید. (یا طبق فایل یک تگ div والد با کلاس page-top اضافه کنید)
فایل ui.scss رو دانلود کنید و توی مسیر quartz/styles قرار بدید.
این کد رو به فایل custom.scss اضافه کنید:

custom.scss

@use "./_ui.scss";
 
// Colors
    :root {
        --bg: #ffffff;
      }
  
    [saved-theme="dark"] {
        --bg: #1a222e;
    }

برای لوگوی سایت، فایل تصویر خودتون رو با اسم avatar.png ذخیره کرده و توی مسیر quartz/static قرار بدید.

بخش دوم: استایل‌ها

استایل های کلی

خلاصه استایل هایی که توی فایل custom.scss اضافه کردم:

عنوان footnote: عنوان پخش پاورقی footnote هست که انگلیسیه. از کدی استفاده کردم که فارسی بشه. این ترفند رو از بلاگ کریستالین برداشتم.
بلوک کد: در حالت پیشفرض حتی اگر طول یک سطر کوتاه باشه باز هم اسکرول محور افقی نمایش داده می شود. با اضافه کردن کد overflow-x: auto اسکرول تنها در صورتی نمایش داده می‌شود که طول سطر طولانی بوده و خارج از بلوک کد باشد. بقیه تنظیمات مربوط به بک‌گراند، فونت و جهت قرار گفتن متن است.
دکمه: یک استایل برای دکمه سفارشی اضافه کردم.
تایپوگرافی: مقداری سایز متن بدنه و هدینگ ها را افزایش دادم. همینطور فاصله بین خطوط.

کالوت

برای تغییر رنگ کالوت ها می تونید فایل quartz/quartz/styles/callouts.scss رو ویرایش کنید. من قبلا آیکون اختصاصی هم اضافه کرده بودم اما تنوع چندانی نداشت. تصمیم گرفتم کالوت هایی بدون آیکون با رنگ های مختلف بسازم. بعد اولش ایموجی اضافه کنم. اینطوری:

👻 شفاف

لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ.

💾 خاکستری

لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ.

⚠️ زرد

لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ.

🔥 نارنجی

لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ.

🚨 قرمز

لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ.

🛡️ آبی

لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ.

🌳 سبز

لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ.

🔮 بنفش

لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ.

💼 قهوه‌ای

لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ.

یکسری دیگه هم بدون عنوان ایجاد کردم برای زمانی که فقط یک باکس رنگی برای متن نیاز دارم.

👻 شفاف

👻 لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ.

💾 خاکستری

💾 لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ.

⚠️ زرد

⚠️ لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ.

🔥 نارنجی

🔥 لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ.

🚨 قرمز

🚨 لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ.

🛡️ آبی

🛡️ لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ.

🌳 سبز

🌳 لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ.

🔮 بنفش

🔮 لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ.

💼 قهوه‌ای

💼 لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ.

برای استفاده از این استایل میتونید کدی که به فایل callouts.scss اضافه کردم رو کپی کنید و توی فایل خودتون قرار بدید.

برای اینکه توی خود ابسیدین هم این کالوت با آیکون و رنگ اختصاصی نمایش داده بشه می تونید از پلاگین Admonition یا Callout Manager استفاده کنید.

چرخش آیکون >

این آیکون در قسمت های مختلف مثل فهرست، اکسپلور و کالوت استفاده شده. جهت این آیکون در حالت بسته باید سمت چپ باشد در حالی که به سمت راست است. برای چرخش آن باید مقدار rotateZ را در فایل های مربوط به هر کدام از منفی90 به مثبت90 تغییر دهید.(+)

فهرست: quartz/components/styles/toc.scss

اکسپلور: quartz/components/styles/explorer.scss

کالوت: quartz/quartz/styles/callouts.scss

به این شکل:

  &.collapsed .fold {
    transform: rotateZ(90deg);
  }

دیاگرام

در کوارتز مثل ابسیدین امکان ساخت دیاگرام وجود داره. به این شکل:

flowchart TD
A([عنوان اصلی])
A --- B([فرعی یک])
A --- C([فرعی دو])
A --- D([فرعی سه])

click A "/"

classDef default fill:#fff,stroke:gray, stroke-width:1px,color:#282828;
linkStyle default stroke:gray,stroke-width:1px;

در سایت mermaid تمامی دستورات برای استفاده از آن توضیح داده شده. کد زیر دیاگرام بالا را نشان می دهد:

```mermaid
flowchart TD
A([عنوان اصلی])
A --- B([فرعی یک])
A --- C([فرعی دو])
A --- D([فرعی سه])
 
click A "/"
 
classDef default fill:#fff,stroke:gray, stroke-width:1px,color:#282828;
linkStyle default stroke:gray,stroke-width:1px;
```

تنظیم استایل دیاگرام در خود اون انجام میشه. دو خط آخر کد بالا مربوط به استایل این دیاگرامه. علاوه براین تنظیمات دیگری هم به فایل custom.scss اضافه کردم:

دایرکشن را روی rtl گذاشتم، چون معمولا از فارسی استفاده می کنم.
بک‌گراند را شفاف کردم، چون بک‌گراند code رو خاکستری کرده بودم، دیاگرام هم خاکستری شده بود.
فونت را روی body font گذاشتم.
آیکون «کپی در کلیپ بورد» را مخفی کردم.

custom.scss

.mermaid {
	direction: rtl !important;
}
 
pre:has(>code.mermaid) {
	background-color: transparent;
	.clipboard-button {
		display: none;
	}
	svg {
		margin: auto;
	}
}
 
.nodeLabel {
	font-family: var(--bodyFont);
}

فاوآیکون لینک‌های خارجی

به بعضی از لینک های خارجی فاوآیکون اضافه کردم:

🔗 نمونه لینک‌ها

normal

github

twitter

google

youtube

aparat

motamem

لینک عادی

گیت هاب

توییتر

گوگل

یوتیوب

آپارات

متمم

اول فایل external-links.scss رو به پوشه quartz\styles اضافه کنید. بعد این کد رو به ابتدای فایل custom.scss اضافه کنید:

@use "./_external-links.scss";

این ایده رو توی سایت quartz.eilleeenz.com دیدم و کدها رو از اینجا برداشتم.

نمای کارتی

این تنظیم استایل جدول رو به حالت کارت تبدیل می‌کنه. مشابه حالتی که تم minimal برای جدول‌های dataview می‌سازه. یک حالت دیگه هم اضافه کردم که باعث میشه کارت‌ها فقط در یک ردیف نمایش داده بشن و بقیه کارت‌ها با اسکرول کردن قابل مشاهده باشن. برای زمانی که تعداد کارت‌ها زیاد باشه این روش مناسب تره.

برای استفاده از این روش اول فایل زیر رو دانلود و در مسیر quartz/styles قرار بدید:

card-view

بعد کد زیر رو به ابتدای فایل custom.scs اضافه کنید.

@use "./_card-view.scss";

حالا می تونید از دو روش برای اعمال این استایل روی فایل‌هاتون استفاده کنید:

1️⃣ اگر میخواهید روی همه جدول‌های موجود در یادداشت اعمال بشن یک پراپرتی با عنوان cssclasses به یادداشت تون اضافه کنید بعد کلاس دلخواه رو وارد کنید. به این شکل:

---
cssclasses: card-g c-3
---

2️⃣ اگر نمی خواهید این استایل روی همه جدول‌ها اعمال بشه می تونید جدول تون رو در تگ div بذارید و کلاس مورد نظر رو براش تعریف کنید. به این شکل:

<div class="card-g c-2">
| class  | description  |
| ------ | ------------ |
| card-g | grid style   |
| card-s | scroll style |
</div>

راهنمای کامل کلاس‌ها رو توی این کالوت توضیح دادم:

📝 راهنمای کلاس‌ها
کلاس های مربوط به حالت گرید

card-g یک نمای کارتی با 4 ستون در ردیف‌های متعدد می‌سازد
c-2 نمایش کارت ها در 2 ستون
c-3 نمایش کارت ها در 3 ستون
c-5 نمایش کارت ها در 5 ستون
c-6 نمایش کارت ها در 6 ستون

کلاس های مربوط به حالت اسکرول

card-s یک نمای کارتی با عرض 150px در یک ردیف میسازد
w100 تنظیم عرض کارت روی 100px
w200 تنظیم عرض کارت روی 200px
w300 تنظیم عرض کارت روی 300px

کلاس های مشترک

nowarp متن را در یک خط نگه داشته و کاراکتر های اضافی را مخفی می‌کند
nowarp2 متن را در دو خط نگه داشته و کاراکتر های اضافی را مخفی می‌کند
c1-1 نسبت تصویر را 1:1 تنظیم می‌کند
c16-1 نسبت تصویر را 16:9 تنظیم می‌کند
c3-4 نسبت تصویر را 3:4 تنظیم می‌کند

💡این کلاس‌ها رو میتویند با هم ترکیب کنید. مثلا من میخوام از حالت گرید استفاده کنم که 3 تا ستون داشته باشه، نسبت تصویر 1:1 باشه و متن هم در دو خط نگه داره. استایل هایی که باید استفاده کنم به این شکله:
---
cssclasses:
  - card-g
  - c-3
  - c1-1
  - nowarp2
---


card-g	یک نمای کارتی با 4 ستون در ردیف‌های متعدد می‌سازد
c-2	نمایش کارت ها در 2 ستون
c-3	نمایش کارت ها در 3 ستون
c-5	نمایش کارت ها در 5 ستون
c-6	نمایش کارت ها در 6 ستون


card-s	یک نمای کارتی با عرض 150px در یک ردیف میسازد
w100	تنظیم عرض کارت روی 100px
w200	تنظیم عرض کارت روی 200px
w300	تنظیم عرض کارت روی 300px


nowarp	متن را در یک خط نگه داشته و کاراکتر های اضافی را مخفی می‌کند
nowarp2	متن را در دو خط نگه داشته و کاراکتر های اضافی را مخفی می‌کند
c1-1	نسبت تصویر را 1:1 تنظیم می‌کند
c16-1	نسبت تصویر را 16:9 تنظیم می‌کند
c3-4	نسبت تصویر را 3:4 تنظیم می‌کند

بخش سوم: امکانات

دکمه‌های شناور

یک مورد جذاب هم در فوتر quartz.eilleeenz.com دیدم که با کلیک کردن روی Random Page یک صفحه تصادفی به کاربر نمایش میده. یک دکمه اسکرول به بالا هم داره. اخیرا این دو مورد رو به صورت دکمه شناور گوشه پایین سایت قرار داده. از اینجا می تونید توضیحات خودش رو مشاهده کنید.

برای اضافه کردنش باید یک کامپوننت جدید بسازیم و استایل و اسکریپتش رو بهش اضافه کنیم. برای این کار کافیه فایل های زیر رو به کوارتز اضافه کنیم. دقیقا در همین مسیری که این فایل ها قرار دارند:

بعد باید این کامپوننت رو به فایل Index.ts اضافه کنیم:

components/index.ts

import FloatingButtons from "./_FloatingButtons"
...
  FloatingButtons,

حالا میتونیم این کامپوننت رو در فایل quartz.layout.ts استفاده کنیم. به این شکل:

quartz.layout.ts

right: [
    Component.FloatingButtons(),
  ],

تصاویر

لایت باکس تصاویر

توی سایت ها معمولا وقتی کاربر روی تصویر کلیک کنه یک لایت باکس باز میشه و تصویر رو با ابعاد بزرگ تر نمایش میده. کوارتز به صورت پیشفرض این قابلیت رو نداره.

یکی از کاربران یک پلاگین نوشته و این قابلیت رو برای کوراتز فراهم کرده. توضیحات کامل و فایل مورد نیاز توی لینک زیر هست:

Quartz Clickable Images Zoom plugin

کاروسل تصاویر

این هم یکی دیگه از قابلیت هایی بود که کوارتز کم داشت. کاروسل تصاویر به این شکل میشه:

توضیحات کامل و فایل ها توی لینک زیر هست:

A Carousel component for Quartz v4.5

⚠️ مشکل نمایش اسلایدهای بعدی
اگر مثل من جهت سایت رو راستچین کرده باشید یعنی طبق تنظیماتی که اینجا گفتم دایرکشن rtl باشه، فقط اسلاید اول رو بهتون نشون میده و بقیه اسلاید ها رو نمایش نمیده. برای حل این مشکل باید فایل carousel.inline.scss رو ادیت کنید.

با اضافه کردن استایل زیر این مشکل حل میشه:
carousel.inline.scss
article .quartz-carousel {
  direction: ltr; // این خط رو اضافه کنید
  }

گالری تصاویر (Grid)

وقتی از چندتا تصویر استفاده میکنم یک گرید اضافه کردم که کنار هم قرار بگیرند. اینطوری:

برای اینکار اول کد زیر رو به فایل custom.scss اضافه کنید:

اگر لایت باکس رو فعال کردید این رو استفاده کنید:

custom.scss

.img-grid {
	display: grid;
	margin-block: 0.5rem;
	grid-column-gap: 0.5rem;
	grid-template-columns: repeat(auto-fit, minmax(0, 1fr));
	align-items: stretch;
}
 
.img-grid .lightbox-wrapper {
	height: 100%;
	display: flex;
	justify-content: center;
	align-items: center;
}
 
.img-grid .lightbox-wrapper .lightbox-image {
	width: 100%;
	height: 100%;
	object-fit: cover;
	margin: 0;
}

اگر لایت باکس رو فعال نکردید این رو استفاده کنید:

custom.scss

.img-grid {
	display: grid;
	margin-block: 0.5rem;
	grid-column-gap: 0.5rem;
	grid-template-columns: repeat(auto-fit, minmax(0, 1fr));
	align-items: stretch;
}
 
.img-grid img {
	object-fit: cover;
	margin: 0 auto;
}

بعد به این شکل از تصاویر داخل فایل مارکدان استفاده کنید:

<div class="img-grid">
  <img src="image1.jpg" alt="Description of image 1"/>
  <img src="image2.jpg" alt="Description of image 2"/>
  <img src="image3.jpg" alt="Description of image 3"/>
</div>

اسم فایل تون رو جایگزین image1.jpg کنید.

کانتنت متا

بخش کانتنت متا که تاریخ و مدت زمان مطالعه رو نشون میده تغییر دادم. در حالت پیشفرض فقط یک تاریخ رو نشون میده که نهایتا میتونید روی تاریخ انتشار یا تاریخ آخرین به‌روزرسانی تنظیمش کنید. من تمایل داشتم علاوه بر تاریخ انتشار، تاریخ آخرین به‌روزرسانی هم برای کاربر قابل مشاهده باشه.

یه مورد دیگه هم نیاز داشتم که وضعیت رشد یادداشت رو نشون بده. طبق روش دیجیتال گاردن از 🌱نهال، 🪴درختچه، 🌳همیشه‌سبز و 🍂زودگذر باید برای مشخص کردن وضعیت یادداشت استفاده کرد.

برای اینکه بتونیم این موارد رو داشته باشیم باید یک کامپوننت جدید بسازیم. کافیه فایل های زیر رو به کوارتز اضافه کنیم. دقیقا در همین مسیری که این فایل ها قرار دارند:

بعد باید این کامپوننت رو به فایل Index.ts معرفی کنیم. به این شکل:

components/index.ts

import Properties from "./_Properties"
...
  Properties,

حالا میتونیم این کامپوننت رو در فایل quartz.layout.ts استفاده کنیم. به این شکل:

quartz.layout.ts

beforeBody: [
    Component.ConditionalRender({
      component: Component.Properties({ showReadingTime: false, showComma: false }),
      condition: (page) => page.fileData.slug !== "index",
    }),
  ],

(این یک مورد شرطی هست که این کامپوننت رو در همه صفحات نمایش میده به جز صفحه index. این رو اضافه کردم چون معمولا توی این صفحه این موارد نباشه بهتره. من مدت زمان مطالعه رو غیر فعال کردم. همینطور ویرگولی که بین اینها قرار میگرفت.)

حالا از پراپرتی های زیر میتونید توی یادداشت تون استفاده کنید:

example.md

---
date: 2025-05-01
lastmod: 2025-06-30
status: 🌱نهال
---

فهرست

بلاگ فرد

تنظیمات سفارشی من برای کوارتز

فهرست

بخش اول: رابط کاربری

بخش دوم: استایل‌ها

استایل های کلی

کالوت

چرخش آیکون >

دیاگرام

فاوآیکون لینک‌های خارجی

نمای کارتی

بخش سوم: امکانات

دکمه‌های شناور

تصاویر

لایت باکس تصاویر

کاروسل تصاویر

گالری تصاویر (Grid)

کانتنت متا

بک‌لینک‌ها

نمای گراف