Markdown

יום טוב, עמיתים! אחרי מסע ארוך של למידה, כולם רוצים להראות למעסיק את הפירות שלו, ולהראות אותם רק מהצד הטוב והמקצועי, נכון? אני חושב שכן. לכן, בנוסף לפרויקט מתוכנן ומיושם נכון, אנחנו צריכים להיות מסוגלים למסד אותו. המעסיק לא יקרא את כל קוד הפרויקט שלך כדי להבין על מה מדובר ומה כלול בו? במאמר זה, נסכם לבסוף את השניים הקודמים, כלומר: אינטגרציה מתמשכת וכיסוי קוד , ונאפשר לנו להבין על הגיליון "הקדמי" של פרויקט הקוד הפתוח במה השתמשנו בפרויקט שלנו ומה הוא מייצג. היום נדבר איתך על Markdown, נשאל את השאלות האהובות עלינו: "מה זה?" ו"למה זה?", בואו להבין היכן הוא משמש וכיצד לעבוד עם זה. אפילו תהיה דוגמה, אנחנו ניישם אותה בפרויקט הקוד הפתוח שלנו . אז בוא נלך!

מה זה "Markdown"?

מכיוון שאתה ואני מתכנתים, מיד נלך לגוגל ונפתח את הקישור הראשון של ויקי , שאומר: Markdown היא שפת סימון קלת משקל שנוצרה במטרה לכתוב את הטקסט הכי קריא וקל לעריכה, אבל מתאים ל המרה לשפות עבור פרסומים מתקדמים (HTML, Rich Text ואחרים). כאן, למען האמת, אין לי הרבה מה להוסיף, אני חושב שזה הסבר כמעט מושלם.

למה אנחנו צריכים את ה"Markdown" הזה?

למען האמת, זה בעצם לא רע בלעדיו :D אבל בואו נזכור את המטרה שלנו: לכתוב תבנית פרויקט מוכשרת שכבר יש לה Intinuous Integration ויש לה סטטיסטיקות Code Coverage על המשאב Codecov. למה הזכרתי את זה? יתרה מכך, Markdown יאפשר לנו לקחת נתונים ממשאבים אלו ולספק את הנתונים בעצמם, או תגים שיפנו אותנו לאן שאנו צריכים לקבל מידע זה. זה נוח שהכל יהיה בעמוד "שער" אחד, ולא מפוזר במקומות שונים, לא?

איפה משתמשים בו?

כל מי שהעלה אחד מהפרויקטים שלו ל-GitHub לפחות פעם אחת יודע ש-GitHub רוצה בהתמדה להזמין אותך ליצור קובץ README: מהי הסיומת של הקובץ הזה? נכון, בולט מכיר את מרקדאון! כפי שאנו כבר יודעים, קובץ זה מותאם בקלות רבה לפורמטים רבים ומומר ל-HTML שאנו צריכים. אבל בואו ניקח את הזמן ואל נמהר להוסיף אותו מיד ישירות ל-GitHub.

איך עובדים עם זה?

ראשית, כפי שאולי שמתם לב, נוכל להוסיף אותו ישירות ל-GitHub וזה יעבוד! אבל לא תמיד אנחנו צריכים להוסיף אותו לפרויקט אחד בלבד, למשל. או למשל אנחנו רוצים לחשוב יותר על איך אנחנו יוצרים את זה. וכאן GitHub כבר לא מתאים לנו. ובכלל, אנחנו יכולים ליצור קבצי Markdown לא רק במטרה לדחוף אותם ל-GitHub. שנית, נוכל ליצור אותו ישירות דרך IDEA, וזה בדיוק מה שנעשה, אבל לא מיד, מהסיבה שלמה אנחנו צריכים סביבת פיתוח עוצמתית כדי לכתוב קובץ אחד קטן? כאן אני ממליץ לעיין בקטלוג של עורכי קבצי Markdown הקלים, והלא כל כך קלים. לעצמי בחרתי ב-Haroopad , זה מאוד פשוט, נגיש, יש ייצוג מיידי של מה שאתה כותב (גם IDEA עושה), ויש לו רמז תחביר. כך נראה חלון העורך: כאן פתחתי README.md מוכן של אחד הפרויקטים שלי. בצד שמאל דף רמאות, מימין תצוגה, במרכז טקסט. הכל מאוד פרימיטיבי ופשוט. אתה יכול גם לראות תגים, עליהם נדבר בקרוב. מי שבוחר בדרך אחרת של כתיבת קבצים אלו – אל תיבהל, כל מה שיהיה שונה זה הממשק הגרפי. הטקסט, התחביר והתצוגה יישארו ללא שינוי. דוגמה המשימה פשוטה מאוד: כתוב README.md כך שיכיל: מידע על הפרויקט (כולל תגים), מידע על ייבוא ​​הפרויקט, מידע על יישום הפרויקט, מידע על אנשי הקשר של המחבר. הכל מאוד פשוט ופרימיטיבי, כפי שכבר אמרתי. בוא ניגש לעניין.

1. בואו נכתוב כותרת - שם הפרויקט שלנו.

   הכותרת הראשית והגדולה נוצרת באמצעות אופרטור ה-hash " # " ולאחר מכן נכתבת הכותרת. במקרה שלנו:

   # ForJavaRushPublication

2. לאחר מכן נכתוב כותרת מעט קטנה יותר, ונכתוב "מידע על פרויקט". לפני הכותרת הקטנה יותר " # ":

   ## Information

   ואז נכתוב מידע על הפרויקט.

3. בואו נכניס קישורים למאמרים שלנו. זה נעשה בצורה פשוטה מאוד, ואם אתה משתמש ב-Haroopad, פשוט הקלד את דף הצ'יט והתבנית תוכנס בעצמה. התחביר הוא: " [טקסט](כתובת אתר) ";

4. בואו נכניס תגים. בואו נסתכל מקרוב כאן.

   ראשית, בואו נסדר אותם בצורה של שולחן, ליופי. יהיו 2 עמודות ו-2 עמודות. התחביר ייראה בערך כך:

   והתוצאה תהיה כזו:

   לאחר מכן, נכניס היפר-קישורים לתגים שלנו, אבל היכן נוכל להשיג אותם? הראיתי במאמר הקודם היכן ניתן להשיג Codecov, אך לא ציינתי איזה מהם להשיג. מכיוון שיש לנו קובץ Markdown, אנחנו צריכים גם תג Markdown:

   פשוט העתק אותו והדבק אותו בעמודה ב-Markdown שלנו. אבל אל תשכח ש-Codecov הופיע בסניף JaCoCo, אבל לא במאסטר, אז תצטרך לתקן את זה ידנית. Travis CI Badge נלקח ישירות מול שם הפרויקט, כאשר יומן הבנייה הוא:

   אנחנו בוחרים את התג, ואז חלון ההגדרות קופץ:

   אנחנו בהחלט בוחרים ב-Markdown ובסניף שאתה צריך. אני אעשה README.md לשני סניפים, והם יהיו מעט שונים, כי עדיין לא הטמעתי את Codecov בסניף המאסטר.




5. בוא נכתוב מידע על איך לייבא או לשכפל את הפרויקט הזה. אני לא אסביר איך לעשות את זה, אבל אתה יכול לקרוא את זה ב-README.md שלי. נכתוב על הטכנולוגיות בהן השתמשנו בפרויקט שלנו, ונציב קישורים אליהן. ובכל זאת, מדובר בפרויקט חינוכי. ובכן, בוא נרשום את פרטי הקשר.




6. ה-Markdown שלנו מוכן. כל שעלינו לעשות הוא להוסיף אותו לפרויקט שלנו וסיימנו. אבל לא בבת אחת! בואו נפתח את ה-IDEA שלנו, ובפלאגינים אנו בודקים שיש לכם תמיכת Markdown:

   יש לי Ultimate IDEA, אז יש לי הכל, ייתכן שהפלאגין שלך לא מותקן כברירת מחדל, אבל כשאתה יוצר קובץ עם סיומת md, אתה אמור להתבקש להוריד אותו. הורד והפעל מחדש את IDEA שלך.




7. לאחר ייבוא ​​ה-Markdown שכתבנו, פתחו אותו דרך IDEA וערכו אותו במידת הצורך. כך זה נראה דרך IDEA:

   אנחנו כן דוחפים. ואז אנו רואים שכאשר פותחים פרויקט, המידע עליו נטען מיד, זה ה-README.md שלנו:

   כעת, כשנלחץ על התג, נוכל לקפוץ ישר למכלול הפרויקט ולראות מה יש לנו שם ואיך.




8. אני אעשה את אותו הדבר עבור סניף JaCoCo כדי להדגים את תג Codecov, כי עדיין אין לנו README.md בו. כתוצאה מכך, יש לנו כעת שני תגים:

   Codecov מציג את אחוז כיסוי הקוד, והוא יכול גם להפנות אותנו לדף Codecov ולהציג דוח כיסוי קוד מפורט.

קישורים שימושיים

• מה וויקי מספרת לנו על Markdown;
• מדריך עורכי Markdown ;
• Haroopad שאני ממליץ עליו;
• אודות Markdown באתר JetBrains ;
• Markdown Navigator באותו JetBrains;
• תגים וכל מה שקשור אליהם. כאן אתה יכול לבחור את הסגנון של כל תג ולהתאים אותו לעצמך;
• כיצד לשדרג את פרויקט הקוד הפתוח שלך? מאמר זה יענה גם על ;
• מאמר קודם

בואו נסכם את סדרת המאמרים שלי

1. בדקנו מה זה CI, בשביל מה זה ואיך להשתמש בו במאמר הראשון על שילוב מתמשך ;
2. שיחקנו עם CC והבנו מה זה ולמה זה נחוץ במאמר השני על Code Coverage ;
3. ובמאמר זה הסתכלנו על מה זה Markdown, למה זה נחוץ וכיצד להשתמש בו ביעילות.

תודה לכולכם שקראתם את שלושת המאמרים הארוכים האלה, אני מקווה שהם היו שימושיים. ייתכנו טעויות והשמטות בטקסט. תודה לכולכם על תשומת הלב!