Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Docs] Upgrade Docusaurus to v3 #6386

Merged
merged 9 commits into from
May 10, 2024
Merged

[Docs] Upgrade Docusaurus to v3 #6386

merged 9 commits into from
May 10, 2024

Conversation

Disorrder
Copy link
Contributor

Pull Request Template for OpenBB Developers

  1. Why? (1-3 sentences or a bullet point list):

    • To improve security with latest patches
  2. What? (1-3 sentences or a bullet point list):

    • Upgrade all docs dependencies
  3. Impact (1-2 sentences or a bullet point list):

    • Decrease amount of dependabot warnings
  4. Testing Done:

    • Manually walked through pages and compared with prod version
  5. Reviewer Notes (optional):

    • Any specific focus areas for review?

    • Example: "Please check algorithm compatibility with existing data models."

  6. Any other information (optional)

Docusaurus 3 Upgrade

I've upgraded Docusaurus to v3 and there're some breaking changes affecting us:

See Docusaurus breaking, MDX 2 breaking and MDX 3 breaking for more info

  • Prefer .mdx format over .md. .md still works, but .mdx has more integrations, features and slightly different validation.
  • If you're using VSCode, please install MDX and ESLint plugins for linting.
    Probably, we can setup another linter later.
  • MDX Playground is your new friend
  • Validate mdx files with this tool:
npx docusaurus-mdx-checker
  • require modules is not supported any more, use ESModules instead

Coding

  • Auto links doesn't work any more, use standard MD links instead
<http://openbb.co> ❌ Error
[http://openbb.co](http://openbb.co) ✅ Valid
  • Don't open multiple tags on one line:
❌ Error
<details><summary>How do I select commands instead of typing?</summary>
. . . More details
</details>

✅ Valid
<details>
  <summary mdxType="summary">How do I select commands instead of typing?</summary>

  . . . More details (1 empty line above is mandatory)
</details>
  • Screen the braces with backslash or wrap into code block
{stars,forks}    ❌ Error
\{stars,forks\}  ✅ Valid
`{stars,forks}`  ✅ Valid
{ 1 + 2 }        ✅ Valid, returns 3
  • Always wrap math equations into $ _ $ or $$$ for multiline block
$D_{i,j} = \sqrt{(1-\rho^{distance}_{i,j})}$
  • If you're using katex in tables, there're 2 options:

a. Make sure your formula is not using |. Screening it with backslash works, but cause glitches

| Column A        | Column B                                         |
| --------------- | ------------------------------------------------ |
| Math formula is | $D*{i,j} = \sqrt{(1-\|\rho^{pearson}\_{i,j}\|)}$ |

b. Use HTML tables

<table>
  <tr>
    <td>Column A</td>
    <td>Column B</td>
  </tr>
  <tr>
    <td>Math formula is</td>
    <td>$D*{i,j} = \sqrt{(1-|\rho^{pearson}\_{i,j}|)}$</td>
  </tr>
</table>

@github-actions github-actions bot added docs Code documentation excel labels May 10, 2024
@Disorrder
Copy link
Contributor Author

Duplicate of #6378. Just renamed branch for Github Actions

@IgorWounds IgorWounds added this pull request to the merge queue May 10, 2024
Merged via the queue into develop with commit 5bd4ae0 May 10, 2024
17 of 20 checks passed
@IgorWounds IgorWounds deleted the docs/docusaurus3 branch May 10, 2024 11:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants