Revamp README

[toastal]

• Markdown → AsciiDoc
• Incorrect usage of blockquotes → Admonitions
• Incorrect Bash syntax blocks → Console syntax
• Block headings instead of floating paragraphs with bold text
• Typographic apostrophes
• Remove unnecessary HTML that makes it harder to read as plaintext

---

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.

[RyanZim]

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.

[toastal]

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:

• image width/heights without resorting to HTML
• 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>
• floating paragraphs for what are headings/captions for code blocks

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.

[RyanZim]

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.

[toastal]

Then go for it :+1: