Closed toastal closed 1 year ago
Regardless of the merits of AsciiDoc, Markdown is the lingua franca of the developer community. I prefer to stick to what people are familiar with. I do agree raw readability could be improved by toning down the HTML a bit, though.
I understand that concern. It's a mostly-compatible syntax most anyone can learn. Larger feature set aside, you won't be able to convert these parts to Markdown with the current documentation scope:
<blockquote>
If you want to eliminate the need to render the document and have a good plaintext experience and robust rendered experience, Markdown will require you to make concessions to at least one of these.
image width/heights without resorting to HTML
We should just resize the actual images to the correct size.
no such concept as admonitions which will involve manually building something with bold blocks, or as it currently stands, using the semantically incorrect element
<blockquote>
GitHub doesn't render admonitions very well anyhow; so I'd prefer an alternative.
floating paragraphs for what are headings/captions for code blocks
This is common practice, and pretty self-evident; no need to change.
Then go for it :+1:
To see this rendered: https://github.com/toastal/postcss-cli/blob/readme/README.adoc To see it raw: https://raw.githubusercontent.com/toastal/postcss-cli/readme/README.adoc
READMEs however should require minimal rendering (or it would be called RENDERME). As such I believe AsciiDoc offers a richer feature set. Currently the README is optimized for... GitHub's rendering? And as such includes a number misused elements and markup that doesn't need to exist. I believe GitHub support of AsciiDoc will continue to improve, especially with admonitions. Maybe the macros for the URLs aren't really needed though as it adds a big block of not really much value. Some comments would do better IMO, but I wanted to keep the general README structure.