[gh config] Inconsistent formatting of GitHub CLI manual entry #10348

Activity

1. iamazeem

   added

   bugSomething isn't workingSomething isn't working

   on Jan 31, 2025
2. cliAutomation

   added

   needs-triageneeds to be reviewedneeds to be reviewed

   on Jan 31, 2025
3. andyfeller commented on Jan 31, 2025

   

   andyfeller

   on Jan 31, 2025

   Last edited by andyfeller

   Contributor

   More actions

   Thank you for opening up this issue, @iamazeem! 🙇 I'm unsure if the problem is the markdown used or if this is an issue with underlying jekyll / pages / gems used to render the website markdown content. 🤔

   Source behind gh config on GitHub CLI manual

   ---
   layout: manual
   permalink: /:path/:basename
   ---
   
   {% raw %}## gh config
   
   Display or change configuration settings for gh.
   
   Current respected settings:
   - `git_protocol`: the protocol to use for git clone and push operations {https|ssh} (default https)
   - `editor`: the text editor program to use for authoring text
   - `prompt`: toggle interactive prompting in the terminal {enabled|disabled} (default enabled)
   - `prefer_editor_prompt`: toggle preference for editor-based interactive prompting in the terminal {enabled|disabled} (default disabled)
   - `pager`: the terminal pager program to send standard output to
   - `http_unix_socket`: the path to a Unix socket through which to make an HTTP connection
   - `browser`: the web browser to use for opening URLs
   
   
   ### Available commands
   
   * [gh config clear-cache](./gh_config_clear-cache)
   * [gh config get](./gh_config_get)
   * [gh config list](./gh_config_list)
   * [gh config set](./gh_config_set)
   
   
   {% endraw %}
   ### See also
   
   * [gh](./gh)

   Follow up

   Doing some digging, I'm wondering if this is a problem with the version of kramdown being used with our GitHub Pages site as this has been a historical problem:

   • Fix bug: handle "|" in $$..$$ or <code>..</code> gettalong/kramdown#23
   • the conditional probability equation doesn't display normal gettalong/kramdown#46
   • The $$\latex$$ syntax works great--except for absolute values: |x| gettalong/kramdown#107
   • Problem with mathjax  gettalong/kramdown#134

   So, maybe we need to escape these pipes in a particular way for the website generation or maybe there's something we do on the kramdown side. 🤔

   👍React with 👍1Reacted by Azeem
4. andyfeller

   added

   docs

   coreThis issue is not accepting PRs from outside contributorsThis issue is not accepting PRs from outside contributors

   on Jan 31, 2025
5. iamazeem commented on Feb 1, 2025

   

   iamazeem

   on Feb 1, 2025

   ContributorAuthor

   More actions

   Verified with kramdown (2.5.1) and it's indeed an issue.

   tl;dr (solution)

   Escaping | works i.e. \| (may need to escape slash as well i.e. \\| depending on the context).
   Replacing with HTML code works too i.e. use | instead.

   ---

   Details

   Tested with irb.
   Posting here with one line item for brevity.

   Issue

   > item = '- `git_protocol`: the protocol to use for git clone and push operations {https|ssh} (default https)'
    => "- `git_protocol`: the protocol to use for git clone and push operations {https|ssh} (default https)" 
   
   > print Kramdown::Document.new(item).to_html
   <ul>
     <li>
       <table>
         <tbody>
           <tr>
             <td><code>git_protocol</code>: the protocol to use for git clone and push operations {https</td>
             <td>ssh} (default https)</td>
           </tr>
         </tbody>
       </table>
     </li>
   </ul>
    => nil 

   Here the table is being generated in an unordered list and the item has been divided into two cells:

   <td><code>git_protocol</code>: the protocol to use for git clone and push operations {https</td>
   <td>ssh} (default https)</td>

   Solution

   With escaped |:

   > item = '- `git_protocol`: the protocol to use for git clone and push operations {https|ssh} (default https)'
    => "- `git_protocol`: the protocol to use for git clone and push operations {https|ssh} (default https)" 
   
   > item_with_escaped_pipe = item.sub('|', '\|')
    => "- `git_protocol`: the protocol to use for git clone and push operations {https\\|ssh} (default https)" 
   
   > print Kramdown::Document.new(item_with_escaped_pipe).to_html
   <ul>
     <li><code>git_protocol</code>: the protocol to use for git clone and push operations {https|ssh} (default https)</li>
   </ul>
    => nil 

   With HTML code |:

   > item = '- `git_protocol`: the protocol to use for git clone and push operations {https|ssh} (default https)'
    => "- `git_protocol`: the protocol to use for git clone and push operations {https|ssh} (default https)" 
   
   > item_with_html_code = item.sub('|', '|')
    => "- `git_protocol`: the protocol to use for git clone and push operations {https|ssh} (default https)" 
   
   > print Kramdown::Document.new(item_with_html_code).to_html
   <ul>
     <li><code>git_protocol</code>: the protocol to use for git clone and push operations {https|ssh} (default https)</li>
   </ul>
    => nil

   👍React with 👍1Reacted by Andy Feller
6. andyfeller

   added

   priority-3Affects a small number of users or is largely cosmeticAffects a small number of users or is largely cosmetic

   help wantedContributions welcomeContributions welcome

   and removed

   coreThis issue is not accepting PRs from outside contributorsThis issue is not accepting PRs from outside contributors

   needs-triageneeds to be reviewedneeds to be reviewed

   on Feb 3, 2025
7. andyfeller commented on Feb 4, 2025

   

   andyfeller

   on Feb 4, 2025

   Contributor

   More actions

   Acceptance Criteria

   When GitHub CLI homepage docs are generated
   Then GitHub CLI manual pages containing pipes are escaped

   The following commands can be used to generate docs and find files containing pipes:

   go run ./cmd/gen-docs --website --doc-path site/manual
   find site/manual -name "*.md" -exec grep -rn '|' {} \;

   👍React with 👍1Reacted by Azeem
8. jtmcg

   closed this as completedin #10371on Feb 6, 2025