Softonic

Generator README

Krok 1 / 4 README.md
Dalej

Puste repozytoria robią złe pierwsze wrażenie. Wpisz nazwę projektu, jednowierszowe hasło, listę funkcji, komendę instalacji, fragment szybkiego startu, autora i licencję, a ten generator utworzy schludny plik README w formacie Markdown z poprawną hierarchią nagłówków i blokami kodu w ogrodzeniu: to znaczy sekcje, które GitHub wyświetla na stronie Twojego projektu. Skopiuj go, zapisz jako README.md w katalogu głównym repozytorium i wypchnij. Nagłówki sekcji są zapisane po angielsku, co jest niemal uniwersalną konwencją plików README open source; natomiast Twój własny tekst pojawia się dokładnie tak, jak go wpiszesz, w dowolnym języku.

Jak przygotować README

  1. 1

    Dodaj podstawy

    Nazwa projektu, opcjonalny adres URL repozytorium i jednowierszowe hasło. Nazwa staje się nagłówkiem `#`; hasło staje się cytatem pod nim.

  2. 2

    Wypisz funkcje i szybki start

    Jedna funkcja w wierszu (każda staje się punktem listy), plus krótki fragment szybkiego startu, który jest opakowany w blok kodu w ogrodzeniu.

  3. 3

    Instalacja, licencja i autor

    Komenda instalacji trafia do bloku kodu `bash` w sekcji Installation; dodaj licencję (MIT, Apache-2.0…) i opcjonalny wiersz autora.

  4. 4

    Skopiuj Markdown

    Kliknij kopiuj i wklej wynik jako `README.md` w katalogu głównym repozytorium. Wypchnij, a wyrenderowana wersja pojawi się na stronie projektu.

Co zawiera dobry README

Przewodnik stylu GitHuba oraz powszechnie stosowana specyfikacja standard-readme są zgodne co do kolejności. Umieść łatwe do przejrzenia części na górze: osoba, która trafia do Twojego repozytorium, w 20 sekund decyduje, czy czytać dalej.

Sekcja Pozycja Cel
Tytuł + hasło Wiersz 1–2 # Project, a po nim jedno zdanie o tym, co robi
Odznaki Wiersz 3–5 Status CI, wersja npm, licencja, pokrycie
Instalacja Powyżej zagięcia Jedna komenda, którą można skopiować
Użycie Powyżej zagięcia Najmniejszy działający fragment dający wynik
API / opcje Środek Tabele flag, kluczy konfiguracji lub punktów końcowych
Wkład Blisko końca Link do CONTRIBUTING.md, kodeks postępowania, zasady PR
Licencja Na końcu Identyfikator SPDX oraz link do LICENSE

Odznaki, które naprawdę pomagają

Adresy URL Shields.io mają przewidywalny wzorzec: https://img.shields.io/badge/<label>-<message>-<color>.svg. Przydatne odznaki na żywo wskazują status kompilacji, wersję pakietu i liczbę pobrań, a nie próżne metryki. Zwykle wystarczają cztery odznaki; więcej to szum.

Częste błędy w README

  • Brak komendy instalacji w pierwszym wierszu sekcji Instalacja. Czytelnicy przeglądają tekst w poszukiwaniu npm install lub pip install; jeśli ukryjesz ją za prozą, odejdą.
  • Zrzuty ekranu o rozmiarze 3 MB. Zmień rozmiar do 800 px szerokości i skompresuj; GitHub i tak je poda, ale czytelnicy mobilni płacą za transfer.
  • Nieaktualne odznaki. Czerwona odznaka CI mówi odwiedzającym, że projekt jest zepsuty. Napraw CI albo usuń odznakę.
  • Brak licencji. Bez licencji Twój kod domyślnie ma „wszelkie prawa zastrzeżone“ i firmy nie mogą z niego korzystać.

Najczęściej zadawane pytania

Tak. Bloki kodu w ogrodzeniu, listy punktowane i nagłówki w stylu ATX (przedrostek #) renderują się na GitHub, GitLab i Bitbucket bez zmian. Komenda instalacji jest oznaczona jako blok bash; blok szybkiego startu pozostaje bez oznaczenia, abyś sam ustawił język.

W większości ekosystemów README.md. Użyj .rst tylko wtedy, gdy publikujesz pakiet Pythona, którego dokumentacja znajduje się na Read the Docs, i chcesz, aby Sphinx wykorzystał ten plik jako stronę docelową.

Gdy podasz adres URL repozytorium, generator dodaje jedną statyczną odznakę licencji (https://img.shields.io/badge/license-<type>-blue.svg). Aby uzyskać odznaki na żywo (status kompilacji, wersja, pobrania), skopiuj wzorzec adresu shields.io i wklej go do wyniku samodzielnie.

Nie. README jest składany z wartości formularza i nic nie jest zapisywane. Zamknij kartę, a dane znikną.

Powiązane narzędzia

Tabela ASCII

Pełna tabela ASCII od 0 do 127 z zapisem dziesiętnym, szesnastkowym, ósemkowym i binarnym oraz notacją numerycznych odwołań HTML, w tym kodami sterującymi NUL, LF i DEL.

Referencja znaków HTML

Przeszukiwalna lista encji HTML wraz z ich kodami nazwanymi i liczbowymi oraz kopiowaniem jednym kliknięciem specjalnych znaków i symboli.

Skróty klawiaturowe

Wyszukuj udokumentowane skróty domyślne VS Code, Chrome i Bash z GNU Readline w macOS, Windows i Linux.

Generator EditorConfig

Zbuduj plik .editorconfig z własnych reguł wcięć, końca linii i kodowania, a potem dodaj poprawną sekcję dla każdego języka w repozytorium: Python, Go, YAML, Makefile i więcej.

Walidator adresów e-mail

Zweryfikuj adres e-mail: sprawdzenie składni RFC 5322, sprawdzenie rekordu MX w czasie rzeczywistym oraz szczegóły dotyczące części lokalnej, domeny i długości. Żadna wiadomość nie jest wysyłana.

Formatowanie HTML

Formatuj HTML lokalnie w przeglądarce, używając wcięć dwóch lub czterech spacji. HTML nie jest wysyłany ani walidowany.

Narzędzie jest dostępne w innych językach