Pandoc -atx-headers -base-header-level 2 -o "$.adoc" -wrap=none "$f" upstream. # Markdown to asciidoc the way I like it. The conversion is not yet perfect, but it does go a long way. If you already have a Markdown document and want to convert it to asciidoc,
GitHub even added the triple backticks block code extension syntax because of that! not possible to view older versions of the documentsīuilt-in syntax can link to headers, give headers custom IDs independent of text, and with asciidoctor -v get a warning for broken linksĮverything can be done without indentation, which is hard to type on browser boxes.broken builds on forced dependency updates.forget about GitHub Pages difficulties such as:.sed refactors everything if you use a single source file.This allows you to easily put everything one HTML page or source file. Here is one example of what you can achieve on GitHub with a README.adoc: Īnd here is Buildroot’s perfect AsciiDoc-based generated documentation:ĪsciiDoc has built-in Table of Contents and file inclusion functionality. The Asciidoctor implementation is likely the best choice as of 2019.ĪsciiDoc takes Markdown, and adds just enough to write serious books, while reducing some markdown annoyances at the same time. your document is large enough to need a headerĬonsider using AsciiDoc instead of Markdown.GitHub READMEs, self-rendered documentation
Readable and portable Markdown style guide. Markdown Style Guide - Ciro Santilli Ciro Santilli Markdown Style Guide