Change is inevitable, and every now and then it comes around. In the past few years there are changes that have been forced upon us, changes we had no direct control over. But at Layer0/Edgio, the recent change is one of our own making, one that was very much needed: a complete rewrite and redesign of the Edgio documentation.
This overhaul was meant to be foundational and controllable. The truth is, we wanted to take matters into our own hands like we’ve never done before. And so, heavily inspired by the React beta docs, we set forth on the shoulders of giants by creating an instance of the base repo and fine tuning it for our specific use case.
First things first
The first step was the Reactiflux discord channel. To put it simply, the community helped identify the React’s beta documentation repo.
The React beta repo as a head-start
We spent a couple of days researching how the React docs beta site had been built, what technologies it uses, and how we can leverage and build on top of this stack to cater to our specific needs. Our hunch about MDX and Next.js was right and we found ourselves with a head-start.
Here are some of the primary technologies used:
- MDX: Functional markdown with embedded React components
- Next.js: React framework
- Webpack: module bundler
- Styled Components: styling
- Algolia: Search
- Prism: Code syntax highlighting
MDX: MDX is an extended form of Markdown for the component era. It makes markdown functional by allowing you to embed JSX in any markdown document, taking content authoring with markdown to a new level.
We already knew what MDX was and how powerful it can be from articles like MDX, The secret ingredient and Front-End Documentation, Style Guides and the Rise of MDX. This paved the way for some of the custom components we created.
Next.js: Pairing MDX with Next.js isn’t something new so the first instinct was to read the official documentation or this blog post. There are a couple of approaches to getting markdown into Next.js pages like having a local markdown document and transforming it into HTML using packages like remark and remark-html inside one of getStaticProps, getStaticPaths, or getServerSideProps
Another approach is to define a `.md` or `.mdx` file directly as Next.js pages with the @next/mdx package, or if you like to deal with the lower-level stuff, follow the React’s team approach and DIY.
Webpack: next.config.js (or next.config.mjs) is used by the Next.js server and build phases. This is where you can configure Next.js for advanced use-cases, like letting markdown read `.mdx` file extensions in the pages directory and loading them as Next.js pages.
Webpack uses loaders to preprocess files. One of the more common use-cases is transpiling and one such common package is babel-loader (Loads ES2015+ code and transpiles to ES5 using Babel). To load `.mdx` files with Webpack in Next.js, @mdx-js/loader is used.
The rich ecosystem of remark/rehype plugins can be called on for assistance by @mdx-js/loader for a fine grain transformation of markdown to html.
Styled Components: While there are a plethora of ways to write CSS in Next.js, we chose Styled Components. With Styled Components, we are able to author components styles in a more colocated, modular, coupled, and less-intrusive way. Learn How To Use Styled-Components In React or explore The styled-components Happy Path for more information on Styled Components.
Algolia: We’ve upgraded to the latest version of DocSearch v3 which is built on top of Algolia Autocomplete, providing enhancements to accessibility and responsiveness giving a smoother experience on both desktop and mobile devices. Coupled with that is the Algolia Crawler to extract the most relevant information when performing your search.
Prism: Prism is the well tested-and-trusted code syntax highlighter. It isn’t just easier to get started, it also has a rich plugins ecosystem, and is extensible with sensible defaults for operations like theming.
While the redesign features a largely cosmetic change at face value, there are other features such as:
A New Homepage with Important Details
Get started with the four pillars of the Layer0/Edgio platform and build your way up and into more features Layer0/Edgio has to offer.
Switching between themes is only a button click away. Go from light mode to dark mode or vice-versa or let your operating system decide.
The two main navigation modes—menu (on the left), and table of content (on the right)—have been redesigned for better navigation and scanning. A new pagination control (at the bottom) helps you know which guide is next and which comes before.
Improved CodeblocksWith PrismJS, syntax highlighting and customization is dead-simple.
Algolia search has been upgraded to v3 which gives us much more control of what content is indexed for results. This also works on mobile devices.
But wait, there’s more
The React beta docs repo has a lot going on for it, and we’ve been able to leverage the power of open-source here. There are some things we get almost out of the box, like table-of-contents, docs pagination, breadcrumbs, SEO etc. Some of these we’ve tweaked to better serve our context, and some we are still exploring.
For us this is the new documentation is a step in the right direction and the beginning of a new beginning. We want you to join us on this journey as we continue to help you make your websites faster and safer without compromising on developer experience. The source code for the Layer0 developer docs is in an open repository on GitHub and we welcome feedback and pull requests. If you’ve found a typo or a better way to explain something, please submit a pull request or file an issue! Also, see our contributing guidelines.