📘

What is the Owlet Weekly Update?

Welcome to the second edition of the Owlet Weekly Update (working title) — an owlet-sized update (posted every Tuesday to the ReadMe Changelog) where we provide an overview of the bug fixes and minor improvements that went out as part of our new Tuesday release cycle.

As we refine our format and process for providing these updates, we'd love to hear what you think at [email protected]!

Bug Fixes and Minor Improvements

• Last week, we inadvertently introduced a bug where users were unable to save their changes to a page if making edits in Raw Mode... yikes! Happy to report that bug has been fixed 📝
• Fixed an issue for a small chunk of projects where certain internal documentation links were broken in the Changelog 🔗
• A small portion of projects were seeing an issue where they specified a Main URL that was different from ReadMe, but clicking the project logo navigated to their ReadMe landing page instead... this issue is now resolved! 🏠
• There was this pesky little issue when editing unpublished pages in the API Reference section where the preview links were inconsistent depending on where you clicked... that discrepancy has been fixed! 🧑‍🎨
• General stability improvements to ReadMe Free 💸
• Minor performance benchmarking improvements 📈

Bigger Feature Updates and Improvements

• We recently released an NPM module called api which makes it easier than ever to generate an SDK from an OpenAPI file 🚀 stay tuned for more info on how to integrate api-powered code samples into your ReadMe documentation!

📘

What is the Owlet Weekly Update?

Welcome to the inaugural edition of the Owlet Weekly Update (working title) — an owlet-sized update (posted every Tuesday to the ReadMe Changelog) where we provide an overview of the bug fixes and minor improvements that went out as part of our new Tuesday release cycle.

As we refine our format and process for providing these updates, we'd love to hear what you think at [email protected]!

Bug Fixes and Minor Improvements

• Performance and stability improvements to our new Markdown engine in the Changelog. 📝
• Fixed an issue where a small portion of our Enterprise customers were seeing a confusing redirect when logging out using our Custom OAuth flow. 🔐
• Fixed a bug where search engines could not access robots.txt for private projects. 🤖
• And last but not least... improvements to our release tracking process, so we can provide you with updates like these! 🚀

Bigger Feature Updates and Improvements

Search Improvements

We shipped some huge improvements to our search, including:

• Better search box design
• Improved indexing querying

Be sure to check out Marc's blog post for some background on our design and product development process.

ReadMe Free

We also released a new free plan! We’ve noticed that many companies come to us with only a Swagger/OpenAPI file or a simple list of endpoints. They don’t have the technical design resources or the time to build a full-featured developer hub, let alone an API Reference.

There are a lot of open source tools out there to build an API Reference, some better than others. We want everyone to have the option to use the best-in-class option available without worrying about its cost or added development effort. Our new free pricing tier was created to allow everyone to build a beautiful API Reference section at no cost.

We've released a big update to our syntax highlighting capabilities today to allow for the support of the following languages:

• CoffeeScript
• Clojure
• D
• Erlang
• Groovy
• Handlebars
• HTTP
• Julia
• LESS
• Perl
• Rust
• SASS
• YAML

Check out our Markdown engine documentation at https://docs.readme.com/rdmd/docs/code-blocks#language-support for the full list of languages we support, and how you can utilize them!

We have released a beta for PDF generation for our enterprise clients! (See a sample here)

We currently build the PDF from the guides section of your projects

How do you use it?

You can request to build a PDF by navigating to the "Versions" page of your project. If you are an enterprise customer, you'll be able to see the "Build PDF" link. Once we've built the PDF, there will be a "Download PDF" link that you can use to retrieve the document.

We've templatized the global landing page! You can build out or update your global landing page to use content from your docs! You can now refer to categories, pages, the selected language, and other data dynamically.

Check out our docs on how to get started here!

Today we released a new major version of our API Explorer! This release has been months in the making, and adds support for some highly requested features, fixes a ton of bugs and oddities, and more!

allOf Support

This release adds allOf support in both the request and response to our API Explorer! This has been one of our most requested features at ReadMe, and we are very excited to finally release it!

Now no matter what the structure of your request body, ReadMe will do the correct thing and render the parameters as you would expect.

You can read more about how you can take advantage of allOf in OAS here: https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/#allof

Our goal is to be as compliant to the OpenAPI Spec as possible, and this brings us significantly closer to that goal.

Error Handling

We’ve also added improved error tracking, so we can more easily be notified when an error occurs in the Reference section. When an admin is logged in, all errors will have a unique id that our Support Engineers can use to help debug the issue and get everything running smoothly again.

And much more…

To view the full list of detailed changes, you can view our changelog in the open source API Explorer repo: https://github.com/readmeio/api-explorer/blob/master/CHANGELOG.md

Last week, we migrated our application cache layer under Cloudflare's proxy umbrella! We already take advantage of their certificate management solution, so the next logical step was to move other pieces of our infrastructure into the same place.

TLDR

Our cache now serves more content and from a wider variety of edge locations! Across the board, all unauthenticated web traffic should see performance increases.

From Homegrown to Managed

Prior to migrating this cache layer, we owned a self-managed implementation consisting of a set of Nginx caches sitting behind a classic load balancer in AWS. All of the traffic going to our hubs (via standard ReadMe domain, or custom DNS), routed through this layer before settling at our origin servers.

Ultimately, there were a few drawbacks:

• Request Protection: We built this a few years ago, so our implementation did not take advantage of some of the Web Application Firewall features AWS has introduced since. As a result, this layer did not have modern content firewall or DDOS protections.
• Scaling: This layer, although programmatically scaled behind our load balancer, was a bottle neck. We could only scale it in and out so much.
• Access Control: We were not able to dial in access control to the level we desired.

Thankfully, moving to a managed solution alleviated all of these issues! We now have extensive firewall and DDOS protections, that are seamlessly scaled and customizable.

Performance Improvements

From a functional perspective, caches store data in-memory. This allows for a metadata to dictate whether desired information is pulled from a very easily accessible source, or be fetched from the origin (which can take longer). Of course, our previous implementation did this, in part. But, it did it from a set of locations that were not optimized for where the web traffic came from.

We are now caching more, and doing so at edge locations near you. That means that any cached pages that are accessed are closer to you, and to your customers. Because distance travelled is reduced, latency is drastically reduced, and content is served faster!

You can now receive notifications for activity on your ReadMe project in your Slack workspace 🎉 this integration supports the following types of notifications off the bat:

• Suggested Edits: when someone suggests new edits to your project
• Discussions/Support Forums: when someone asks a question in your project's Support Forums

To connect your ReadMe project to your Slack workspace, go to your Project Integrations on ReadMe (Configuration > Integrations), and click the Add to Slack button:

For the latest information on setup and configuration, please see our knowledge base.

Earlier this year, we purchased the readme.com domain for our homepage. Starting today, the ReadMe dashboard is accessible at dash.readme.com!

We recommend updating your bookmarks and password managers to this domain today. The dashboard is still accessible via the old domain (dash.readme.io), but we'll begin redirecting starting next week.

The ReadMe API will still be accessible via https://dash.readme.io/api/v1 for the foreseeable future.

If you have any questions, please contact us at [email protected].

As part of the rollout of the Changelog and Custom Pages API, we had initially required a x-readme-version header. The Changelog and Custom Page objects are not versioned the same way that they are for standard Guide and API Reference pages and it created problems with existing data in the dashboard, so all versioning has been removed from these sets of endpoints.

Going forward, the x-readme-version header is no longer required for the Changelog and Custom Pages API. If you have any questions, please contact us at [email protected].