כתיבת מדריכים ב-Cloud Shell

‫Cloud Shell תומך ביצירה ובהפעלה של הדרכות כדי לעזור למשתמשים להכיר את הפרויקט שלכם במהירות וביעילות.

מדריך הוא קבוצה של הוראות שנכתבות ב-Markdown. ‫Cloud Shell יוצר הדרכות בהקשר מתוך קובצי ה-Markdown האלה על ידי ניתוח הטקסט לשלבים ותתי-שלבים שמוצגים בחלונית במסוף Google Cloud .

מדריך שפועל ב-Cloud Shell

כתיבת מדריכים

ההדרכות כתובות ב-CommonMark Markdown. יש תמיכה בתוספים נוספים של Markdown, וגם בהוראות, שכוללות פונקציונליות מתקדמת כמו הדגשת תכונות והוספה של אייקונים בשורה.

שלבים

כשיוצרים הדרכה, חשוב להשתמש בכותרות כדי לקבוע את המבנה שלה. כדי להגדיר את הכותרת הנכונה, את כותרות השלבים ואת ההוראות הבסיסיות, צריך להשתמש בהיררכיה הבאה:

  • תגי H1 ‏ (#) לכותרת המדריך. בכל הדרכה צריך להיות רק תג H1 אחד.
  • תגי H2 (##) לכותרת של שלב.
  • תגי H3 (###) לכותרת של שלב משנה.

הנה קובץ Markdown לדוגמה שאפשר להשתמש בו כדי ליצור הדרכה:

# First tutorial

## First step

Hello world

### Part 1

Part one instructions.

### Part 2

Part two instructions.

## Conclusion

Done!

הוראות

ההנחיות מאפשרות פונקציונליות מתקדמת כמו הדגשת תכונות והוספה של סמלים בתוך הטקסט.

כדי להוסיף הנחיה, צריך להשתמש בפורמט הבא:

<walkthrough-DIRECTIVE_NAME PARAMETER="PARAMETER_VALUE">
</walkthrough-DIRECTIVE_NAME>

לדוגמה, אם רוצים להשתמש בהוראה editor-open-file ובפרמטר filePath, צריך לכתוב אותם כך:

<walkthrough-editor-open-file filePath="test/hello.md">
</walkthrough-editor-open-file>

רשימת ההנחיות הזמינות מופיעה בחומרי העזר בנושא הנחיות.

הפעלת מדריכים ב-Cloud Shell

יש שתי דרכים להתחיל הדרכה ב-Cloud Shell:

  1. שימוש בפקודה cloudshell launch-tutorial

    מריצים את פקודת cloudshell הבאה בסשן של Cloud Shell כדי להפעיל הדרכה מקובץ Markdown קיים, tutorial.md:

    cloudshell launch-tutorial tutorial.md

    לחלופין, אפשר להשתמש בכינוי teachme על ידי הרצת הפקודה הבאה בסשן Cloud Shell כדי להפעיל הדרכה מקובץ קיים, hello.md:

    teachme hello.md

  2. שימוש באפשרות פתיחה ב-Cloud Shell

    לחלופין, אפשר להשתמש בתכונה פתיחה ב-Cloud Shell כדי להפנות את המשתמשים מאתר, מבלוג או מפרויקט קוד פתוח אל המדריך שלכם שמתארח במאגר Git. התכונה Open in Cloud Shell מאפשרת להשתמש בפרמטר cloudshell_tutorial, שאפשר להוסיף לסוף כתובת ה-URL כדי לציין את המיקום של קובץ ה-Markdown של המקור במאגר. כלומר, קוד ה-Markdown של לחצן שמקושר למדריך ייראה כך:

    [![Open in Cloud Shell](https://gstatic.com/cloudssh/images/open-btn.png)](https://ssh.cloud.google.com/cloudshell/open?cloudshell_git_repo=GIT_REPO_URL&cloudshell_tutorial=PATH_TO_MD_FILE)

השלבים הבאים