About Illuminate

Motivation

I created Illuminate mainly as a learning tool for myself. Throughout my career, I have mostly worked as either a solo technical writer or a team lead and had a significant stake in the choice of tooling to author and publish documentation. Much of the value that I have brought to my previous teams came from developing a deep understanding of the tooling we used and the ability to optimize it to make it easier for my fellow team members to contribute content.

There is no one-size-fits-all solution for documentation tooling. Many factors determine which tooling will be a good fit for the team and the product, and the options are seemingly endless. Building Illuminate allows me to test different technologies and techniques to learn hands-on where the pain points and limitations are and the scope of work to implement different documentation features. Regardless of whether I would be performing the work myself or in collaboration with a development team, this insight is invaluable.

Besides all that, I just enjoy building things.

---

Technology

Gatsby (framework)

I originally chose Gatsby because it was one of the most popular static site generators with an active community. It also had plenty of content and a rich plugin ecosystem to make building a website easier for someone like me who wasn't (yet) experienced in coding and web development. It uses React and GraphQL, both of which I wanted to learn, so I thought this would be a good way to get acquainted.

Overall, Gatsby has been a great learning tool and shares many common features with other popular web frameworks. However, after being acquired by Netlify last year, Gatsby's future seems unclear. I will probably migrate future work with Illuminate to a different framework.

MDX (content)

MDX lets you write content in Markdown, the simplest and most widely used format for software documentation. It supports an ecosystem of plugins such as rehype and remark make it easy to add more advanced functionality, as needed. MDX allows the use of custom JSX components to create more rich and engaging content. Refer Markdown and MDX to learn more about how to author content in Illuminate.

Chakra UI (component library)

Chakra UI is a unique middle ground between a solution like Tailwind or plain CSS and a framework like Bootstrap. They emphasize accessibility in their components and follow WAI-ARIA standards. This allows me to quickly build layouts from scratch without getting too caught up in the details while still having plenty of flexibility in the design.

Code Hike (code examples)

Code Hike goes beyond just basic syntax highlighting for code blocks. It also allows the author to add an extra degree of interaction with code blocks so that readers can see relevant parts of the code highlighted as they progress through instructions. It uses Bright for syntax highlighting which enables the use of any VSCode theme. Code Hike also enables the ability to link to external code files so that code samples can be isolated from the rest of the content. Refer to Code Hike to learn more about how to use these components in Illuminate.

Pagefind (search)

Pagefind is a fast, client-side search tool created by Cloudflare for integration with static site generators. It can handle searching large volumes of content without sacrificing speed because the search index is split into chunks, so only a small part of the index needs to be loaded. For most use cases, the network payload will be under 100kB. Refer to the Search guide to learn how to use Illuminate's search integration.