Improve readme

[jcbhmr]

This PR would... (checkboxes track draft progress)

• Add a header image to the top of the readme to grab attention (currently placeholder cat)
• Add an options table in the readme (need your @spenserblack approval of table vs headings vs <dl> vs in-code)
• Keep most of the content from the original
• NOT update anything else
• NOT promise features that @jcbhmr wants to implement but hasn't actually coded yet
• Address the CURRENT STATE of the repo only

Regarding table vs ... here's the options that I found: (copied from Andrew-Chen-Wang/github-wiki-action#22 (comment))
@spenserblack looking for active ✅ approval/opinion on your favorite

1: table

2: In YAML

https://github.com/actions/checkout#readme

3: Literal list

https://github.com/wow-actions/contributors-list#readme

4: Headers for each option

https://github.com/veracode/veracode-sandboxes-helper#readme

5: dl description list

<dl> (couldn't find any GitHub Action examples of this)

Closes #9

[jcbhmr]

Here's what the <dl> currently looks like (it's the first one I tried after <table>)

[jcbhmr]

An improvement to this draft would be a screenshot of the "Create your first wiki page for user/repo" page with a circle around the button in the "you must create a dummy page first" section

I did this in Andrew-Chen-Wang/github-wiki-action#22

I also do try to do this in readmes but sometimes forget (like I did here). I think it's a nice touch that's an addon type thing, but not required to understand the content of a section

demo:

https://gist.github.com/jcbhmr/5fa35ec1c7208018e9dce2a9e06af0cf

[jcbhmr]

Another improvement might be to add in the github and github actions badges that I use to be like "here's what you can use this tool with" like I did in Andrew-Chen-Wang/github-wiki-action#22

[jcbhmr]

@spenserblack opinions on options in PR post? table vs <dl> vs headings vs code or whatever?

[spenserblack]

BTW, I see you're using ❗ and ⚠️ for alerts. Just an FYI, this is in beta:

Markdown

> **Warning**
> This is a warning

Rendered

(should be an admonition, assuming no changes to GH's Markdown parsing)

Warning
This is a warning

---

Personally, I prefer the emojis, but I figured you might be interested.
more info.

[jcbhmr]

@spenserblack Yep! I saw that new feature, but I have a distaste for it because

1. It completely upends the idea that a <blockquote> is a quote of something and instead now it's just an indent trick
2. They are still duller than the emoji version (just an outline, no fill color)

[jcbhmr]

@spenserblack I've commented on the review comments; and while I did make a valiant defense of my own coding/readme/writing style, I will conform with this repo's styleguide. ✍️

[jcbhmr]

@spenserblack I saw somewhere (can't find it again) that you were curious how gh repo view rendered markdown, so here's a sample using some <div align=center> stuff from https://github.com/jcbhmr/fetch.ino

Note that both the "under construction" image and the code https://carbon.now.sh image are centered with <div align=center>

here's cli terminal output screenshot:

here's original web view:

I think it's pretty cool that they've got a fancy terminal renderer (wow). I wonder if it's based on https://github.com/charmbracelet/glow ?

[spenserblack]

I wonder if it's based on https://github.com/charmbracelet/glow ?

It is! They use glamour, which uses glow. (they even have some of the same problems 😆)

Edit: Nevermind, I got the dependencies reversed 😆 gh and glow share the same dependency with similar visual results.

[jcbhmr]

ChatGPT says this is a 9/10 readme 🤣 as of https://github.com/jcbhmr/actions-wiki/commit/f6995de86b90fc85f6c253d8d6974fed31f2d3c4

@jcbhmr

Rate this GitHub readme from 1-10

paste of readme raw code

ChatGPT

I would rate this GitHub readme a 9 out of 10. It is well-structured, informative, and provides clear instructions for using the tool. The features and usage of the action are described clearly, and the readme includes helpful examples and screenshots. The readme also provides alternatives to the tool, which can be helpful for users who are considering other options. The only improvement that could be made would be to include more information about the limitations and potential issues that users may encounter.

[jcbhmr]

Made some changes. Namely I added a sub-section in the "Usage" section to discuss cross-repo publishing

https://github.com/jcbhmr/actions-wiki/tree/improve-readme#publishing-to-a-different-repository

/cc @spenserblack

[spenserblack]

Looks great! One last nitpick.

[spenserblack]

Thanks for putting up with my nitpicks! 😆

[spenserblack]

Stumbled on this recently. I haven't dug into it yet, but I figured it could be relevant, and you might be interested. https://github.com/RichardLitt/standard-readme