widdershins
widdershins copied to clipboard
Mermade
Pure / consistent markdown option
Is your feature request related to a problem? Please describe.
Unsure as to why there is a mix of HTML and traditional markdown headers/links mixed in with all of the output code. It ruins the ability for me to transform the markdown output into something usable with other documentation systems that are expecting pure markdown.
It also makes simple document-wide transformations like stepping all of the headers down one level prohibitively difficult.
Example:
<h1 id="api">My Api</h1>
> Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
My API
Base URLs:
* <a href="....">...</a>
## Authentication
- oAuth2 authentication.
...
<h3 id="get-route-parameters">Parameters</h3>
Describe the solution you'd like
Pure markdown,
# Header
## Second Header
[A link](http://....)
I'll need to dig into the commit messages to find out what problems we were experiencing with plain markdown headers, links and anchors. Please bear with me.
What we output aims to be CommonMark compatible, and HTML is allowable there, though I would be interested to know what documentation consumers only support 'traditional' markdown.
Same issue for me, I am using widdershins to generate markdown from asyncapi specs in a bitbucket pipeline and pushing the output to documentation repo. Mostly to view in bitbucket directly, but it results in this:
@MikeRalphson Docusaurus is another tool that doesn't play well with html in the markdown.
EDIT: The problem appears to have been HTML comments, other than that the markdown worked fine.
What is the point of using markdown if you are going to add HTML to it anyway?
What is the point of using markdown if you are going to add HTML to it anyway?
@eaglestorm markdown supports HTML tags. And we use them for things that markdown doesn't support, and for things which don't work well with native markdown in Slate and other tools.