search

Mermade / widdershins

OpenAPI / Swagger, AsyncAPI & Semoasa definitions to (re)Slate compatible markdown
https://mermade.github.io/reslate
MIT License
1.48k stars 321 forks source link

Pure / consistent markdown option #294

Open braco opened 4 years ago

braco commented 4 years ago

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://....)
MikeRalphson commented 4 years ago

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.

dylan-evans commented 2 years ago

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:

image

jrtcppv commented 2 years ago

@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.

eaglestorm commented 1 year ago

What is the point of using markdown if you are going to add HTML to it anyway?

MikeRalphson commented 1 year ago

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.