Happy Tuesday folks! This edition of the Owlet Weekly Update is dedicated to my mother, who is celebrating her birthday today. 🎉 Feel free to tweet at us with your birthday shoutouts using the hashtag #happybirthdaykanadsmom!

We have some exciting updates to our API Explorer, our Suggested Edits workflow, and lots more. Details below! 👇🏽

Bigger Feature Updates and Improvements

• Building off our Cookie-filled announcement from a few weeks ago, the API Explorer now supports Cookie Authentication! (See a demo here.) 🍪
• Say goodbye to broken links when you change slugs in ReadMe! 🔗 Now, when you update the slug on a Guides or API Reference page, links to the old slug will magically redirect to the new slug! ✨
• This wouldn't be a true Owlet Weekly Update without a mention of our massive Search improvements! We're continuing our gradual (emphasis on gradual) rollout to even more projects. As always, we'd love to hear your feedback—let us know at [email protected]! 🔍
• Suggested Edits is one of my favorite features within ReadMe. If you’re anything like me when reviewing suggested edits, your review process generally entails reading the raw Markdown diff in the suggestion, closing your eyes, and imagining what these changes look like in the documentation. 🌀 Well I’ve got wonderful news for those of you that don’t share my vivid imagination. Suggested Edits now has a Preview button! 👀

Bug Fixes and Minor Improvements

• A few weeks ago, we fixed a bug where users were unable to save their changes when making edits in Raw Mode. Turns out this was an issue with the Custom Pages as well. Happy to report that it's now fixed! 📝
• Now that data actually loads in Documentation Metrics, we discovered another bug where clicking to see additional info wouldn't even load that data. Sorry about that, folks. This issue has now been fixed! 👥
• Fixed an issue with our Segment Analytics integration where, for certain projects, it was only tracking initial page loads. 📈
• A small portion of projects may notice some speed improvements during the initial load of the ReadMe project dashboard. 🚀
• Various security and access improvements for projects that use both SAML and ReadMe login. 🔐
• Improvements to how our API Explorer code snippets handle application/x-www-form-urlencoded payloads. 📦
• Minor styling improvements to our api code snippets in the API Explorer. 💄
• Even more backward-compatibility improvements to the ReadMe Markdown engine. ⏪

Thanks again for reading and for being a part of the ReadMe community (and happy birthday mom)!

—Kanad and the ReadMe Team

📘

What is the Owlet Weekly Update?

Thanks for tuning in to another edition of the Owlet Weekly Update —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]!

Happy Tuesday (and last day of June... 🤯), everyone! Last week was a short week for all of us at ReadMe — we spent Thursday and Friday at our summer "offsite." I'm putting "offsite" in quotes because we normally do our offsites in person, but this one was fully remote due to the pandemic... but despite the circumstances, we had a great time! Check out our latest Instagram post to see what we were up to. 👨🏽‍🎨

Despite the short week, we shipped a lot of exciting improvements to the navigation bar, Documentation Metrics, and more. Plus, our project is officially using the new Search improvements! Check out our project and hit ⌘ (or Ctrl)+K to see it in action!

Read onward to get the details on all of this. 👇🏽

📘

What is the Owlet Weekly Update?

Welcome to the fourth 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

• Enterprise projects were unable to load certain parts of the Documentation Metrics platform in the dashboard... yikes! Happy to report that the data is loading properly now, and that you can finally get back to learning about your documentation visitors again! 📊
• Certain projects were briefly unable to take advantage of the huge behind-the-scenes improvements to our Search feature. Those projects can now take advantage—search away! 🔥
• Improvements to how the ReadMe Markdown engine renders content in the Changelog. ✏️
• We were seeing an issue in Safari where certain API reference sections were getting cut off. That issue is now fixed! ✂️
• Some minor style fixes to the new Search design. 🎨
• Several small backward-compatibility improvements to the ReadMe Markdown engine. ⏪
• Various small linking fixes for enterprise projects. 🔗
• Loading improvements for API logs in the API Reference section. ⚡
• A couple of small style improvements on mobile (which you may have noticed if you're reading this post on your phone!). 📱

Bigger Feature Updates and Improvements

• You may have noticed in the last week or so that we made some design improvements to our navigation bar, which should drastically simplify project navigation! Check out our docs for information on how to enable these improvements on your project. 🧭
• One of these days, I'm going to stop mentioning our massive Search improvements... but today is not that day! We've been gradually rolling these beautiful visual updates over the last few weeks, and we're continuing that rollout to some more projects today (including ours)! Let us know what you think of the changes at [email protected]! 🔍

Thanks for reading and for being a part of the ReadMe community! —The ReadMe Team

📘

What is the Owlet Weekly Update?

Welcome to the third 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

• We've been seeing an issue affecting projects with site-wide passwords where authenticated users were having troubles accessing these projects. Happy to report that this has been resolved! 🔐
• Fixed an issue affecting a small selection of Changelog posts (fortunately this didn't affect the Owlet Weekly Updates... that would have been awkward!) where the body content wasn't loading for logged out users. 📢
• Small usability improvements to our huge Search revamp that we announced a couple weeks ago. 🔍
• Behind-the-scenes improvements to our issue-tracking and release process. 🚀

Bigger Feature Updates and Improvements

As mentioned last week, we released a new NPM module called api and we just released some huge updates to our API Explorer so you can see this in action! 🎉

Now, there's a new code sample language option available via the OpenAPI Extension called node-simple. Including this in your OpenAPI file generates Node.js code samples using our api SDK. You can see this working in the ReadMe API documentation!

Additionally, we also made a few smaller fixes and improvements to the API Explorer:

• Resolved a bug with the way Content-Type headers would be interpreted in code snippets so now if the Content-Type on a request is application/json, the body payloads will be a JSON object, not a stringified JSON object. 📦
• Fixed some issues with the API Explorer not functioning if a server URL in an OpenAPI/Swagger file had a trailing slash. 🔗
• Added support for Cookie parameters across the API Explorer. (See a demo here!) 🍪

Thanks for reading! Again, if you have any questions or feedback on any of these updates, drop us a line at [email protected]!

📘

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!