Ten konwerter zamienia Markdown na reStructuredText (RST) dla Sphinx, Read the Docs i PyPI: nagłówki z podkreśleniami, dyrektywy code-block, tabele siatkowe, bloki uwag i przypisy. Wystarczy wkleić README.md i skopiować gotowy plik .rst.
Ostatnia aktualizacja:
Jak to działa
Wklej Markdown
README, stronę dokumentacji lub jej fragment wystarczy wkleić, otworzyć jako plik .md albo wczytać przykład.
Ustal konwencje
Znaki w „Podkreślenia nagłówków”, dyrektywę w „Bloki kodu”, styl tabel i sposób zapisu linków da się dopasować do istniejącego projektu.
Użyj pliku .rst
Wystarczy pobrać README.rst albo wkleić tekst do projektu Sphinx.
Funkcje
Poprawna struktura sekcji
RST ustala poziomy na podstawie kolejności stylów podkreśleń, więc pominięte poziomy z Markdownu są zwijane, aby uniknąć błędu „Title level inconsistent”.
Dyrektywy zamiast obejść
Kod staje się .. code-block:: python, uwagi – .. note:: lub .. warning::, a wzory – .. math::.
Trzy style tabel
„Tabela siatkowa”, „Tabela prosta” albo „Dyrektywa list-table”, którą najłatwiej później edytować.
Reguły znaczników w tekście
Tam, gdzie RST wymaga białych znaków wokół **pogrubienia** lub `linków`__, wstawiane są spacje poprzedzone ukośnikiem wstecznym.
Limity i prywatność
Pliki do 10 MB. Teksty większe niż 256 KB są konwertowane w wątku roboczym w tle (Web Worker), więc strona nie przestaje reagować. Nic nie jest wysyłane na serwer, a „Otwórz z adresu URL” pobiera plik bezpośrednio z podanego adresu. Więcej na stronie o prywatności.
Różnice, o których warto pamiętać
reStructuredText nie ma przekreślenia ani podkreślenia, więc taki tekst zostaje bez formatowania. Twarde podziały wierszy zamieniają się w bloki linii (wiersze zaczynające się od |). Linia oddzielająca (––) nie może zaczynać ani kończyć dokumentu, dlatego w tych miejscach jest usuwana. Tabele siatkowe i proste nie obsługują wyrównania kolumn – jeśli jest ważne, wybierz dyrektywę list-table.
Gotowy plik .rst można też przekształcić z powrotem: służy do tego RST → Markdown.
Najczęstsze pytania
Jak zamienić README.md na README.rst?
Wystarczy otworzyć README.md i pobrać wynik jako README.rst. Ostrzeżenia pod wynikiem pokazują, czego RST nie potrafi wyrazić.
Czy PyPI nadal wymaga RST?
Nie, PyPI renderuje też Markdown, ale projekty Sphinx i wiele starszych narzędzi oczekuje reStructuredText.
Dlaczego znika pogrubienie wewnątrz linku?
reStructuredText nie pozwala zagnieżdżać formatowania w tekście. Tekst linku zostaje, a wewnętrzne formatowanie jest usuwane z ostrzeżeniem.
Jak zapisywane są obrazy w środku zdania?
Przez podstawienia: |nazwa| w tekście i definicję .. |nazwa| image:: na końcu dokumentu.
Który zestaw podkreśleń nagłówków wybrać?
Do wyboru są zestawy „popularne”, „dokumentacja Pythona” i „docutils”. Ważne, by w całym projekcie trzymać się jednego, bo RST rozpoznaje poziomy po kolejności znaków.
Czy można wrócić z RST do Markdownu?
Tak, konwerterem RST → Markdown, do którego link jest nad wynikiem.