Context: we sync all of our documentation from Github repos, using the full suite of rdme tools: both OpenAPI spec and docs written in markdown. We intentionally do not use ReadMe's live editor to maintain a single source of truth in a repo that can have automated checks and sync up.

Problem:

Most of the markdown rendering tools follow the spec that insert a new line only after a blank line was inserted in source.

For example:

If I write some text here even if I insert a new line
here it, in the final output it will continue on the same line

And only here it will get a new line/paragraph

However, ReadMe will render all of the \n in the upload and break lines creating a somewhat disorienting output.

The commonmark spec allows an unclosed code block to extend to the end of the doc. I think we allowed this until #70, but didn't have a test for it?

In certain scenarios when a callout is pinned to the sidebar, like so...

...it seems to loose it's content on render:

This is likely to do with the way I've set up the callout AST, which requires some hoop-thru-jumping to parse out the icon and title text from the rest of the children content:

https://github.com/readmeio/api-explorer/blob/2cfc9160a46293b07574d49c2a255f783afd1a90/packages/markdown/components/Callout/index.jsx#L18

Hi there, I am using this package on my nextjs v12.2.0 , react v18.2.0, typescript v4.7.4 project. Node v14.17.0, npm v8.3.2
I have copy pasted the syntax found in the docs

Here is my code

It shows a typescript error. When I hover over the area there's an error this is what I get

What is the correct syntax for setting up code blocks markdown in nextjs and typescript

We should probably pull the ReadMe-side TOC styles in to this repo!

We are not able to add this in Next.js 14. Can you add support for react 18?

I installed the package on my nextjs 12, typescript 4.7.4 and tailwind 3.1.4 project. On initialising using the package, I get this error

error - ./node_modules/@readme/markdown/dist/main.js:3:0
Module not found: Can't resolve '@readme/variable'

Here is my code snippet

there's a red highlight on the code blocks but it shouldn't affect whether my code runs or not.
Please help,otherwise, I will have to look for some other way to present code blocks in tabs

If someone happens to have an API Reference page with the following Markdown with invalid CSS, the Markdown engine will currently fail, taking the rest of the Explorer component down with it.

<p style="font-size:15px;font-family=Lato, proxima-nova, Helvetica Neue, Arial, sans-serif;color: #001a00;text-align:justify;">Pickup location are required to be created from where pickup has to be done. One time pickup location can also be created through Warehouse creation API.</p>

All Markdown runs through the Explorer should be handled through a try-catch so if it fails, we just fallback to rendering plaintext.

The commonmark spec for code blocks allows indentation for code blocks. I'm pretty sure our implementation for tabbed code blocks does not.

If you try to use double curly braces within your markdown it seems to throw an error:

{{#if FirstName}}
  Hi {{FirstName}}
{{/if}}

This is because Angular continues to interpret this text post-render, and treats that above syntax as valid Angular code. I did this to fix it originally. But it seems the bug hath returned!

I'd like to be able to pass a configuration option into rdmd.html(text,options) that lets me turn off some of the sanitization. For example, I'd like to allow iframes and script tags.

https://github.github.com/gfm/#example-49

> JSON.stringify(window.RDMD.mdast("## "), null, 2)
"{
  "type": "root",
  "children": [
    {
      "type": "heading",
      "depth": 1,
      "children": []
    }
  ]
}"

Hello 👋

I'm trying to render some markdown content that I retrieved via the ReadMe API. My setup is pretty simple. Based off the example from the README, I have:

import rdmd from '@readme/markdown';

export interface Props {
  body?: string;
}

export default function Markdown({ body }: Props) {
  return <div className="markdown-body">{rdmd(body)}</div>;
}

In my project, when I render the Markdown component, I see the following error in the console:

I did some digging, and it looks like the version of vfile that gets rolled up into the build is at 4.1.1. In version 4.2.1, they added manual browser polyfills for path and process. I know I could change my webpack config to resolve the issue, but it'd be nice if this package was updated to pull in a newer version of vfile. All that would be needed is to run npm update vfile to update the resolved version in package-lock.json.

Our engineers are looking to create docs with diagrams and would like to use mermaid js (https://mermaid.js.org/). Is there any plans to add mermaid support to readme's markdorn engine or an alternative?

Looks good. A bit bummed about having to move image serialization back to the magic block format… any thoughts on a way to manage captions and sizing in RDMD-flavored syntax?

Originally posted by @rafegoldberg in #377 (review)

Commonmark Dicussions Forum

Back in February github added support for mermaid markdown: https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/

Is this mermaid support one of the plugins supported by Readme Markdown?

Per a few customer comments, top-level lists apparently have some margin styles (I think?) that are causing weirdness/conflicts with other CSS. Likely just @rafegoldberg just tryna' be fancy and fuc•ing things up in the process.

When I try to add this package to my project with
npm i @readme/markdown --save

First i have this error :

npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: [email protected]
npm ERR! Found: [email protected]
npm ERR! node_modules/react
npm ERR!   react@"^18.2.0" from the root project
npm ERR!   peer react@"16.x || 17.x || 18.x" from @readme/[email protected]
npm ERR!   node_modules/@readme/variable
npm ERR!     peer @readme/variable@"^15.1.3" from @readme/[email protected]
npm ERR!     node_modules/@readme/markdown
npm ERR!       @readme/markdown@"*" from the root project
npm ERR!   2 more (react-dom, @tippyjs/react)
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^16.14.0" from @readme/[email protected]
npm ERR! node_modules/@readme/markdown
npm ERR!   @readme/markdown@"*" from the root project
npm ERR!
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.

Then I add --legacy-peer-deps :
npm i @readme/markdown --save --legacy-peer-deps

The package I now installed but I have 5 vulnerabilities and before it was 0 :

npm WARN deprecated [email protected]: Use String.prototype.trim() instead
npm WARN deprecated [email protected]: Use String.prototype.trim() instead
npm WARN deprecated [email protected]: this package has been merged into graphql-language-service
npm WARN deprecated [email protected]: this package has been merged into graphql-language-service
npm WARN deprecated [email protected]: this package has been merged into graphql-language-service
npm WARN deprecated [email protected]: this package has been merged into graphql-language-service

added 189 packages, and audited 1414 packages in 9s

389 packages are looking for funding
  run `npm fund` for details

5 vulnerabilities (2 moderate, 3 high)

To address all issues, run:
  npm audit fix

Run `npm audit` for details.```

Then if I try `npm audit fix`  : 
```up to date, audited 1414 packages in 1s

389 packages are looking for funding
  run `npm fund` for details

# npm audit report

codemirror  <5.58.2
Severity: moderate
Regular expression denial of service in codemirror - https://github.com/advisories/GHSA-4gw3-8f77-f72c
fix available via `npm audit fix --force`
Will install @readme/[email protected], which is a breaking change
node_modules/codemirror
  @readme/syntax-highlighter  10.14.1 || >=10.14.3
  Depends on vulnerable versions of codemirror
  node_modules/@readme/syntax-highlighter
    @readme/markdown  >=2.4.0
    Depends on vulnerable versions of @readme/syntax-highlighter
    Depends on vulnerable versions of remark-parse
    node_modules/@readme/markdown

trim  <0.0.3
Severity: high
Regular Expression Denial of Service in trim - https://github.com/advisories/GHSA-w5p7-h5w8-2hfq
fix available via `npm audit fix --force`
Will install @readme/[email protected], which is a breaking change
node_modules/remark-parse/node_modules/trim
  remark-parse  <=8.0.3
  Depends on vulnerable versions of trim
  node_modules/remark-parse

5 vulnerabilities (2 moderate, 3 high)

To address all issues (including breaking changes), run:
  npm audit fix --force

This will downgrade the package and even after there are still vulnerabilities.

Can you help me on this ?

I readlly need to implement this package to fetch our documentation from Readme to embed in our website but can't do it if there is such vulnerabilities.

Currently, the RDMD engine handles pinned sidebar blocks in a somewhat hacky way: we always render the full doc content (pinned and non-pinned blocks alike), wrapping sidebar blocks in a <div.pin/> as we go. Then we use CSS to conditionally display these blocks depending on a few upper-level selector conditions.

This is a cheap solution and it'll hold quite well for now. But it complicates code block theming, makes React trees heavier, and opens us up to potential UI weirdness if someone decides to override our display styles. To get this working properly I think the steps would look something like:

• fork the rdmd.react processor export so it can return:
  • the entire content tree
  • only the main content tree
  • pinned sidebar content only
• update various RDMD React integrations
  • across the Explorer
  • in ReadMe

Originally here on readmeio/api-explorer#700

Let's add a previewText export method to the RDMD engine to loop through the AST and remove any non-paragraph nodes. Then we can transform that to plain-text, and do the truncation in the top-level method. So it'd look something like:

import remarkToPlainText from 'remark-plain-text';
import visit from 'unist-util-flatmap';

const pTagFilter = node => node.type==='paragraph' ? node : null);
//^Our custom p tag filter "plugin"; this is all
// pseudo code, but it works something like this!

export function previewText(text, truncateAt, opts = {}) {
  if (!text) return null;
  [text, opts] = setup(text, opts);

  text = processor(opts)
    .use(tree => visit(tree, pTagFilter))
    .use(remarkToPlainText)
    .use(rehypeStringify)
    .processSync(text)
    .contents;

  return text.slice(0, truncateAt).trim() + '...';
}

https://github.github.com/gfm/#emphasis-and-strong-emphasis

> JSON.stringify(window.RDMD.mdast("***strong** emphasis*"), null, 2)
"{
  "type": "root",
  "children": [
    {
      "type": "paragraph",
      "children": [
        {
          "type": "strong",
          "children": [
            {
              "type": "text",
              "value": "*strong"
            }
          ]
        },
        {
          "type": "text",
          "value": " emphasis*"
        }
      ]
    }
  ]
}"

Callout should clear floated elements on either side so they don't interrupt the block's inner content layout.

I set up TerserWebpackPlugin to run on our builds a while back, but for some reason the minified output would break the ReadMe app whenever I imported it!

https://github.com/readmeio/api-explorer/blob/67ebc1dde38871bee0c8127166ae3dd90668051d/packages/markdown/webpack.config.js#L18-L27

Didn't quite determine what was causing this issue, but we should get back to it ASAP so we can reenable minification.

If any spaces immediately following the ``` that should end a code block, it is not closed properly and it will include the subsequent code block section(s) in the document. It acts as if the the rendering engine only looks for a terminating line break immediately after the last grave accent. Perhaps trailing spaces should be trimmed before determining if it is a single code block or multiples.

This example shows how the rendering is affected with/without a trailing space: https://dashcore-anchortest.readme.io/docs/merged-code-block

Technical documentation features a lot of code blocks. We already allow authors to customize the base background and text colors for code blocks. We should extend this support to the complete syntax highlighting theme.

.markdown-body pre .cm {
  &-node        {  color:  var(--md-syntax-string,     #9c3328)  }
  &-tag         {  color:  var(--md-syntax-string,     #9c3328)  }
  &-string      {  color:  var(--md-syntax-string,     #b35e14)  }
  &-number      {  color:  var(--md-syntax-number,     #75438a)  }
  &-property    {  color:  var(--md-syntax-property,   #1d75b3)  }
  &-keyword     {  color:  var(--md-syntax-keyword,    #1d75b3)  }
  &-qualifier   {  color:  var(--md-syntax-qualifier,  #047d65)  }
  &-variable    {  color:  var(--md-syntax-var,        #047d65)  }
  &-variable-2  {  color:  var(--md-syntax-var-alt,    #ffffff)  }
  &-comment     {  color:  var(--md-syntax-comment,    #75787b)  }
  &-atom        {  color:  var(--md-syntax-atom,       #75438a)  }
  &-operator    {  color:  var(--md-syntax-operator,   #ffffff)  }
  &-def         {  color:  var(--md-syntax-def,        #ffffff)  }
}