Galaxy markdown render preview - enhancement request

utoddl · October 13, 2023, 3:17pm

Continuing the discussion from Markdown features supported on galaxy.ansible.com:

I’d like to put this forward as a request for enhancement: to provide an API on galaxy to return the HTML that galaxy would render for a submitted blob of markdown. The discussion cited above, part of which is quoted below, shows how to use the equivalent API on both github and gitlab. Such a feature on galaxy would facilitate README.md and other *.md creation and editing by providing a mechanism for maintainers to see how their documentation renders before committing to publication.

Markdown features supported on galaxy.ansible.com

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
}

jlmitch5 · November 21, 2023, 3:18pm

This sounds like a cool idea @utoddl, thanks for proposing!

We’ve got it added to our roadmap* for scoping and inclusion in a future milestone. The team is a bit at capacity with our current shorter term roadmap of enhancements and fixes to galaxy right now. In short, we probably won’t be able to dedicate a dev to this feature until sometime next year at the earliest.

That being said, if you or anyone else is interested in working on this enhancement in the shorter term, we’d be happy to work through a potential PR for inclusion.

*the roadmap mentioned/milestones are currently getting finalized we are hoping to publish info about these next week.

utoddl · August 7, 2024, 9:10pm

The ansible/galaxy_ng README.md invites me to view the Roadmap which leads me to a three-year-old page leading to roadmap for 4.4.0 which is tweakable, but searching for various combinations of “markdown”, “preview”, and/or “galaxy” just … reminds me that I have a lot of “good intention” artifacts in my own projects.

I can throw no stones. [sigh]

bmclaughlin · August 12, 2024, 4:18pm

Hi @utoddl! I actually took an interest in this one quite some time ago and added a command to galaxy-importer to convert markdown to html. It was released with version 0.4.19 of galaxy-importer on January 18th.

utoddl · August 12, 2024, 6:20pm

Thank you, @bmclaughlin.

I’m a little vague on how galaxy-importer fits into the ecosystem. Is this the same code that’s used by galaxy.ansible.com when uploading content? If so, does this imply that galaxy (the service) stores doc assets pre-rendered? (That would explain why I didn’t see anything relevant to rendering md→html when rummaging through the galaxy-ng code.)