How should the inputs and outputs be marked up in the readme?

[jcbhmr]

However, making a Markdown table well-spaced is a bit of a pain to do manually, so maybe it's time to add prettier to the toolchain?

Even adding prettier won't do anything to help the rendered version. If your descriptions are good, they should ideally be like two sentences. One to describe what the option is, and one to describe what the option does (is used for). Like:

repo
This is the slug of the GitHub repository, optionally
prefixed with a domain name. We will push the wiki
folder chosen by the path option to this repo's wiki

The point is that these descriptions can get long-ish and they don't fit well in a table when rendered like this: (from your own example lol)

like wtf is that multiline ${{ github.token }} thing?

---

Point is there are these options that I've thought of: (see top PR original post for <details> sections examples of each)

• table
• in-yaml <pre> block
• literal list <ul>
• heading sections for each option
• <dl> list

Here's my rudimentary analysis of the options:

• table: ugly multiline madness since you can't control width of columns
• pre: kinda cheating, but seems to be a decent middle-ground of src vs render
• list: 2d option tuples don't really fit into a 1d list
• heading: works ok, just takes up too much vertical space with all the margins
• dl: looks pretty decent on render, hard to markup in source

To make the <dl> slightly better in source, you could

<dl><dt><code>repo</code></dt><dd>

You can use plain \
**Markdown** here since there's _2_ newlines.

</dd><dt><code>option-b</code></dt>...

but some might argue (even me) that ☝️ is worse

We should open a discussion about this 😜

Originally posted by @jcbhmr in #13 (comment)

[spenserblack]

like wtf is that multiline ${{ github.token }} thing?

IKR? I really wish that GitHub included some CSS styling to forbid line breaks in code spans (it's really easy to do) 😅

I'll take some time to think about this.

---

Here are just some random, unordered, and possibly even contradictory thoughts:

• (Well-written) HTML will always render better since we control the exact elements, and some limited styling. But I'm always hesitant to add embedded HTML.
• I'd definitely like to avoid as much vertical scrolling as possible. The more that renders horizontally, the better.
• As a sort of hack, we can just drop the ${{ and }} delimiters, since the line breaks are on whitespace.
• We may just want to instruct the user to view action.yml. Let's consider the target audience: repository owners who will write a GitHub workflow using this action. The likelihood that they can't read YAML is very low. This also avoids the duplicate effort of updating action.yml and the docs. All that needs to be added are comments describing possible values.
• Perhaps a YAML code block might be best. It can be copied and pasted, and coders love to copy and paste.

[jcbhmr]

As a sort of hack, we can just drop the ${{ and }} delimiters, since the line breaks are on whitespace.

As another hack, you can use   characters since they are literally non-breaking spaces.

ex:

table	lots	of	columns	and	more	here	wow	many	columns
www www www www www w	www www www www www www www	www ww ww wwww www wwww	wwwwww wwwww	wow wow no breaks!	www w wwwww w www	wwww ww w ww ww w w w	ww w w w	ww w wwww w

[jcbhmr]

For reference, here's an example YAML used to describe the options: https://github.com/actions/checkout#usage

[spenserblack]

😢 But   doesn't look pretty in plain-text 😆

IDK if you can tell, but I'm borderline form-over-function when it comes to how source code looks. 😆

[jcbhmr]

Yes, I know, I too hate to look at this:

| Title here |
| --- |
...

if only you could insert a literal U+00A0 (a nbsp char) without Prettier replacing it with the regular U+0020 (space char) 😡 then it'd look good in src (looks like normal space) AND in render (doesn't break)

like this works in github, but it doesn't work if it's run through Prettier because that special gets replaced with a

|table|lots|of|columns|and|more|here|wow|many|columns|
|---|---|---|---|---|---|---|---|---|---|
|www www www www www w|www www www www www www www|www ww ww wwww www wwww|wwwwww wwwww|`wow wow no breaks!`|www w  wwwww w www| wwww ww w ww ww w w w|ww w w w|ww  w wwww w |

table	lots	of	columns	and	more	here	wow	many	columns
www www www www www w	www www www www www www www	www ww ww wwww www wwww	wwwwww wwwww	wow wow no breaks!	www w wwwww w www	wwww ww w ww ww w w w	ww w w w	ww w wwww w

💡 pro tip: you can get a nbsp or a zero-width space by (ab)using copy() in your js console: copy("\u00a0") or copy("\u2060") for a zero-width-non-breaking space (word joiner)

[spenserblack]

Put in my vote 🙂

[jcbhmr]

I'm torn between the YAML idea and just a plain <ul>

i guess here's a comparison of the two:

- uses: actions/checkout@v3
  with:
    # Repository name with owner. For example, actions/checkout
    # Default: ${{ github.repository }}
    repository: ''

    # The branch, tag or SHA to checkout. When checking out the repository that
    # triggered a workflow, this defaults to the reference or SHA for that event.
    # Otherwise, uses the default branch.
    ref: ''

    # Personal access token (PAT) used to fetch the repository. The PAT is configured
    # with the local git config, which enables your scripts to run authenticated git
    # commands. The post-job step removes the PAT.
    #
    # We recommend using a service account with the least permissions necessary. Also
    # when generating a new PAT, select the least scopes necessary.
    #
    # [Learn more about creating and using encrypted secrets](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)
    #
    # Default: ${{ github.token }}
    token: ''

    # SSH key used to fetch the repository. The SSH key is configured with the local
    # git config, which enables your scripts to run authenticated git commands. The
    # post-job step removes the SSH key.
    #
    # We recommend using a service account with the least permissions necessary.
    #
    # [Learn more about creating and using encrypted secrets](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)
    ssh-key: ''

• repository: Repository name with owner. For example, actions/checkout. Default: ${{ github.repository }}
• ref: The branch, tag or SHA to checkout. When checking out the repository that triggered a workflow, this defaults to the reference or SHA for that event. Otherwise, uses the default branch.
• token: Personal access token (PAT) used to fetch the repository. The PAT is configured with the local git config, which enables your scripts to run authenticated git commands. The post-job step removes the PAT. We recommend using a service account with the least permissions necessary. Also when generating a new PAT, select the least scopes necessary. Learn more about creating and using encrypted secrets Default: ${{ github.token }}
• ssh-key: SSH key used to fetch the repository. The SSH key is configured with the local git config, which enables our scripts to run authenticated git commands. The post-job step removes the SSH key. We recommend using a service account with the least permissions necessary. Learn more about creating and using encrypted secrets

After seeing this, I actually think I prefer the <ul> since it's so compact in comparison to the bulky odd codeblock.

Also the codeblock kinda also has example stuff surrounding it? It's a bit of a conflation between "example" and "options table"...

well that's my vote. 😉

---

P.S. if you really want to space out the <ul> some more, you can use two newlines between each - ... bullet:

- number 1

- number 2

like so:

• repository: Repository name with owner. For example, actions/checkout. Default: ${{ github.repository }}

• ref: The branch, tag or SHA to checkout. When checking out the repository that triggered a workflow, this defaults to the reference or SHA for that event. Otherwise, uses the default branch.

• token: Personal access token (PAT) used to fetch the repository. The PAT is configured with the local git config, which enables your scripts to run authenticated git commands. The post-job step removes the PAT. We recommend using a service account with the least permissions necessary. Also when generating a new PAT, select the least scopes necessary. Learn more about creating and using encrypted secrets Default: ${{ github.token }}

• ssh-key: SSH key used to fetch the repository. The SSH key is configured with the local git config, which enables our scripts to run authenticated git commands. The post-job step removes the SSH key. We recommend using a service account with the least permissions necessary. Learn more about creating and using encrypted secrets

@spenserblack any chance this sways your vote? 🗳️

[jcbhmr]

Here's an example with our content:

[spenserblack]

any chance this sways your vote?

TBH I think it's solidified my vote 😆
I do really like the YAML block with the comments.

I've personally enjoyed, when using a starter workflow or starter dependabot.yml file, seeing the comments in the valid code and making adjustments as needed. Then there's very little context switching between docs and the code I'm writing -- just copy it all and read and adjust as needed.

[jcbhmr]

So to summarize on the two frontrunners:

YAML codeblock

pros	cons
Copying includes documentation: Can embed the full documentation for the options into the example code so that they are one-and-the-same	Takes up more space: User has to scroll through potentially multiple paragraphs of manually wrapped code (doesn't expand-to-fit width) to get to the bottom Screen readers suffer (a bit) on code since each line break is treated as a <br> and they speak each # Can't include fancy links 👈 like that

Normal <ul> list in markdown

pros	cons
Makes sense semantically: Is rendered to plain old natural HTML documentation. Compact doesn't take up too much vertical space since allowed to expand to fit content box Is just plain markdown; that means you can add links, bold stuff, etc.	No real cons? just a lack of pros from the YAML idea; namely the copy-with-docs thing

---

@spenserblack wait a minute... what if we did BOTH? A short description in the example code for any options, plus an options table? Maybe even filtered by option popularity like path get's a comment and a <li> entry, but commit-date only gets an <li>?

so like this

- uses: actions/checkout@v3
  with:
    # Change this to set the directory that will be published to your GitHub wiki
    path: wiki
    # If you're using an external GitHub repository, un-comment this and change it. You'll
    # need a PAT to push to one outside of the scope of ${{ github.token }}.
    # repository: jcbhmr/test-repo
    # token: ${{ secrets.GITHUBX_TEST_REPO_PAT }}
...

then the full options ul

[spenserblack]

Sounds good to me! 👍