Until now, the Retro Modules specification almost exclusively used YAML files. The files are human readable, but are not very user-friendly. The documentation has got to improve! The Retro Modules for Education project was created to specifically focus on making Retro Modules more accessible for educational institutions. Accurate & intuitive documentation is essential for this project to succeed. The specification should not only be easy to grok, but also have a significant set of learning materials & example projects.

Enter Markdown & Docusaurus

Markdown is a well-established markup language that is supported as the go-to documentation language. GitHub supports Markdown by default & will auto-format Markdown as HTML. Moving the specification to primarily use Markdown is a step in the right direction, but it will only go so far. Retro Modules really needs a fully-fledged documentation site complete with rich media tutorials, graphical guides & quality references to third-party systems. Docusaurus is an open-source framework which supports React components in Markdown files. Docusaurus will help provide a quality introduction to the Retro Modules specification.

Initial Migration to Markdown

The process has already started. Over the course of the last week I have created many new markdown files that temporarily refer to the legacy YAML files -- and have also refined the documentation for the main six connectors: DA-15, 2x8k16 Header, DE-9, 2x5k10 Header, DB-25 & the 2x13k26 Header. The changes are in a feature branch & will be merged into the main branch once the remaining Markdown updates are complete over the course of the next month or so. You can check out the changes by browsing the feature branch at retromodules.com/start!

Docusaurus Static Site

Migrating the Markdown files into the folder structure preferred by Docusaurus will be straightforward, but still a little time-consuming. At the outset, the Docusaurus site will likely use very few React components. Follow-up releases will start to introduce video-related & graphical components. As the application matures, interactive graphical components will become common -- to help further assist Makers new to the framework.

The Path Forward

For many years, retromodules.com has merely been a landing page that links to the specification & related social media sites. This has been necessary, given my focus on specification standardization & other very important priorities. Once the Docusaurus-driven documentation site is ready, it will become the default site you will see when visiting retromodules.com. As I develop the documentation site, I will be testing the limits of the Docusaurus framework & evaluate whether a dynamic site will be necessary. If so, the documentation site will be the static complement of the fully-dynamic retromodules.com site. Retro Modules Specification changes (which will be fewer & fewer, over time), would automatically update content on both the static Docusaurus-driven site & the dynamic site. Stay tuned!