Open briandominick opened 1 month ago
Admonition-like blocks can be done with emoji and block quotes in GitHub markdown. Horizontal rules can add additional demarcation/emphasis. Compare to Admonitions | Asciidoctor Docs:
Warning markdown:
> -----
>
> ⚠️ **WARNING**
> Wolpertingers are known to nest in server racks. Enter at your own risk.
>
> -----
Warning rendered:
⚠️ WARNING Wolpertingers are known to nest in server racks. Enter at your own risk.
Important markdown:
> -----
>
> 🛑 **IMPORTANT**
> #### Feeding the Werewolves
> While werewolves are hardy community members, keep in mind the following dietary concerns:
> 1. They are allergic to cinnamon.
> 2. More than two glasses of orange juice in 24 hours makes them howl in harmony with alarms and sirens.
> 3. Celery makes them sad.
>
> -----
Important rendered:
🛑 IMPORTANT
Feeding the Werewolves
While werewolves are hardy community members, keep in mind the following dietary concerns:
- They are allergic to cinnamon.
- More than two glasses of orange juice in 24 hours makes them howl in harmony with alarms and sirens.
- Celery makes them sad.
Problem
It is very unclear from the README who this codebase is for, and common public search queries may lead unsuspecting end users here while looking for licenses/tools from the main site, at which point they may decide CC is a technical utility that they cannot hope to understand. Further, even for those who think this is the repo they need to be working on, some clarity would be nice.
Description
Adda prominent note to the top of the README that declares anyone looking for CC licenses and public domain tools should go to https://creativecommons.org/share-your-work/
Add some context about who is expected to make use of this codebase in what ways, before they're submerged in all the technical stuff that follows.
Add a link to https://creativecommons.org/licenses/ (already linked in sidebar but it should be clarified that this codebase essentialy generates that page specifically).
Alternatives
I thought of converting the README to AsciiDoc so we can put a proper admonition block to get better attention, but that seems like overkill. ;-)
Implementation