תיעוד Obsidian מבוסס על הנחיות הסגנון המפורטות בדף זה. הנחיות אלו מבוססות על שיטות עבודה מומלצות בתעשייה, בפרט [מדריך הסגנון לתיעוד מפתחים של Google](https://developers.google.com/style) ו-[מדריך הסגנון של Microsoft](https://learn.microsoft.com/en-us/style-guide/). במקרים שאינם מכוסים להלן, יש להתייחס למדריכים החיצוניים הללו כמקורות משניים.
> [!tip]- תרומה
> רוב התיעוד נוצר לפני שמדריך סגנון זה נכתב.
>
> אם מצאת הפרות כלשהן של מדריך סגנון זה, אנא [צור issue](https://github.com/obsidianmd/obsidian-docs/issues/new) ושלח pull request ל-[obsidianmd/obsidian-docs](https://github.com/obsidianmd/obsidian-docs).
## מינוח ודקדוק
### סגנון שפה
עבור התיעוד שלנו באנגלית, מומלץ להשתמש ב-[Global English](https://docs.openedx.org/en/latest/documentors/references/doc_english_writing.html) כדי לשרת טוב יותר את הקהל העולמי שלנו ולסייע ב[[#תרגומים]]. משמעות הדבר:
- הימנעות מביטויים אידיומטיים וביטויים ספציפיים תרבותית
- שימוש בצורה פעילה ובמבנה משפטים ישיר
- העדפת מילים פשוטות ונפוצות על פני מינוח מורכב
- היו מפורשים ולא מרומזים
- עבור מוסכמות כתיב, השתמשו באנגלית אמריקאית (למשל, 'organize' ולא 'organise').
### מונחים
- העדיפו "keyboard shortcut" על פני "hotkey". השתמשו ב-Hotkey כאשר מתייחסים לתכונה הספציפית.
- העדיפו "the Obsidian app" בנייד, ו-"the Obsidian application" בשולחן העבודה.
- העדיפו "sync" או "syncing" על פני "synchronise" או "synchronising".
- העדיפו "search term" על פני "search query".
- העדיפו "heading" על פני "header" כאשר מתייחסים לטקסט שמציג קטע.
- העדיפו "maximum" על פני "max" ו-"minimum" על פני "min".
### שמות מוצרים
שמות מוצרי Obsidian מתחילים ב-"Obsidian", למשל "Obsidian Publish" ו-"Obsidian Sync".
אם פסקה הופכת לחזרתית מדי, ניתן להשתמש בצורה המקוצרת באזכורים הבאים.
לדוגמה:
_כדי לאפשר תצורה ספציפית למכשיר, Obsidian Sync לא מסנכרן את ההגדרות שלו עצמו. עליכם להגדיר את Sync עבור כל אחד מהמכשירים שלכם._
### ממשק משתמש ואינטראקציות
- השתמשו ב**מודגש** לציון טקסט כפתורים
- העדיפו "select" על פני "tap" או "click".
- עבור הוראות ספציפיות לנייד, "tap" מקובל בתיאור אינטראקציות מגע מכיוון ש-"click" אינו זמין.
- העדיפו "sidebar" על פני "side bar".
- העדיפו "perform" על פני "invoke" ו-"execute" כאשר מתייחסים לפקודות או פעולות.
כאשר מתייחסים לאינטראקציות ממשק מרובות ברצף, השתמשו בסמל ← (U+2192). לדוגמה, "**[[הגדרות]] ← תוספים קהילתיים**".
### הערות, קבצים ותיקיות
- השתמשו ב"הערה" כאשר מתייחסים לקובץ Markdown בכספת.
- השתמשו ב"קובץ" כאשר מתייחסים לסיומות קובץ אחרות מ-Markdown.
- העדיפו "שם הפתק" על פני "כותרת הפתק".
- העדיפו "הערה פעילה" על פני "הערה נוכחית".
- העדיפו "תיקייה" על פני "ספרייה".
- העדיפו "סוג קובץ" על פני "פורמט קובץ", אלא אם מתייחסים באופן ספציפי לפורמט הנתונים של תוכן הקובץ.
כאשר עוברים בין הערות, השתמשו ב"פתח" אם היעד מוסתר, ו"עבור" אם הערת המקור והיעד שתיהן פתוחות בפיצולים נפרדים.
### תיעוד הפניות להגדרות
כאשר ניתן, כל הגדרה צריכה להיות מתועדת בתוך Obsidian באמצעות טקסט תיאורי. הימנעו מתיעוד הגדרה ספציפית בעזרת Obsidian אלא אם:
- היא דורשת ידע מעמיק יותר לגבי אופן השימוש ומתי להשתמש בה.
- היא נפוצה בשימוש שגוי או בשאלות.
- היא משנה *באופן דרמטי* את חוויית המשתמש.
שקלו להשתמש בתיבת הערה מסוג עצה אם ברצונכם להפנות תשומת לב להגדרה ספציפית.
### מונחי כיוון
הוסיפו מקף למונחי כיוון כאשר משתמשים בהם כתארים. הימנעו ממקף כאשר הכיוון משמש כשם עצם.
**מומלץ:**
- בחרו **[[הגדרות]]** בפינה השמאלית-תחתונה.
- בחרו **[[הגדרות]]** בתחתית השמאלית.
**לא מומלץ:**
- בחרו **[[הגדרות]]** בפינה שמאלית תחתונה.
- בחרו **[[הגדרות]]** בשמאלית-תחתונה.
העדיפו "upper-left" ו-"upper-right" על פני "top-left" ו-"top-right".
אל תציינו כיוון כאשר מתייחסים להגדרות. מיקום פקד ההגדרות תלוי במכשיר.
**מומלץ:**
- ליד **Pick remote vault**, בחרו **Choose**.
**לא מומלץ:**
- מימין ל-**Pick remote vault**, בחרו **Choose**.
בתיאור כיוון אנכי באלמנטי ממשק, השתמשו ב"מעל" ו"מתחת" ליחסים מרחביים. הימנעו מ"למעלה" ו"למטה" מכיוון שהם דו-משמעיים בהקשרים שונים.
**מומלץ:**
- תיבת החיפוש מופיעה מעל רשימת הקבצים.
- אפשרויות נוספות זמינות מתחת.
**לא מומלץ:**
- תיבת החיפוש נמצאת למעלה מרשימת הקבצים.
- עוד אפשרויות למטה.
### הוראות
השתמשו בציווי לשמות מדריכים, כותרות קטעים והוראות שלב-אחר-שלב. צורת הציווי תמציתית ומוכוונת פעולה, מה שנוח יותר למשתמשים העוקבים אחר הוראות.
- העדיפו "הגדר" על פני "הגדרה של"
- העדיפו "העבר קובץ" על פני "העברת קובץ"
- העדיפו "ייבא את ההערות שלך" על פני "ייבוא ההערות שלך"
### אותיות גדולות במשפט
העדיפו *sentence case* על פני *title case* עבור כותרות, כפתורים וכותרי עמודים. כאשר מתייחסים לאלמנטי ממשק, תמיד התאימו לרישום שמופיע בממשק.
**מומלץ:**
- How Obsidian stores data
**לא מומלץ:**
- How Obsidian Stores Data
### דוגמאות
העדיפו דוגמאות מציאותיות על פני מונחי חסרי משמעות.
**מומלץ:**
- `task:(call OR schedule)`
**לא מומלץ:**
- `task:(foo OR bar)`
### שמות מקשים וקיצורי מקלדת
כאשר מתייחסים למקשי מקלדת וקיצורים, השתמשו בסימון עקבי.
**שמות מקשים בודדים:**
כאשר מתייחסים לתו במקלדת לפי שמו, הוסיפו את התו בסוגריים מיד אחרי השם.
**מומלץ:**
- לחצו על מקש המקף (-) כדי להוסיף קו.
- השתמשו בסימן השאלה (?) כדי לחפש.
**לא מומלץ:**
- לחצו על מקש המקף כדי להוסיף קו.
- השתמשו ב-? כדי לחפש.
- הוסיפו `-` לפני המילה.
**קיצורי מקלדת:**
עצבו קיצורי מקלדת ללא רווחים סביב סימן הפלוס. כאשר קיצור שונה בין מערכות הפעלה, ציינו את שתיהן.
**מומלץ:**
- לחצו `Ctrl+Z` (Windows) או `Command+Z` (macOS) כדי לבטל.
- לחצו `Escape` כדי לסגור חלון זה.
- השתמשו ב-`Tab` כדי לעבור בין שדות.
**לא מומלץ:**
- לחצו `Cmd+Z` כדי לבטל.
- לחצו `Ctrl + Z` (עם רווחים) כדי לבטל.
- לחצו `Ctrl/Cmd+Z` כדי לבטל.
עבור קיצורים זהים בכל הפלטפורמות, אין צורך לציין את מערכת ההפעלה. אם אינכם בטוחים האם קיצור שונה בין פלטפורמות, ציינו את מערכת ההפעלה למען הזהירות. Windows ו-Linux בדרך כלל משתמשים באותם קיצורים.
### Markdown
השתמשו בשורות ריקות בין בלוקי Markdown:
**מומלץ:**
```md
# כותרת 1
זהו קטע.
1. פריט ראשון
2. פריט שני
3. פריט שלישי
```
**לא מומלץ:**
```md
# כותרת 1
זהו קטע.
1. פריט ראשון
2. פריט שני
3. פריט שלישי
```
**קו מפריד ארוך ברשימות:**
השתמשו בקו מפריד ארוך (—) כדי להפריד בין מונחים מודגשים לתיאוריהם ברשימות תבליטים. אל תשתמשו בקו מפריד ארוך ברשימות מקוננות פשוטות עם קישורים.
**מומלץ:**
- **תפריט תצוגה** — צור, ערוך ועבור בין תצוגות.
- **חשב ערכים** — הוסף מחירים, חשב סכומים או בצע פעולות מתמטיות.
**לא מומלץ:**
- [[יצירת base]] — למד כיצד ליצור ולהטמיע base.
### תמונות
השתמשו ב"**רוחב** x **גובה** פיקסלים" לתיאור מימדי תמונה או מסך.
**דוגמה:**
מימדי תמונה מומלצים: 1920 x 1080 פיקסלים.
## מבנה מידע
### סוגי תיבות הערה
השתמשו בתיבות הערה באופן אסטרטגי להדגשת סוגי מידע ספציפיים:
**עצה** (`[!tip]-`) - עצות מעשיות או שיטות עבודה מומלצות המשפרות את זרימת העבודה של המשתמש. השתמשו עבור קיצורי דרך, פתרונות עוקפים או מידע שאינו הכרחי אך שימושי. תיבות הערה אלו מתחילות מצומצמות.
**מידע** (`[!info]+`) - הקשר נוסף, מידע רקע או הבהרות. השתמשו כאשר מידע מוסיף הבנה אך אינו נדרש להשלמת משימה. תיבות הערה אלו מתחילות פתוחות.
**אזהרה** (`[!warning]+`) - אזהרות חשובות המונעות אובדן נתונים, שגיאות או תוצאות לא רצויות. השתמשו באופן מצומצם למצבים מסוכנים באמת. תיבות הערה אלו לעולם לא צריכות להיות מצומצמות.
**דוגמה** (`[!example]-`) - הערות שוליים כלליות או פרטים משלימים. השתמשו עבור מידע צדדי שחלק מהמשתמשים עשויים למצוא רלוונטי. תיבות הערה אלו מתחילות מצומצמות.
**דוגמאות:**
```md
> [!tip]- השתמשו בקיצורי מקלדת
> ניתן להאיץ את זרימת העבודה על ידי שינון הקיצורים הנפוצים ביותר.
> [!info]+ זהו תוסף בתשלום
> תכונה זו דורשת מנוי בתשלום לשימוש.
> [!warning]+ פעולה זו אינה ניתנת לביטול
> מחיקת כספת היא לצמיתות. שקלו לייצא את ההערות שלכם תחילה.
> [!example]- שימוש מתקדם
> ניתן גם להגדיר הגדרה זו דרך תפריט הגרף.
```
### רשימות מול טקסט רצוף
השתמשו ברשימות כאשר מציגים פריטים נפרדים שאין להם קשרים רציפים או סיבתיים חזקים. השתמשו בטקסט רצוף ופסקאות כאשר פריטים בונים זה על זה, דורשים הסבר או נהנים מזרימה סיפורית.
**השתמשו ברשימה עבור:**
- קבוצה של תכונות לא קשורות
- דרישות התקנה
- אפשרויות תצורה
- שלבי פתרון בעיות
**השתמשו בטקסט רצוף עבור:**
- הסברים על אופן הפעולה של דברים
- זרימות עבודה עם תלויות
- סקירות מושגיות
- הנחיות הדורשות הקשר
### טבלאות
השתמשו בטבלאות להשוואת תכונות, גרסאות או נקודות נתונים קשורות כאשר יישור מסייע להבנה. הימנעו מטבלאות עבור רשימות פשוטות או נתונים בעמודה אחת.
**מקרה שימוש טוב:**
| תכונה | נייד | שולחן עבודה |
|--------|------|-------------|
| סינכרון | כן | כן |
| תוספים | לא | כן |
| ערכות נושא | מוגבל | מלא |
### הפניות צולבות
השתמשו בקישורי ויקי פנימיים (`[[שם הערה]]`) בשפע כדי לעזור למשתמשים לנווט בנושאים קשורים. עם זאת, הימנעו מקישור יתר:
- אל תקשרו את אותו מונח מספר פעמים בעמוד אחד
- קשרו רק כאשר העמוד המקושר מספק הקשר משמעותי נוסף
- השתמשו בטקסט קישור תיאורי כשמועיל: `[[שם הערה#קטע|טקסט תיאורי]]`
**דוגמה:**
אזכור ראשון: "למדו על [[מבוא ל-Obsidian Sync|Obsidian Sync]] כדי לשמור על הכספת שלכם מעודכנת בין מכשירים."
אזכור מאוחר יותר: "ניתן להגדיר את Sync עבור כל מכשיר בנפרד."
### תוכן ספציפי לפלטפורמה
בעת תיעוד תכונות שנבדלות בין פלטפורמות, השתמשו בכותרות קטעים לארגון התוכן.
השתמשו ב-`שולחן עבודה` ו-`נייד` ככותרות משנה להפרדת הוראות או תכונות ספציפיות לפלטפורמה.
**מומלץ:**
```md
## התאמה אישית של סרגל הכלים
### שולחן עבודה
בגרסת שולחן העבודה, ניתן להתאים אישית את סרגל הכלים כדלקמן:
- סדרו מחדש את סדר פעולות סרגל הכלים על ידי גרירה ושחרור של הסמלים.
- כדי להסתיר פעולות ספציפיות, לחצו לחיצה ימנית על שטח ריק ובטלו את הסימון של הפעולות שברצונכם להסתיר.
### נייד
בגרסת הנייד, ניתן להתאים אישית את סרגל הכלים דרך ההגדרות:
1. פתחו את **[[הגדרות]]**.
2. נווטו אל **מראה חיצוני**.
3. לחצו על **לנהל** תחת **תצורת סרט**.
```
> [!info]+ מתי ליצור קטעים?
> צרו קטעים נפרדים רק אם התוכן שונה באופן משמעותי. אם ההוראות דומות ברובן עם שונויות קלות, השתמשו בהערות בתוך השורה במקום.
## סמלים ותמונות
כללו סמלים ותמונות כאשר הם מקלים על הסבר דברים שקשה לתאר במילים, או כאשר עליכם להציג חלקים חשובים באפליקציית Obsidian. ניתן לשמור תמונות בתיקיית `Attachments`.
- התמונה צריכה להקל על הבנת הטקסט שמלווה אותה.
**דוגמה**: לאחר הפעלה, תוסף [[ספירת מילים]] ייצור ערך חדש בשורת המצב התחתונה.
![[Style-guide-zoomed-example.png#interface|300]]
- תמונות צריכות להיות בפורמט `.png` או `.svg`.
- אם תמונה נראית גדולה מדי בהערה, הקטינו אותה מחוץ ל-Obsidian, או התאימו את ממדיה כפי שמוסבר ב[[הטמעת קבצים#הטמעת תמונה בהערה|הטמעת תמונה בהערה]].
- במקרים נדירים, ייתכן שתרצו למקם תמונות גדולות או מורכבות במיוחד ב[[ציטוטים#תיבות הערה מתקפלות|תיבת הערה מקופלת]].
- עבור חלונות קופצים או מודלים, התמונה צריכה להציג את חלון אפליקציית Obsidian בשלמותו.
![[Style-guide-modal-example.png#interface]]
### סמלים
ניתן להשתמש בסמלי [Lucide](https://lucide.dev/icons/) וסמלי Obsidian מותאמים אישית לצד אלמנטים מפורטים כדי לספק ייצוג חזותי של תכונה.
**דוגמה:** בסרגל הכלים בצד שמאל, בחרו **צור קנבס חדש** ![[lucide-layout-dashboard.svg#icon]] כדי ליצור קנבס באותה תיקייה כמו הקובץ הפעיל.
**הנחיות לסמלים**
- אחסנו סמלים בתיקיית `Attachments/icons`.
- הוסיפו את הקידומת `lucide-` לפני שם סמל Lucide.
- הוסיפו את הקידומת `obsidian-icon-` לפני שם סמל Obsidian.
**דוגמה:** הסמל ליצירת קנבס חדש צריך להיקרא `lucide-layout-dashboard`.
- השתמשו בגרסת ה-SVG של הסמלים הזמינים.
- סמלים צריכים להיות ברוחב `18` פיקסלים, גובה `18` פיקסלים ועובי קו של `1.5`. ניתן להתאים הגדרות אלו בנתוני ה-SVG.
> [!info]- התאמת גודל ועובי קו ב-SVG
> ```html
> <svg xmlns="http://www.w3.org/2000/svg" width="WIDTH" height="HEIGHT" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="STROKE-WIDTH" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-layout-dashboard"><rect width="7" height="9" x="3" y="3" rx="1"/><rect width="7" height="5" x="14" y="3" rx="1"/><rect width="7" height="9" x="14" y="12" rx="1"/><rect width="7" height="5" x="3" y="16" rx="1"/></svg>
>```
- השתמשו בעוגן `icon` בתמונות מוטמעות, כדי לכוונן את המרווח סביב הסמל כך שיתיישר בצורה מסודרת עם הטקסט בסביבתו.
- סמלים צריכים להיות מוקפים בסוגריים. ![[lucide-cog.svg#icon]]
**דוגמה**: `![[lucide-cog.svg#icon]]`
### תגי עוגן לתמונות
תגי עוגן לתמונות זמינים להוספת שינויים דקורטיביים לתמונות מוטמעות.
> [!warning] אזהרת תצוגה מקדימה חיה
> תגי עוגן הסמלים לא יוצגו כראוי ב**תצוגה מקדימה חיה.** השתמשו ב**תצוגת קריאה** כדי לאשר שתג העוגן הוחל.
**סמל**
`![[lucide-menu.svg#icon]]`
תג עוגן הסמל מבטיח יישור אנכי נכון לסמלים המשמשים לציון אלמנטי ממשק.
סמל התפריט הראשון משתמש בתג עוגן ![[lucide-menu.svg#icon]], בעוד שסמל התפריט השני ( ![[lucide-menu.svg]] ) אינו משתמש.
**ממשק**
`![[Vault picker.png#interface]]`
תג עוגן הממשק מוסיף צל קופסה דקורטיבי סביב התמונה. בתמונה הראשונה, תג עוגן הממשק מוחל.
![[Vault picker.png#interface]]
לעומת זאת, התמונה השנייה אינה כוללת עוגן ממשק.
![[Vault picker.png]]
**מתאר**
`![[Backlinks.png#outline]]`
תג עוגן המתאר מוסיף גבול עדין סביב התמונה. בתמונה הראשונה, תג עוגן המתאר מוחל.
> [!tip] שימו לב לפינה השמאלית-תחתונה של התמונה כדי לראות את ההבדל.
![[Backlinks.png#outline]]
התמונה השנייה חסרה את תג עוגן המתאר.
![[Backlinks.png]]
### אופטימיזציה
תמונות מאטות את זמן הטעינה של העמוד ותופסות שטח אחסון יקר ב-[[מבוא ל-Obsidian Publish|Publish]]. אופטימיזציה של תמונות מאפשרת הקטנת גודל הקובץ תוך שמירה על השלמות החזותית של התמונה.
יש לבצע אופטימיזציה הן לתמונות והן לסמלים.
> [!info] כלים לאופטימיזציה של תמונות
> הנה כמה תוכנות מומלצות להקטנת גודל התמונות שלכם.
> - **Windows:** [FileOptimizer](https://sourceforge.net/projects/nikkhokkho/)
> - **macOS:** [ImageOptim](https://imageoptim.com/)
> - **Linux/Unix** [Trimage](https://trimage.org)
>
> אנו ממליצים על שיעור אופטימיזציה של 65-75%.
## פריסה
### קישורים שבורים
לפני שליחת ה-Pull Request שלכם, אנא בדקו אם ישנם קישורים שבורים בתיעוד של התרגום שאתם עובדים עליו, ותקנו אותם. קישורים שבורים יכולים להתרחש באופן טבעי עם הזמן, כך שאימות הדיוק שלהם עוזר לשמור על איכות התיעוד.
ניתן לבדוק קישורים שבורים באמצעות [[תוספים קהילתיים]] או כלים הזמינים ב-IDE שלכם.
### תיאורים
תיעוד זה נערך ב-GitHub ומאורח באינטרנט באמצעות [[מבוא ל-Obsidian Publish|Obsidian Publish]], הכולל [[תצוגות מקדימות של קישורים ברשתות חברתיות#תיאור|תיאורים]] לכרטיסים חברתיים ואלמנטי [[SEO]] אחרים.
אם העמוד שאתם עובדים עליו אינו כולל [[מאפיינים|מאפיין]] `description`, אנא הוסיפו אחד. התיאור צריך להכיל 150 תווים או פחות ולספק סיכום אובייקטיבי של תוכן העמוד.
**טוב**: Learn to create templates that capture and organize web page metadata automatically with Web Clipper.
**ניתן לשפר**: Learn how to create templates that automatically capture and organize metadata from web pages with Web Clipper.
### כיוונים
בעת כתיבה או שכתוב של [[#הוראות]] כיצד לבצע פעולה בתוך האפליקציה, הקפידו לכלול שלבים הן עבור גרסת הנייד והן עבור גרסת שולחן העבודה.
אם אין לכם גישה למכשיר נייד או שולחן עבודה, אנא ציינו זאת בעת שליחת ה-Pull Request שלכם.
## תרגומים
תרגמו את מלוא התוכן בעת השלמת תרגום. זה כולל אך אינו מוגבל ל:
- שמות הערות
- שמות תיקיות
- כינויים
- שמות קבצים מצורפים
- טקסט קישור חלופי