Markdown features supported on galaxy.ansible.com

Get Help
,
1

I’m looking for:

  • a reference for the flavor of markdown supported on galaxy.ansible.com for collections’ README.md files.
  • a way to preview how galaxy would render a README.md before publishing a collection.

I have an old collection that needs a bit of rework to meet modern expectations. It’s README.md contains a few tables which render fine on github, but are a bit of a mess on old-galaxy. While some simple table support seems to be there, there’s clearly a difference in the details. Perhaps the current galaxy supports a broader subset of markdown than old-galaxy, too.

Is “galaxy-flavored markdown” documented somewhere? Is there a way to view galaxy rendered markdown before publishing a collection only to find the README.md needs more work?

2

I don’t, but have not had a problem with it. However I have been running this precommit against the repo to check my linting, Markdown is a pain, and we had things that looked fine on github, but still had errors, which might be causing the issue in a different interpreter.

To that end, I linted the repo and it came up with 42 Markdown errors with the standard markdown lint options I use.
PR to add it to your repo

And the action that ran that shows errors

1 Like
3

Thanks, @sean_sullivan . Lots to digest here. Alas, I can only give it one :heart: .

I was hoping the new galaxy had something like github provides, where you can throw a block of markdown at its API and it throws back the rendered html. Here’s a bash function that uses it:

gfm2html ()
{ # github-flavored markdown to html. Requires jq.
    local fname=${1-README.md}
    if [ ! -f "$fname" ]; then
        echo "'$fname' not found." 1>&2
    else
        jq --slurp --raw-input '{"text": "\(.)", "mode": "markdown"}' < "$fname" \
           | curl --data @- https://api.github.com/markdown
    fi
}
4

That’s really cool! I had no idea that existed.

5

There’s a very similar thing for gitlab. At work, we’re a gitlab shop. I’m trying to make my stuff work on our self-hosted gitlab instances, github, and galaxy. Here’s the equivalent bash function for gitlab. You’ll need to provide your own fqdn for your gitlab instance. (It may work with their public facing service, too. Hadn’t thought to try that. Hmm.)

glmd2html ()
{ # gitlab-flavored markdown to html; requires jq.
    local fname=${1-README.md}
    if [ ! -f "$fname" ]; then
        echo "'$fname' not found." 1>&2
    else
        jq --slurp --raw-input '{"text": "\(.)", "gfm":false}' < "$fname" \
        | curl --header Content-Type:application/json --data @- https://${GITLAB_INSTANCE}/api/v4/markdown \
        | jq --raw-output .html;
    fi
}

I don’t see anything in the galaxy API addressing this, but one can hope…

1 Like