-
-
Notifications
You must be signed in to change notification settings - Fork 190
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
feat: Docs vNext (Docusaurus Migration) #2793
Conversation
Deploying with Cloudflare Pages
|
Notes for live code researchIdeal DX: write TS code files that are compiled alongside MDX files, and can be embedded, with live code + preview. Approach: StorybookI believe Storybook will get us that but the challenge is that the build pipeline is separate. However, it feels possible to integrate Storybook's build as a Docusaurus plugin.
Results As of b42edc1 I got SB integrated as a plugin, with a side-by-side dev server. I think it will be too tough right now at least to get seamless SB integration working. The issue is that the Storybook dev server and compilation pipeline is tightly coupled. Unlike Typedoc, we can't just call an easy API to get JSON back to do custom rendering. Plus I'd need to basically rebuild all the UI even if we did. I also question whether we may need SB if we can get a playground working properly. Because then all we really "need" is the "Controls" support SB provides and we can write that ourselves or build it into the docs. Approach: react-liveDocusaurus already provides a theme plugin for live-code via React Live. You can then use the This means we would write snippets in TS, compile them, and they would be interactive and live at runtime. As of bd7d7a0, this POC approach is working. Downsides
Results Seems workable. To mitigate the embedded canvas, I believe we could house the Approach: Shiki TwoslashThere's a library called Shiki Twoslash which actually renders TS compiler annotations (and errors!), including snippets and highlighting. There's a docusaurus plugin as well. Issues
Results Update 1: I could not easily integrate the Docusaurus plugin with v3; I was running into errors. Even if I did, we don't get live editing. However, just having the annotations would be really nice for static snippets, so I will still play with this and see if we can't get it to work for static code. Update 2: As of 647916a, I was able to get Shiki Twoslash working with static code blocks! There is a possible issue with Approach: StackBlitz SDKhttps://developer.stackblitz.com/platform/api/javascript-sdk Pros
Issues
Downsides
Results As of 5d84603 StackBlitz is integrated and working with multiple examples on a page (Actors) as well as image assets (Animations). This could be a very good approach, if we can figure out how to make local code edits a bit more seamless. Approach: SandpackThanks to this blog post by Josh, Sandpack could be an option -- but like most of the live playgrounds, it is optimized for JavaScript, not TypeScript. Sandpack uses CodeMirror 5 (?) but there is an LSP integration that in theory would work with the TS LSP in the browser. I'd need to manually hook it all up. This is what the new React docs uses. Pros
Issues
Approach: Bright (CodeHike)This might need to be supported by Docusaurus directly, but: Does support extensions, which presumably would let us inject live editing if we want (plus build other extensions specific to excalibur) |
…kamranayub/docs-vnext
@kamranayub MERGED! 🎉 🎉 🎉 |
===:clipboard: PR Checklist :clipboard:===
==================
Closes excaliburjs/excaliburjs.github.io#383
Preview Site
👉 https://excaliburjs.pages.dev/
Local Dev
Changes:
site/
directory to hold Docusaurus siteTask Tracking
Foundations Phase
Everything that will enable the full migration to work
Note
replaced with AdmonitionsCodeSandboxEmbed
IFrameEmbed
Example
storybook embedembed:
snippets (Live Code?)Integrate TailwindDocs Buildout Phase
Site Buildout Phase
Notes
Separate tooling: Right now the
site
directory is managed separately from the rest of the engine package building. I may explore unified tooling using a monorepo approach, but it will require moving folders around + redoing all the build tooling. If we move Docusaurus to run/build from the root of the repo, there are some conflicts with thebuild
temp directory, as well asdocs
directory andsrc
directories. We'd have to change those and I haven't looked into it yet.Cloudflare root directory: Since the Docusaurus build needs to reach into other parts of the repo (hello Typedoc), I was getting errors when I set the Pages build root to
site
. I had to remove that and then modify the build command tocd site && npm ci && npm run build
so the build takes longer. It'd be great not to have to (but we may need to do that if we cannot access the repo files outside thesite
dir).Initial build doesn't link symbols:Fixed. Since the docusaurus-plugin-typedoc-api runs as a plugin lifecycle, and we need the.json
Typedoc file as input into thedocs.remarkPlugins
config, it has to wait until the first successful build to get the JSON. I am not sure if there's a way to fix this without modifying the other plugin. 🤔Custom symbol link builder: I had to patch my https://github.com/kamranayub/remark-typedoc-symbol-links package to support custom link building since it was hardcoded to Typedoc paths. I could extract this into a npm package perhaps. It would be ideal to bake it into docusaurus-plugin-typedoc-api though 🤔 Not sure how to handle the remarkPlugin piece with
@mdx/loader
.Integrated Storybook build: Previously we had to run
npm run visual
ornpm run build-storybook
to work with Storybook examples. I have a POC that adds direct dev server + build integration with Docusaurus so everything happens in one "experience." This will move SB to thesite
directory instead of the root, keeping things tidy. It will also allow us to move the stories into theexamples/
folders withindocs
, making story creation even more seamless. There is some uncertainty with how the SB dev server will interact with the Docusaurus dev server, and process file handles, exiting gracefully, etc.