در این مقاله چه خواهید یافت؟
احتمالاً به طور تصادفی با بسیاری از مخازن GitHub برخورد کرده اید که هر کدام صفحه README منحصر به فرد خود را دارند. آیا تا به حال فکر کرده اید که چه چیزی یک README خوب را می سازد؟ نوعی که برجسته است، شما را جذب می کند و از همه مهمتر به شما در درک پروژه کمک می کند؟
در این مقاله، ما به شما نشان خواهیم داد که چگونه صفحه GitHub README عالی را ایجاد کنید.
TL; DR: شما فقط می توانید README من را اینجا کپی کنید
Papermark – جایگزین منبع باز برای DocSend.
قبل از شروع، اجازه دهید Papermark را به شما معرفی کنم. این یک جایگزین منبع باز برای DocSend است که به شما در مدیریت اشتراک‌گذاری امن اسناد، از جمله تجزیه و تحلیل بلادرنگ کمک می‌کند. این همه منبع باز است!
من کاملاً هیجان زده خواهم شد اگر بتوانید به ما یک ستاره بدهید! فراموش نکنید که نظرات خود را در بخش نظرات به اشتراک بگذارید ❤️
https://github.com/mfts/papermark
بسترسازی
خوب حالا بیایید دستمان را کثیف کنیم. ما شما را از طریق اجزای کلیدی یک README کامل و نحوه ساخت هر بخش راهنمایی می کنیم.
محیط نشانه گذاری خود را تنظیم کنید
ابتدا باید محیطی را برای نوشتن README خود تنظیم کنید. همه GitHub README با Markdown نوشته شده اند، یک نحو سبک وزن و آسان برای استایل دادن به نوشته شما. اگر با Markdown آشنایی ندارید، نگران نباشید. برداشتن آن به آسانی پای است.
من معمولا README خود را در کنار کد پروژه می نویسم، اما شما همچنین می توانید یک فایل README جداگانه ایجاد کنید. این به شما بستگی دارد. فقط مطمئن شوید که یک فایل README.md در دایرکتوری ریشه پروژه خود دارید.
من از Visual Studio Code به عنوان ویرایشگر کد خود استفاده می کنم و یک افزونه مفید به نام Markdown All in One وجود دارد که به شما امکان می دهد Markdown خود را هنگام تایپ پیش نمایش کنید. این یک راه عالی برای مشاهده اینکه README شما در GitHub چگونه به نظر می رسد است.
شروع با یک انفجار: عنوان پروژه و توضیحات
هر README باید با یک عنوان واضح و قانع کننده شروع شود و سپس یک شرح مختصر پروژه ارائه شود. این اولین چیزی است که مردم هنگام ورود به مخزن شما می بینند، بنابراین مطمئن شوید که جذاب و توصیفی است.
در اینجا یک مثال است:
# Papermark
Papermark is an open-source document sharing alternative to DocSend with built-in analytics.
“نحوه” بسیار مهم: نصب و استفاده
این گوشت و سیب زمینی README شماست. شما باید کاربران خود را در مورد نحوه نصب و استفاده از پروژه خود راهنمایی کنید. واضح، دقیق و در صورت لزوم مثال بزنید.
در اینجا یک مثال است:
## Installation
First, clone this repository:
<!-- start:code block -->
# Clone this repository
git clone https://github.com/mfts/papermark.git
cd papermark
# Install dependencies
npm install
# Copy the example .env file
cp .env.example .env
# Initialize the database
npx prisma generate
npx prisma db push
# Run the app
npm run dev
# Open http://localhost:3000 in your browser
open http://localhost:3000
<!-- end:code block -->
نسخه ی نمایشی: نشان دهید، فقط بگویید
ارزش یک عکس هزاران کلمه است و یک GIF حتی بیشتر. برای نشان دادن ویژگی های پروژه خود از اسکرین شات یا GIF استفاده کنید. این کار باعث می شود تا کاربران درک کنند که پروژه شما چه می کند.
مشارکت: تشویق به همکاری
منبع باز همه چیز در مورد جامعه است. فراموش نکنید که بخشی را بگنجانید که دیگران را به مشارکت تشویق می کند. مراحل مشارکت را مشخص کنید و اگر فایل CONTRIBUTING.md پروژه خود را دارد پیوند دهید.
در اینجا یک مثال ساده آورده شده است:
## Contributing
Papermark is an open-source project and we welcome contributions from the community.
If you'd like to contribute, please fork the repository and make changes as you'd like. Pull requests are warmly welcome.
امتیاز: نشان‌ها و مشارکت‌کنندگان را نشان دهید
نشان ها راهی عالی برای نشان دادن آمار پروژه شما هستند. می‌توانید برای مواردی مانند تعداد ستاره‌ها، چنگال‌ها و مشارکت‌کنندگان نشان اضافه کنید. همچنین می توانید نشان هایی برای CI/CD، پوشش کد و موارد دیگر اضافه کنید. شما می توانید تمام نشان ها را در shields.io پیدا کنید.
<div align="center">
<a href="https://github.com/mfts/papermark/stargazers"><img alt="GitHub Repo stars" src="https://img.shields.io/github/stars/mfts/papermark"></a>
<a href="https://twitter.com/mfts0"><img alt="Twitter Follow" src="https://img.shields.io/twitter/follow/mfts0"></a>
<a href="https://github.com/mfts/papermark/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/badge/license-AGPLv3-purple"></a>
</div>
همچنین می توانید لیستی از مشارکت کنندگان را به README خود اضافه کنید. این یک راه عالی برای نشان دادن قدردانی شما از افرادی است که در پروژه شما مشارکت داشته اند. به contrib.rocks بروید تا لیستی از مشارکت کنندگان پروژه خود را ایجاد کنید.
### Our Contributors ✨
<a href="https://github.com/mfts/papermark/graphs/contributors">
<img src="https://contrib.rocks/image?repo=mfts/papermark" />
</a>
نتیجه
شما آن را دارید! ساختن README عالی ترکیبی از ارتباطات واضح، سازماندهی خوب و مقداری از پیتزا است. این به خودی خود یک شکل هنری است و با کمی تمرین، README هایی ایجاد می کنید که نه تنها آموزنده، بلکه جذاب نیز هستند.
من مارک هستم، یک علاقه‌مند به منبع باز و نگهدارنده افتخار Papermark. کاردستی README مبارک!
کمک کنید خارج شوم!
اگر این مقاله برای شما مفید بود و README را کمی بهتر درک کردید، بسیار خوشحال خواهم شد اگر بتوانید به ما ستاره بدهید! و فراموش نکنید که نظرات خود را در نظرات به اشتراک بگذارید ❤️
https://github.com/mfts/papermark
