Hello from Kryzz (Liz + Krystan) here at Skylight! We've been hard at work revamping the new Skylight Smarketing (marketing + documentation) site. Now that it's deployed, we'd love to tell you about it.

The old site was in dire need of a content update. Some of our favorite features weren't even mentioned! Also, the documentation site was super boring and not fun to update. Thus, some of our documentation wasn't as thorough as it should have been, resulting in support tickets that could've been easily handled with a FAQ. Since Skylight developers answer our own support tickets, we saw a lot of value in revamping the docs.

As two of the less experienced developers in the office, we were excited to have the opportunity to work independently on a project as a way to level up our mad skillz. We set a few goals at the beginning of the project:

• Use HTML and CSS best practices to create a responsive and accessible site.
• Write clean and well-documented code.
• Make the docs ridiculously easy to update.

As always, user experience is hugely important at Skylight. We figured we could "slice two carrots with one knife" (Krystan is vegan so she's not cool with killing birds with stones) by making the docs user experience as fun as the marketing site was going to be. Hence the name "Smarketing." The docs are part of the marketing, they're smart, and they make you smarter about how to use Skylight.

Highlights

Check out the following Smarketing features that we are most proud of:

• The new Skylight Guides! We put a ton of effort into making a really useful walkthrough of the Skylight app.
• The Performance Tips support page! It's like having a little tiny Godfrey or Yehuda in your computer.
• It's responsive! Check out our sweet features page at various breakpoints. We flex-boxed and breakpointed the heck out of this thing, all for your viewing pleasure. We challenge anyone to a game of Flexbox Froggy. We will beat you.
• You can navigate it with your keyboard! We love our mouse-hating VIM-bros (of which Liz is one!), so we made sure you didn't have to touch the electric rodent if you didn't want to, even to play around with the newly revamped pricing calculator.
• Cute monster easter eggs! We've hidden the new Skylight monsters throughout the site. Gotta catch em all!

The Skylight-Docs Engine

In order to "make the docs ridiculously easy to update," we decided to migrate our docs from a really out-of-date Middleman site to a custom Rails engine. Our solution is open-source, so you can see how we did it (and contribute new content and corrections to the docs). Now, in order to update Skylight's documentation, we just need to add or modify a .md.erb file then update the skylight-docs gem in our marketing app.

Here's how it works (you can follow along here):

In the ChaptersController, we get Skylight::Docs::Chapter.all, which returns an array of Chapter objects containing the markdown filenames.

As we need more information about each chapter, more data is lazily added to the Chapter object. For example, when we call chapter.title for the first time in a view, the title is extracted from YAML frontmatter in the markdown file and added to the object. Thereafter, we don't need to extract the frontmatter again because it's already part of the object.

The really cool stuff happens when we call @chapter.content on the chapters/show template:

• First, we remove the frontmatter from the raw .md.erb file.
• Then we run the clean content through ERB.result to generate markdown. We use ERB to implement some custom functionality as discussed below.
• We then add some kramdown-specific markdown at the beginning of the file to generate a table of contents for that file.
• This new markdown content is then run through kramdown to generate html content.
• The html content is split into the table of contents and the main content.

This may sound complicated, but it all happens in about six lines of code. We implemented some custom ERB functionality to make writing docs even simpler:

• Markdown partials so that we can reuse snippets of content in multiple places.
• link_to helpers that know if they are linking to internal or external content (and apply classes and target locations as necessary).
• image_tag helpers that automatically add image-specific classes.

Since the docs are essentially static content, we are utilizing fragment caching to make sure that navigating the documentation is super snappy. The cache keys are based on the bundler generated file name (which in turn is based on the git sha), so we don't need to worry about incrementing the version number with every tiny change.

Mission Accomplished

Team Kryzz is delighted with our final product, and we hope you will be too. We also hope you'll give us lots of feedback about the new site and that the new documentation allows you to tackle your performance issues even more easily than before.

Ready to do the answer dance? Sign up for your 30-day Skylight free trial! Or refer a friend and you both get $50 in credit.