LINE Developers site: From Middleman to VuePress

Hi, we’re Roman Lossa and Marshall Gunnell, a front-end developer and technical writer both working on the LINE Developers site here at LINE. 

Our team’s mission statement is simple: Empower developers using the LINE Platform to accomplish more with less friction. In other words, our goal is to provide a platform that allows developers to be self-sufficient, confident, and able to quickly create better apps with fewer roadblocks and less frustration. 

We take this mission statement to heart, and we constantly work to provide the ultimate frictionless experience for those using the LINE Developers site. That means providing easy-to-read documentation, improving the speed and responsiveness of our site, and constant maintenance of website architecture and hygiene.

One task we recently took on in order to realize our mission statement was the migration of the LINE Developers site from Middleman to VuePress. In this blog post, we’d like to cover the minor and major changes the LINE Developers site underwent during this process, the challenges that the migration from Middleman to VuePress presented to our team, and what this new change means for both internal and external developers.

About the LINE Developers site

The LINE Developers site is a portal site for developers who want to use our developer products such as LINE Login, LIFF (Line Front-end Framework), and the Messaging API. On the site, you can find our product documentation, the latest news about LINE developer products, and an FAQ section to provide answers to your questions. It also provides access to SDKs and other resources that we’ve made available to developers.

Another major component of the LINE Developers site is the developer console which lets you manage the channels used to connect your apps with the LINE Platform. The developer console also recently underwent a major overhaul, providing various fixes and improvements.

Making the switch from Middleman to VuePress

VuePress is an open-source static site generator that runs as a Single-Page Application (SPA) after the page has been loaded. For those of you who may be unfamiliar with the concept of SPA, here’s a brief overview.

Traditional HTML vs. SPA

Let’s start off by looking at a traditional HTML-only website. This website would consist of multiple HTML pages, each having one HTML file per page. When moving from page A to page B on the site, a new HTML file is loaded, causing the browser to reload all of the HTML file’s contents visible to the user. Even if the page header, footer, or side menu is the same on page B as it was on page A, the entire page is re-rendered. This was our situation when we were using Middleman.

VuePress, however, adopts the SPA approach. As the name suggests, when a user first visits the site, only a single HTML page is loaded. From there on, we harvest the power of JavaScript to speed up the process. When navigating through pages on the website, instead of reloading the entire browser window with each page transition, only the content that actually changes is replaced. The header, footer, and side menu remain present on the page. This reduces the amount of data required for each page transition as well as the amount of screen real estate that has to be re-rendered. As a result, this significantly improves browsing speed which, in turn, improves the user experience.

Why the switch? Why VuePress?

While Middleman has served us well in the past, its Ruby codebase appears outdated in the age where JavaScript, npm, React, Vue.js, and the likes are gaining popularity. On top of Middleman, we used to add webpack to enable the use of npm and, thus, more modern front-end development in Vue.js.

As the site grew larger and more complex over the years, booting up the Middleman development server locally and working on the system became quite slow. By adopting VuePress, we were able to move our entire codebase to JavaScript for both front and back-end development. This streamlined, simplified, and sped up our system.

Another reason was, before the console underwent its aforementioned overhaul, we were using shared components for the front-end. That is, shared between the console and the LINE Developers site. With the console’s overhaul, its codebase changed and moved away from the shared components, which left them only being used by the document site. By renewing the entire documentation site, we could fix the issue of having a split codebase along the way.

By addressing these issues, we could simplify our development process and increase productivity.

But how did we decide on VuePress as being the ideal solution for us?

Before we decided on using VuePress, we also considered other systems such as Gatsby and Gridsome. We ended up choosing VuePress because it checked the most boxes for us:

  • Being a Vue.js-based system
  • Out-of-the-box markdown rendering
  • Localization support —essential since we have English, Japanese, and (partially) Chinese content on the site—

Choosing VuePress did not come without risks, though. It was still in beta stage when reviewing it in early 2019, and it was barely released in stable v1.0 in mid-2019 when we began development. Even still, we trusted the active Vue.js community to have this project mature. We decided to take on the challenge.

It was not all easy: The challenges

While these benefits made the transition to VuePress worth it in the end, the transition process wasn’t exactly easy.

1. Partial files

While VuePress provides a lot of out-of-the-box features, we realized early on that it was lacking an important one: support for partial markdown. Particularly with our API references, we have several pages with a large amount of content. Managing this content in a single file is possible but not feasible, so we split the content into multiple markdown files.

However, at the time of writing this, VuePress doesn’t support splitting markdown files into multiple partial files. Luckily, VuePress is extremely customizable, so we were able to come up with a work-around. Using the additionalPages method of the VuePress Option API, we implemented a pre-processing step that scans our markdown content for our custom partial files that include this syntax:

!partial /here/comes/the/partial-file.md

The partial-file.md is then read and the custom partial file include command is replaced with the actual content of the partial file.

2. Content

a) Migration script

Having a large team of technical writers work on the documentation of multiple services (in multiple languages) simply results in a large number of pages on the site.

As the file structures of VuePress and Middleman differ, porting the content from one system to the other posed a challenge in itself. Also, as the site is constantly being updated, new changes made to the content on Middleman needed to be constantly ported to VuePress until the release.

In order to solve this challenge, we built a migration script to restructure and port the markdown content on Middleman to VuePress. While the process was not fully automated and the script had to be executed by hand, having this script resulted in a semi-automated process that greatly reduced the time and cost of the content migration.

b) Build time

As the number of pages on VuePress increases, so does the build time. At one point, the build wouldn’t be finished even after 1 hour and 40 minutes. This rendered the use of VuePress essentially useless, so we either had to fix this issue or abandon the transition to VuePress completely.

As mentioned earlier, we provide our content in three different languages; English, Japanese, and Chinese. By default, one build would contain all three languages. It seemed like a good idea to split the build into three; that is, one build per language. Having a separate build per language would result in losing SPA navigation between languages, but we assumed that a user would generally only look at one language when browsing the site. This seemed like a fair trade-off, so we went with it.

Splitting the build into three per-language builds, as well as running these in parallel, brought the build time down to around 5 minutes.

VuePress became usable for us again.

3. UI redesign

a) Merging three style sources

VuePress comes with a neat default design. However, our documentation site used its own built-from-scratch custom design. We wanted to generally maintain our design, but this time we’d build it based on LINE’s internal design library in order to be more consistent with other LINE websites.

In conclusion, we had three style resources that we had to put together to come up with the current design:

  • Default VuePress design
  • Custom built-from-scratch design
  • LINE’s internal design library

Even still, it strongly resembles our old design.

b) Custom UI elements

In addition to tweaking the base design as described above, we also had to implement UI elements custom-tailored to our needs that are simply not provided by VuePress.

Examples are the News pages, the API reference pages, the FAQ, and the glossary.

4. SSR

Writing SSR (server-side rendering) compatible JavaScript was a task not before seen on Middleman.

When developing locally, it is enough to boot up the VuePress development server. At this stage, things will work even when they are not SSR compatible.

However, in order to put the site on a server, it needs to be built. When building the site, its code needs to be SSR compatible. This means that when writing non-SSR compatible code, it may work on the dev server but will break the build.

A common cause for this is trying to access browser-specific JavaScript objects such as document or window in setup methods. During SSR, these objects are not available. They must only be accessed in runtime methods that are exclusively executed on the browser.

5. Microsoft Windows

Due to our heavy customization and a lot of dynamic page generation, the dev server’s (webpack’s) hot reload feature doesn’t currently work properly on Windows. This is not a problem for our Mac users, but some members of the team are using Windows and are struggling here.

At the time of writing, this problem isn’t fully resolved yet.

Moving forward with VuePress

With the new LINE Developers site now live, both internal and external developers will experience a number of improvements.

  • Quicker development – As our codebase is now streamlined in a single git repository while using JavaScript only, the team can develop new features and deploy changes to the site at a much faster pace.
  • Improved site speed – With SPA now in place, site speed has significantly increased and users will notice a snappier response when browsing from page to page.
  • Overall design – The site sports a more modern, up-to-date look and feel. With this new design, we were also able to make better use of the space on the API reference pages, improving overall readability.
  • Including interactive site elements – Certain elements, such as the API playground and feedback form, are much easier to integrate now since VuePress natively supports including Vue.js components.
  • Supportive community – It’s no secret that the JavaScript community is active and growing. This is extremely important to us now that we’ve made the switch.

While the list of challenges were long, these benefits along made the switch to VuePress worth it in the end. Even still, this is just the beginning for us in improving the LINE Developers site. We plan to bring continuous updates and releases to create an even more frictionless experience for our users. If you’re interested in providing feedback on how we can improve, you can provide feedback on our recently re-released feedback form on the LINE Developers site.

If you want to stay up-to-date with the latest developments, add the LINE Developers Official Account as a LINE friend by scanning this QR code.