Styling and docusarus markdown rendering not working

samducker commented 9 months ago

Have you read the Contributing Guidelines on issues?

[X] I have read the Contributing Guidelines on issues.

Prerequisites

[X] I'm using the 2.4.1 version of Docusaurus.
[X] I have tried the npm run clear or yarn clear command.
[X] I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
[X] I have tried creating a repro with https://new.docusaurus.io.
[X] I have read the console error message carefully (if applicable).

Description

Describe the bug

Currently the built in docusarus custom rendering of markdown is not working as intended. For example admonitions are not rendering and also codeblocks are not rendering with prism syntax highlighting.

I am unsure if this is related to the docusaurus-openapi-docs plugin or to docusarus itself but I have also posted an issue here and I hoped you could at least tell me why these issues may be happening so I can better debug it.

aka how does the docusarus markdown extensions work e.g. admontions and codeblocks with prism rendering.

OpenAPI Docs Plugin

Expected behavior

I expected the theme to display as per the demo docs, with for example the type of HTTP request next to each item in the api docs, and also for docusarus built in features like admonitions to continue to work.

Current behavior

Currently markdown renders but not the custom changes e.g. to admonitions or prism rendering, I presume this is to do with the preset-classic theme potentially not loading correctly since I implemented the openapi-docs plugin.

Screenshots

My package.json

{
  "name": "blink-docs",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "docusaurus": "docusaurus",
    "start": "docusaurus start",
    "tinastart": "tinacms start",
    "build": "tinacms build && docusaurus build",
    "swizzle": "docusaurus swizzle",
    "deploy": "docusaurus deploy",
    "clear": "docusaurus clear",
    "serve": "docusaurus serve",
    "write-translations": "docusaurus write-translations",
    "write-heading-ids": "docusaurus write-heading-ids",
    "typecheck": "tsc"
  },
  "dependencies": {
    "@docusaurus/core": "2.4.1",
    "@docusaurus/preset-classic": "2.4.1",
    "@mdx-js/react": "1.6.21",
    "@mendable/search": "^0.0.158",
    "@tinacms/cli": "^1.5.29",
    "clsx": "1.1.1",
    "docusaurus-plugin-openapi-docs": "^2.0.0-beta.3",
    "docusaurus-theme-openapi-docs": "^2.0.0-beta.3",
    "prism-react-renderer": "1.2.1",
    "react": "^17.0.1",
    "react-dom": "^17.0.1",
    "react-youtube": "^10.1.0",
    "swizzle": "^1.1.0",
    "tinacms": "^1.5.20"
  },
  "devDependencies": {
    "@docusaurus/module-type-aliases": "2.4.1",
    "@tsconfig/docusaurus": "^1.0.5",
    "typescript": "^4.7.4"
  },
  "browserslist": {
    "production": [
      ">0.5%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  },
  "engines": {
    "node": ">=16.14"
  },
  "overrides": {
    "react-live": ">=3.1.1 <4.0.0"
  },
  "resolutions": {
    "react-live": ">=3.1.1 <4.0.0"
  }
}

Reproducible demo

https://github.com/lucky-duck/blink-docs

Steps to reproduce

Try to run the project with

npm install npm start

Expected behavior

Admonitions and prism codeblock rendering and docusarus extensions of Markdown to work as intended

Actual behavior

Codeblocks render as normal markdown not with prism only way to get it to work is importing as a react component inside MDX.

Admonitions the same doesnt work with syntax like

:::tip

Text

:::

only works when imported as a react component

Your environment

Public source code: https://github.com/lucky-duck/blink-docs
Public site URL: https://blink-docs-two.vercel.app/
Docusaurus version used: 2.4.1

Self-service

[X] I'd be willing to fix this bug myself.

slorber commented 9 months ago

https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/ is not an official package.

If it doesn't work as intended then it's a bug in that package and should be reported to the package directly.

We can't resolve the problem by adding any code to Docusaurus. However I'm happy to help that package maintainer figure out a solution to fix the bug.

Some ideas you can give them:

If they use our mdx loader, they should add a admonitions: true | AdmonitionOptions loader option
They should probably apply @theme/MDXContent in their tree so that code blocks are rendered by our classic theme prism component

samducker commented 9 months ago

Hi @slorber

I attempted removing the plugin, and reseting to default and still had the same issues. So I believe it must be related to something else. Could you guide me on how I might be able to debug why this isn't working?

slorber commented 9 months ago

Hi @slorber

I attempted removing the plugin, and reseting to default and still had the same issues. So I believe it must be related to something else. Could you guide me on how I might be able to debug why this isn't working?

Show me a repro using docusaurus.new that only uses core Docusaurus packages (no openapi plugin dependency or any other third-party package) and where admonitions/codeblocks fail to render, and I'll be able to help you.

samducker commented 9 months ago

Hey Sebastian thank you for your reply.

I ended up rebuilding the project from scratch with the plugins template.

Which fixed my issue.

And managed to resolve the issues I believe it may have been to do with versions of packages although I am not totally sure it is mostly just a guess based on some prior issues I had which were resolved on this basis.

Could you explain to me how the custom docusarus MDX works so I can debug it in future if the same issue comes up?

On Thu, Sep 28 2023 at 9:42 am, Sébastien Lorber < @.*** > wrote:

Hi @slorber ( https://github.com/slorber )

I attempted removing the plugin, and reseting to default and still had the same issues. So I believe it must be related to something else. Could you guide me on how I might be able to debug why this isn't working?

Show me a repro using docusaurus.new that only uses core Docusaurus packages and where admonitions fail to render, and I'll be able to help you.

— Reply to this email directly, view it on GitHub ( https://github.com/facebook/docusaurus/issues/9323#issuecomment-1738723785 ) , or unsubscribe ( https://github.com/notifications/unsubscribe-auth/AF7VYSZTGYYMCSULJZ7KZ33X4UZ65ANCNFSM6AAAAAA46VKZVA ). You are receiving this because you authored the thread. Message ID: <facebook/docusaurus/issues/9323/1738723785 @ github. com>

slorber commented 9 months ago

Great 👍

Docusaurus uses MDX and register some default remark/rehype plugins for you.

The plugins registered can be different on a plugin-by-plugin basis so it's possible third-party plugins decide to use different plugins that the core plugins.

It's impossible to explain you everything about MDX in a comment like this, this is a complex ecosystem and you have to invest time to understand how it works.

And Docusaurus v3 (soon) comes with MDX v2, which brings quite a few changes to this ecosystem (for the better). Here's a preview of a blog post that will be published today: https://deploy-preview-9333--docusaurus-2.netlify.app/blog/preparing-your-site-for-docusaurus-v3/

facebook / docusaurus