مارک داون

روز بخیر، همکاران! پس از یک سفر طولانی یادگیری، همه می خواهند میوه های خود را به کارفرما نشان دهند و آنها را فقط از بهترین و حرفه ای نشان دهند، درست است؟ فکر می کنم بله. بنابراین علاوه بر اینکه یک پروژه به درستی طراحی و اجرا شده است، باید بتوانیم آن را رسمی کنیم. کارفرما تمام کد پروژه شما را نمی خواند تا بفهمد درباره چیست و چه چیزی در آن گنجانده شده است؟ در این مقاله، ما در نهایت دو مورد قبلی را خلاصه می‌کنیم، یعنی: یکپارچه‌سازی مداوم و پوشش کد ، و اجازه می‌دهیم در برگه «جلو» پروژه منبع باز بفهمیم که در پروژه خود از چه چیزی استفاده کرده‌ایم و چه چیزی را نشان می‌دهد. امروز ما در مورد Markdown با شما صحبت خواهیم کرد، سوالات مورد علاقه خود را بپرسیم: "این چیست؟" و "چرا این است؟"، بیایید بفهمیم که کجا استفاده می شود و چگونه با آن کار کنیم. حتی یک مثال وجود خواهد داشت، ما آن را در پروژه منبع باز خود پیاده سازی خواهیم کرد . پس بزن بریم!

"Markdown" چیست؟

از آنجایی که من و شما برنامه نویس هستیم، بلافاصله به گوگل می رویم و اولین پیوند ویکی را باز می کنیم که می گوید: Markdown یک زبان نشانه گذاری سبک است که با هدف نوشتن خواناترین و آسان ترین متن ایجاد شده است، اما مناسب برای تبدیل به زبان برای انتشارات پیشرفته (HTML، متن غنی و غیره). در اینجا، صادقانه بگویم، چیز زیادی برای اضافه کردن ندارم، فکر می کنم این یک توضیح تقریباً کامل است.

چرا ما به این "Markdown" نیاز داریم؟

صادقانه بگویم، در واقع بدون آن بد نیست :D اما بیایید هدف خود را به خاطر بسپاریم: نوشتن یک الگوی پروژه شایسته که قبلاً یکپارچه سازی مداوم داشته باشد و آمار پوشش کد را در منبع Codecov داشته باشد. چرا به این موضوع اشاره کردم؟ علاوه بر این، Markdown به ما این امکان را می‌دهد که داده‌ها را از این منابع بگیریم و خود داده‌ها یا نشان‌هایی را ارائه کنیم که ما را به جایی که باید این اطلاعات را دریافت کنیم هدایت می‌کند. راحت است که همه چیز را در یک صفحه "عنوان" داشته باشید، نه اینکه در مکان های مختلف پراکنده شود، اینطور نیست؟

کجا استفاده می شود؟

هر کسی که حداقل یک بار پروژه خود را در GitHub آپلود کرده باشد، می داند که GitHub دائماً می خواهد از شما دعوت کند تا یک فایل README ایجاد کنید: پسوند این فایل چیست؟ درست است، بولت مارکدان را می شناسد! همانطور که می دانیم، این فایل به راحتی با بسیاری از فرمت ها تنظیم شده و به HTML مورد نیاز ما تبدیل می شود. اما بیایید وقت خود را صرف کنیم و عجله نکنیم که بلافاصله آن را مستقیماً به GitHub اضافه کنیم.

چگونه با آن کار کنیم؟

اول، همانطور که ممکن است متوجه شده باشید، ما می توانیم آن را مستقیماً به GitHub اضافه کنیم و کار خواهد کرد! اما برای مثال، همیشه نیازی نیست که آن را فقط به یک پروژه اضافه کنیم. یا به عنوان مثال می خواهیم بیشتر در مورد نحوه ایجاد آن فکر کنیم. و در اینجا GitHub دیگر برای ما مناسب نیست. و به طور کلی، ما می‌توانیم فایل‌های Markdown را نه تنها با هدف فشار دادن آنها به GitHub ایجاد کنیم. ثانیاً، ما می‌توانیم آن را مستقیماً از طریق IDEA ایجاد کنیم، که دقیقاً همان کاری است که انجام خواهیم داد، اما نه بلافاصله، به این دلیل که چرا برای نوشتن یک فایل کوچک به یک محیط توسعه قدرتمند نیاز داریم؟ در اینجا توصیه می کنم فهرست ویرایشگرهای فایل Markdown آسان و نه چندان آسان را مرور کنید. برای خودم، Haroopad را انتخاب کردم ، بسیار ساده، در دسترس است، نمایشی فوری از آنچه شما می نویسید دارد (IDEA نیز انجام می دهد)، و یک اشاره نحوی دارد. پنجره ویرایشگر به این صورت است: در اینجا من یک README.md آماده یکی از پروژه هایم را باز کردم. در سمت چپ یک برگه تقلب، در سمت راست یک نمایشگر، در مرکز متن است. همه چیز بسیار ابتدایی و ساده است. همچنین می توانید نشان هایی را مشاهده کنید که به زودی در مورد آنها صحبت خواهیم کرد. کسانی که روش متفاوتی را برای نوشتن این فایل ها انتخاب می کنند - نگران نباشند، تنها چیزی که متفاوت خواهد بود رابط گرافیکی است. متن، نحو و نمایش بدون تغییر باقی خواهند ماند. مثال کار بسیار ساده است: README.md را بنویسید تا حاوی: اطلاعات مربوط به پروژه (از جمله نشان ها)، اطلاعات مربوط به واردات پروژه، اطلاعات مربوط به اجرای پروژه، اطلاعاتی در مورد مخاطبین نویسنده باشد. همانطور که قبلاً گفتم همه چیز بسیار ساده و ابتدایی است. بریم به کسب و کار برسیم.

1. بیایید یک عنوان بنویسیم - نام پروژه ما.

   عنوان اصلی و بزرگترین با استفاده از عملگر هش " # " ایجاد می شود و سپس عنوان نوشته می شود. در مورد ما:

   # ForJavaRushPublication

2. سپس یک عنوان کوچکتر می نویسیم و "اطلاعات پروژه" را می نویسیم. قبل از هدر کوچکتر " # " بیشتر آمده است:

   ## Information

   و سپس اطلاعاتی در مورد پروژه می نویسیم.

3. بیایید پیوندهایی به مقالات خود درج کنیم. این کار بسیار ساده انجام می شود و اگر از هاروپد استفاده می کنید، فقط برگه تقلب را تایپ کنید و قالب خودش درج می شود. نحو عبارت است از: " [text](url) ";

4. بیایید نشان ها را وارد کنیم. بیایید نگاهی دقیق تر به اینجا بیاندازیم.

   ابتدا برای زیبایی آنها را به صورت میز بچینیم. 2 ستون و 2 ستون وجود خواهد داشت. سینتکس چیزی شبیه به این خواهد بود:

   و نتیجه به این صورت خواهد بود:

   در مرحله بعد، ما لینک هایی را به نشان های خود درج می کنیم، اما از کجا می توانیم آنها را دریافت کنیم؟ من در مقاله قبلی نشان دادم از کجا باید Codecov را تهیه کرد، اما اشاره نکردم که کدام یک را تهیه کنم. از آنجایی که ما یک فایل Markdown داریم، به یک نشان Markdown نیز نیاز داریم:

   فقط آن را کپی کرده و در ستونی در Markdown ما قرار دهید. اما فراموش نکنید که Codecov در شعبه JaCoCo ظاهر شده است، اما نه در Master، بنابراین باید آن را به صورت دستی اصلاح کنید. نشان Travis CI دقیقاً در مقابل نام پروژه گرفته می شود، جایی که گزارش ساخت عبارت است از:

   ما نشان را انتخاب می کنیم و سپس پنجره تنظیمات ظاهر می شود:

   ما قطعا 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 ;
• هاروپاد که من توصیه می کنم.
• درباره Markdown در وب سایت JetBrains ;
• Markdown Navigator در همان JetBrains.
• نشان ها و همه چیز در مورد آنها. در اینجا می توانید سبک هر نشان را انتخاب کنید و آن را برای خود سفارشی کنید.
• چگونه پروژه منبع باز خود را ارتقا دهیم؟ این مقاله همچنین پاسخ خواهد داد ؛
• مقاله قبلی

بیایید مجموعه مقالات من را خلاصه کنیم

1. ما در مقاله اول در مورد Continuous Integration به این موضوع پرداختیم که CI چیست، چه کاربردی دارد و چگونه از آن استفاده کنیم .
2. ما با CC بازی کردیم و فهمیدیم که چیست و چرا در مقاله دوم درباره پوشش کد مورد نیاز است .
3. و در این مقاله به این موضوع پرداختیم که Markdown چیست، چرا به آن نیاز است و چگونه از آن به طور موثر استفاده کنیم.

با تشکر از همه شما برای خواندن این سه مقاله طولانی، امیدوارم مفید بوده باشد. ممکن است اشتباهات و حذفیات در متن وجود داشته باشد. از توجه همه شما متشکرم!