Darmowy konwerter online ASCIIDOC do MD

GitHub, GitLab i wiele narzędzi do tworzenia dokumentacji obsługuje Markdown, ale nie AsciiDoc, dlatego plik .adoc może wymagać konwersji przed opublikowaniem lub edytowaniem w tych narzędziach. Konwersja do .md zachowuje czytelny kod źródłowy, jednocześnie dostosowując nagłówki, listy, linki i bloki kodu do składni Markdown.

Czym jest format ASCIIDOC

AsciiDoc to format znaczników w postaci zwykłego tekstu, używany do tworzenia dokumentacji oprogramowania, instrukcji, książek, informacji o wydaniach i plików README. Typowe rozszerzenia to .adoc, .asciidoc i .ad.

Pliki AsciiDoc są zwykle tworzone lub przetwarzane za pomocą Asciidoctor, nowoczesnej implementacji w języku Ruby, albo starszego procesora AsciiDoc. Edytory takie jak Visual Studio Code, IntelliJ IDEA i dedykowane narzędzia do tworzenia dokumentacji również mogą tworzyć te pliki, ponieważ kod źródłowy jest zwykłym tekstem.

AsciiDoc obsługuje atrybuty, dyrektywy include, bloki admonition, tabele, odwołania wewnętrzne, diagramy, cytowania i wielokrotnego użytku struktury dokumentów. Niektóre z tych funkcji nie mają bezpośredniego odpowiednika w Markdown.

Czym jest format MD

MD to typowe rozszerzenie plików Markdown. Markdown to lekki format zwykłego tekstu, zaprojektowany z myślą o czytelnym kodzie źródłowym i łatwym renderowaniu do HTML. GitHub, GitLab, Bitbucket, generatory witryn statycznych, wiki, aplikacje do robienia notatek i edytory kodu zwykle go obsługują.

Markdown jest praktycznym formatem docelowym, gdy repozytorium wymaga pliku README.md, gdy współpracownicy edytują dokumentację w narzędziach ukierunkowanych na Markdown albo gdy pliki źródłowe muszą być spójnie wyświetlane na różnych platformach do hostowania kodu. GitHub Flavored Markdown (GFM) dodaje tabele, listy zadań, automatyczne linki i ogrodzone bloki kodu.

Jak faktycznie przekonwertować ASCIIDOC do MD

Aby wykonać konwersję lokalnie, zainstaluj Pandoc, a następnie uruchom:

pandoc input.adoc -f asciidoc -t gfm -o output.md

Zastąp input.adoc nazwą pliku źródłowego, a output.md żądaną nazwą pliku docelowego. Opcja -f asciidoc wybiera czytnik AsciiDoc, -t gfm generuje GitHub Flavored Markdown, a -o zapisuje wynik do pliku.

Aby przekonwertować plik z rozszerzeniem .asciidoc, użyj jego rzeczywistej nazwy:

pandoc manual.asciidoc -f asciidoc -t gfm -o manual.md

Jeśli zainstalowana wersja Pandoc nie udostępnia czytnika AsciiDoc, użyj Asciidoctor do utworzenia najpierw pliku DocBook XML, a następnie przekonwertuj ten plik pośredni:

asciidoctor -b docbook5 -o intermediate.xml input.adoc
pandoc intermediate.xml -f docbook -t gfm -o output.md

Jeśli nie chcesz nic instalować, prześlij plik źródłowy do 101convert.com, wybierz Markdown jako format wyjściowy, uruchom konwersję i pobierz wynikowy plik .md. Unikaj przesyłania dokumentów zawierających poufne lub zastrzeżone informacje.

Ograniczenia jakości i zgodności

Konwersja nie zawsze jest bezstratna. Atrybuty AsciiDoc, treści warunkowe, dyrektywy include, niestandardowe role, makra, rozszerzenia, złożone tabele, bloki admonition i odwołania wewnętrzne mogą zostać uproszczone, pominięte lub zapisane jako surowe znaczniki.

Sprawdź wygenerowany plik Markdown pod kątem poziomów nagłówków, zagnieżdżenia list, formatowania tabel, ścieżek obrazów, ogrodzonych bloków kodu, linków i znaków poprzedzonych znakami ucieczki. GFM obsługuje tabele i listy zadań, ale inne parsery Markdown mogą renderować te funkcje inaczej.

Dyrektywy include w AsciiDoc mogą wymagać wstępnego przetworzenia przed konwersją. Rozwiąż pliki wskazywane przez dyrektywy include:: i sprawdź, czy względne ścieżki obrazów i linków nadal prowadzą do właściwych lokalizacji po przeniesieniu pliku wyjściowego.