-
Notifications
You must be signed in to change notification settings - Fork 1.1k
Redocly Migration Scripting and Pre‐Migration Moves
For the migration to the Redocly toolchain, there are several cases where Redocly needs things to be in a different format or syntax than they currently are.
There are three strategies we can use to make these changes, on a case by case basis. In order from most to least preferable, they are:
-
Adapt the current site to a format that's compatible with both tools.
- "Remove" Variant: Remove any Dactyl-specific syntax and switch to something plainer that both can handle.
- "Shim" Variant: Implement a quick Dactyl plugin site so that it's compatible or mostly-compatible.
-
Script a tool that can quickly apply sweeping changes from the Dactyl format to the Redocly format starting from basically any commit. Instead of committing the changes to the Redocly branch and copying work over, we commit the script to the main branch.
- "Extend" Variant: We implement something in Redocly that is a close analogue of what Dactyl supports, and the script does a find-and-replace from old→new syntax.
- Manual changes on a Redocly migration branch, which would have to be kept up-to-date and in-sync over a potentially extended period of time. In many cases we can assume that scripted / shimmed changes above may cover 90% of the work and manual changes can be applied as a last step during a code freeze just before the final migration.
Rather than forking once and having to keep the branches in-sync for a long time, it should be less friction to make a series of incremental changes to make the master branch more "Redocly-ready" while still maintaining compatibility with the current Dactyl site. Some of these changes may involve a large changeset, but by keeping each one constrained to one category of change and having the PR open only a couple days at most should reduce the impact and migration pain of any individual step.
| Approach: | Adapt |
|---|
The Dactyl-based site currently uses a convention where translated pages are {file}.ja.md in the same dir as the English versions. Redocly needs these to be under @i18n/ja/ in a parallel folder structure and named {file}.md.
The key is that Dactyl doesn't actually need the md files to follow any specific filename/folder structure. I think we can do one update to put them under an @i18n/ja folder without any breaking changes to how Dactyl handles them; this would only be a small, one-time disturbance to translation efforts and then they could resume and the files would already be in the right place for when we're ready to flip the switch to Redocly.
| Approach: | Adapt & Shim |
|---|
The Dactyl site uses relative links in the form {file}.html in most places. Redocly links can either be a relative path to the source file or an absolute path to the output path. I already have a Dactyl plugin that finds links in the current Dactyl pages and converts them into the format Redocly expects; I believe it would be pretty straightforward to reverse the logic, so we could change the links once to a format that's compatible with Redocly, and just have a Dactyl plugin subbing those links back to their existing values (on-build) until we're ready to move. The only exception would be any links from snippets, but that's a much smaller set of things to keep in sync.
| Approach: | Adapt |
|---|
The Dactyl site has a bunch of auto-generated landing pages that contain just a list of children with blurbs for each; these are defined in the config file but don't generally have any representation in the filesystem. Redocly recently added some tooling to do something similar, but it still needs the files to have an index.md file (or something like it) in the filesystem where the landing goes.
We can create (largely empty) index.md pages for the current Dactyl site, and move the properties from the dacyl-config.yml to those pages' frontmatter, which would still generate the exact same site at build time. This move can be done once via a script. Having these index.md pages in place would help with making links that will port cleanly to Redocly, and the final conversion to Redocly would involve a smaller/simpler one-time change to each of these files (which can also be scripted).
| Approach: | TBD |
|---|
Redocly currently reads snippet files (even if the folder and/or file name starts with _) and throws errors if they contain broken links. Also, any link paths in these snippets are relative to the snippet location, not to where the files are being built in the end.
In our meeting on 2023-09-28, Roman said they may implement improvements to snippets/partials "this week", so I'd like to wait to see what changes they implement before deciding on migration steps. But if it involves renaming files to have an underscore, we can move and then find-and-replace the files without breaking Dactyl's compatibility.
| Approach: | Adapt & Remove |
|---|
This is one of a few cases where we use {{ variable }} syntax in the current docs. Redocly has {% $variable %} syntax but which variables it provides in which contexts doesn't quite line up with Dactyl's.
Most instances of {{currentpage.name}} in the existing docs are extraneous and we can actually just remove them. (For example, the header "AccountSet Flags" could just be "Flags" because it's already on the AccountSet page.) This will change/break some links, but we can add <a id='old-anchor-name'></a> tags to keep the old URLs functional if we need to.
| Approach: | TBD. Script & Extend / Adapt & Remove |
|---|
Another case where we use {{ variable }} syntax is the {{ include_svg(...) }} macro. We can probably implement a Component that does something very similar and get the benefits of the current approach (theme-aware diagrams).
| Approach: | Script & Extend |
|---|
Redocly has already implemented a Component that does most of this, but currently it only does line numbers, not "starts_with" and "end_before". Roman promised he would add those, so then we could make a simple find-and-replace script to convert from the existing syntax to the Redocly equivalent.