An Intro to Redoc: Choosing the Right Doc Solution
Reaction Commerce’s documentation section is our go-to information portal for both community members and core teammates alike—it also drives 30% of our overall traffic on any given month! Needless to say, it was super important for us to find the perfect solution to power our docs. So important, in fact, that we ended up building it ourselves.
The end result? Redoc. Redoc, which is short for "Reaction documentation redo," is a Meteor application and doc site generator, available as an open source project on GitHub for the Meteor community. Learn more about our project requirements, our experiences with existing doc site platforms, and how we ended up building our own custom solution.
While looking for the perfect solution, we put together a list of requirements that would point us in the right direction.
First and foremost, we wanted a doc site generator that could create pages with a clean, intuitive aesthetic, similar to the docs of Meteor, Stripe, or Twilio. The ability to create an elegant user interface was a must-have.
We also needed something that would accommodate the ability to pull from multiple source code locations. Reaction’s source code is distributed across multiple GitHub repos, with each repo containing very specific sets of documentation. At one point, the project documentation even lived in the same repo as the main code base. Our packages are also distributed via npm, so these package managers would require the addition of a readme.md file in the distribution.
Aside from these two pivotal must-haves, our wishlist also included:
- The ability to directly import markdown
- Table of contents manager
- Easy, automated content updates
- The ability to branch specific docs, eg. Master, Development, etc.
- A cohesive publishing workflow
- Search options
- API / Source linking
- SSR and SEO friendliness
Looking for the Right Solution
We tested out several solutions, but nothing quite met all our wishlist requirements. While a Jekyll solution supported multiple sources, we felt as if the overall tooling and workflow was too complex for updates that occurred several times daily. Readme.io had some beautiful templates, and was very easy to use, but it didn’t easily support multiple source locations. We followed in the footsteps of Meteor Guide, one of our favorite docs around, by trying out Hexo as a doc generator. We even went down StaticGen’s list of open-source site generators in search of the holy grail, but to no avail.
Metalsmith.io, a static site generator with lots of plugin features, was a pretty good fit, but the more we needed, the more custom code we had to write, which is often much more cumbersome when you aren’t writing the base yourself. So, we decided, in the end, to just write the whole app from scratch— what every developer secretly wants to do!
A custom Meteor application would provide us with the most flexibility as we grew, even if the first iteration didn’t fulfill our wishlist requirements from the get-go. We were also inspired by MDG, who was writing their own doc tool at the time, to release any of our custom solutions as an open source project to share with the rest of the Meteor community. Ultimately, we decided that a Meteor-based homegrown solution was the way to go.
How It Works
Redoc fetches raw markdown from multiple remote sources, such as the reaction-docs GitHub repository, and dynamically applies styling to all of the content, resulting in a clean and seamless table of contents page. Redoc can be initialized through multiple configurations— through an array of repos, a table of contents (TOC) array, or via folder structure.
Once all the markdown documents have been fetched from the sources defined in the TOC, Redoc takes the markdown content, applies styling, and parses links. This doc is then stored in a MongoDB collection and presented with React server side, rendering for maximum SEO friendliness.
Additional features of Redoc include:
- Search documentation
- SSR / SEO-friendly functionality
- Page aliasing and friendly URLs
- Gitter Sidecar chat integration
- Customizable themes
- Caching with adjustable refresh schedule
- Integration with Google Analytics
Powered by Redoc
So what’s the end result? A simple, scalable table of contents that can be skinned, themed, and custom-configured for any project, big or small.
Here’s Redoc in action at Reaction:
To see it live, visit Reaction Docs.
And here’s Redoc over at Rocket.Chat:
To see it live, visit Rocket.Chat Docs.
You can deploy Redoc through any of the deployment methods supported by Meteor, but we highly recommend using Docker. Docker allows users to bundle the dependencies of an entire deployment into one neat container, which can then be deployed onto ?any? server with Docker installed on it. Redoc provides several Dockerfiles to choose from, all of which are intended for a wide variety of use cases.
We use the Docker Cloud and Circle CI with a custom Stackfile to automatically redeploy whenever the Redoc code is updated. Users may also regularly update documentation on a configurable schedule, or even manually refresh the code themselves, depending on their needs.
For additional information on Redoc, visit Redoc via GitHub, where you may find example configuration files, which provide a step-by-step overview of our Reaction docs setup.
We’re always open to contributions and feedback from the community as well, so if you have any questions, comments, or suggestions, feel free to visit our forums.