Skip to content

Toolchain Migration to Redocly

Jump to bottom
Amarantha Kulkarni edited this page Feb 27, 2024 · 10 revisions

The XRP Ledger documentation and developer resources are available on xrpl.org.

The source for xrpl.org is available in the xrpl-dev-portal repository. While anyone can contribute to the xrpl-dev-portal repository, members of the XRPL.org Editors team in GitHub are maintainers of the xrpl-dev-portal repository.

At a high level, the current process of publishing documentation can be summarized by the following diagram:

image

There are a few challenges to the current toolchain that make it unsustainable in the long run, such as the risk of a single point of failure for the maintenance and future development of the toolchain used to publish xrpl.org and the lack of continuous integration and deployment.

By moving to a sustainable and viable toolchain, we can mitigate/avoid these challenges and thus help XRPL community contributors focus on creating more useful and relevant content to build on the XRPL.

Why Redocly?

The Redocly Developer Portal supports the docs-as-code workflow and offers a CI/CD service.

  • OOTB support for most developer docs features
  • Best-in-class support for API docs
  • Interactive code samples
  • Extensible and customizable through React components
  • Built-in workflows for CI/CD - commits merged to the production branch will be published to the site automatically.
  • Supports Markdown, familiar to developers & tech writers. Redocly supports Markdoc too.
  • Similar to the current experience, members of the XRPL.org Editors team will have access to the Redocly portal for admin tasks.

Migration Plan

The toolchain migration is a huge initiative and the implementation and onboarding for all stakeholders needs to be addressed in multiple phases. Issue #2131 tracks the overall toolchain migration initiative.

Phase 1: Migration plan and initial pass to migrate content

  • Draft migration plan
  • Initial pass to migrate content from xrpl-dev-portal to identify scripting and customization needs.
  • Update migration plan with tasks and estimated timelines.
  • Share the migration plan with stakeholders and incorporate any feedback.
  • Create scripts for identified tasks to migrate from Dactyl to Redocly
    • Sidebar information from dactyl.yaml to sidebar.yaml
    • Links (filename.html) in Dactyl to (absolute path/filename.md) in Redocly
    • Replace _snippets with partials
    • Move Japanese files to the i18n folder
  • Migrate About pages
  • Migrate Blog
  • Migrate Dev Tools
  • Generate redirects.yaml
  • Set up workflow and previews for work-in-progress content.
  • Onboard stakeholders to Redocly workflow.
  • Start documenting the contribution process and best practices to be used once migration is complete.

Phase 2: Build custom components and complete workflow and site optimization

  • Validate support for Japanese
  • Build custom components and implement new/revised designs
  • Integrate AI-based search bot
  • Site configuration/optimization to add data tracking, SEO optimization, site search config, etc
  • Add optimizations to the workflow such as link checker, style checker,

Phase 3: Test the preview site and publish PR to switch over to the Redocly-based site

  • Test sandbox site for production readiness.
  • Test site settings and verify that xrpl.org Editors have access to Redocly build logs.
  • Update contribution guidelines and publishing toolchain information
  • Publish PR for community review and acceptance
  • Small window of code freeze on master branch to reconcile branches and prepare to launch Redocly-based site.
  • DevOps tasks to switch over to new site (Update CNAME)
  • Decommission the old servers (NGINIX & Jenkins) once the new site is up and running for a few weeks
Clone this wiki locally