Path to Docusaurus 3

[akeller]

Description

This is my mess. You can join me here, or tackle things piecemeal. Related to #2719.

When should this change go live?

• This is a bug fix, security concern, or something that needs urgent release support.
• This is already available but undocumented and should be released within a week.
• This on a specific schedule and the assignee will coordinate a release with the DevEx team. (apply hold label or convert to draft PR)
• This is part of a scheduled alpha or minor. (apply alpha or minor label)
• There is no urgency with this change and can be released at any time.

PR Checklist

• My changes are for an already released minor and are in /versioned_docs directory.
• My changes are for the next minor and are in /docs directory (aka /next/).

• My changes require an Engineering review, and I've assigned the Engineering DRI or delegate.
• My changes require a technical writer review, and I've assigned @camunda/tech-writers as a reviewer.

[github-actions]

👋 🤖 🤔 Hello, @akeller! Did you make your changes in all the right places?

These files were changed only in docs/. You might want to duplicate these changes in versioned_docs/version-8.6/.

• docs/self-managed/modeler/web-modeler/configuration/configuration.md

You may have done this intentionally, but we wanted to point it out in case you didn't. You can read more about the versioning within our docs in our documentation guidelines.

[akeller]

In the API spec .mdx files, it looks like <div>'s are opened but not closed.

Error: MDX compilation failed for file "/Users/amara/Projects/post-86/camunda-docs/versioned_docs/version-8.6/apis-tools/zeebe-api-rest/specifications/unassign-a-user-task.api.mdx"
Cause: Expected a closing tag for <div> (39:548-39:553) before the end of paragraph
Details:
{
"column": 1,
"message": "Expected a closing tag for <div> (39:548-39:553) before the end of paragraph",
"line": 39,
"name": "39:1-39:553",
"place": {
"start": {
"line": 39,
"column": 1,
"offset": 2630,
"_index": 0,
"_bufferIndex": 0
},
"end": {
"line": 39,
"column": 553,
"offset": 3182,
"_index": 1,
"_bufferIndex": -1
}
},
"reason": "Expected a closing tag for <div> (39:548-39:553) before the end of paragraph",
"ruleId": "end-tag-mismatch",
"source": "mdast-util-mdx-jsx"
}

[akeller]

Apparently, prettier went to the past...

[akeller]

The deploy tag produces a different issue, the version of Node is old. That's not what I get on my local machine, instead I experience this:

Screen.Recording.2024-11-06.at.2.17.17.PM.mov

[pepopowitz]

In the API spec .mdx files, it looks like <div>'s are opened but not closed.

Error: MDX compilation failed for file "/Users/amara/Projects/post-86/camunda-docs/versioned_docs/version-8.6/apis-tools/zeebe-api-rest/specifications/unassign-a-user-task.api.mdx"
Cause: Expected a closing tag for <div> (39:548-39:553) before the end of paragraph
Details:
{
"column": 1,
"message": "Expected a closing tag for <div> (39:548-39:553) before the end of paragraph",
"line": 39,
"name": "39:1-39:553",
"place": {
"start": {
"line": 39,
"column": 1,
"offset": 2630,
"_index": 0,
"_bufferIndex": 0
},
"end": {
"line": 39,
"column": 553,
"offset": 3182,
"_index": 1,
"_bufferIndex": -1
}
},
"reason": "Expected a closing tag for <div> (39:548-39:553) before the end of paragraph",
"ruleId": "end-tag-mismatch",
"source": "mdast-util-mdx-jsx"
}

I can't find this comment anywhere, but I swear I left it on one of these issues --

All of these errors in the API specs will be resolved when we can update the API generator & regenerate these docs. I've confirmed locally.

I hope you don't mind, I'm going to regenerate them on this branch and push up, to try to move this forward.

[pepopowitz]

The deploy tag produces a different issue, the version of Node is old. That's not what I get on my local machine, instead I experience this:

Screen.Recording.2024-11-06.at.2.17.17.PM.mov

#4667 bumps node to the current lts version in the .nvmrc (for people who use version managers locally), and each of the workflows that specify a node version. This should hopefully help?

[pepopowitz]

The deploy tag produces a different issue, the version of Node is old. That's not what I get on my local machine, instead I experience this:

This is interesting, I hadn't noticed that the preview environment workflow doesn't specify a node version. I'll update it to do so, and include it in #4667.

[pepopowitz]

I can't find this comment anywhere, but I swear I left it on one of these issues --

All of these errors in the API specs will be resolved when we can update the API generator & regenerate these docs. I've confirmed locally.

I hope you don't mind, I'm going to regenerate them on this branch and push up, to try to move this forward.

Eeeehhhhh I decided I didn't want to throw a bunch of junk into your PR, so I opened my own, into this branch, at #4669.

Two things I learned from that, which are necessary during the upgrade:

• I forgot that we need to convert the older version specs too 😭. We don't generate these; they become basically "hardcoded" when we cut each version. I think this will involve tracking down the exact spec at the time of cutting each version, each API, and hacking the regeneration process to put things in the correct place.
• We'll need to rewrite the DocItem/Metadata and DocCard components. They both use the useDoc hook from the base theme, but that is no longer exposed to us by docusaurus. I'm guessing it's not simply pointing at a different place, but probably figuring out a suitable replacement function to use, and identifying if we can still accomplish the things we were doing in those components.

[akeller]

@pepopowitz I mentioned this on your PR, but the likelihood of me getting back to this work before the end of the year is zero at this point. You can repurpose this PR or close it out, but I won't be able to get to it.

[pepopowitz]

Ok! I hope to make progress on it before the end of this year, so I will take it over. I'll look at it this week and decide if I want to start over or update this PR based on main.

[pepopowitz]

Closing in favor of #4781, and I'll take this work over.