readmeio/markdown

ReadMe's flavored Markdown parser and React-based rendering engine.

markdown's Issues

Code Syntax Theming

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.

CSS-Based Themes

Using syntax selectors & highlight variables to override the default 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)  }
}

Issues

• lots of manual Custom CSS config required (still, it's better than some of the crazy things I've seen done to get this working though!)
• will revert to default theme in older browsers (without a polyfill at least!)

Don't insert <br> on new lines when syncing markdown

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.

Quoted tabbed code blocks???

Module not found: Can't resolve '@readme/variable'

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

SECURITY: High Severity Vulnerability

┌──────────────────────────────────────────────────────────────────────────────┐
│                                Manual Review                                 │
│            Some vulnerabilities require your attention to resolve            │
│                                                                              │
│         Visit https://go.npm.me/audit-guide for additional guidance          │
└──────────────────────────────────────────────────────────────────────────────┘
┌───────────────┬──────────────────────────────────────────────────────────────┐
│ High          │ Regular Expression Denial of Service in trim                 │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Package       │ trim                                                         │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Patched in    │ >=0.0.3                                                      │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Dependency of │ @readme/markdown                                             │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Path          │ @readme/markdown > remark-parse > trim                       │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ More info     │ https://npmjs.com/advisories/1700                            │
└───────────────┴──────────────────────────────────────────────────────────────┘

Markdown syntax for images that supports sizing and captions

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

Clear callout blocks.

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

Syntax for setting up code blocks in nextjs & typescript

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

Run Markdown through a try-catch in the Explorer

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.

React processor throws "ReferenceError: process is not defined"

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.

Feature request: allow sanitization configuration

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.

Split pinned content in React processor.

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

Security issue in dependencies

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.

Should tabbed code blocks allow an unclosed code block?

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?

Should tabbed code blocks allow indentation?

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

Normalize list indentation.

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.

Should allow blank headers of depth greater than 1

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

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

Integrate TOC styling

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

Plain-text "summary" RDMD export method.

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() + '...';
}

Markdown code block closing incorrectly

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

Minify RDMD production builds.

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.

Mermaid.js Support

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?

Should handle strong emphasis correctly

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*"
        }
      ]
    }
  ]
}"

Pinned callout blocks lose data.

Asana

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

Are mermaid style diagrams supported?

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?

Investigate double curly-brace errors.

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!