📢 New Docs: How We Revamped Our Documentation with Astro Starlight 🌌

#webdev #javascript #programming #opensource

Today is one of the most important days in the future development of the template language.

We have produced really comprehensive and clear documentation that looks very professional :)

In this article, I would like to consider the process of its creation, as well as tell you how you can make it and how it will be useful to you.

Let's get started!🏎️

👀 Why did we choose Astro Starlight for the new documentation?

I would like to point out that this is not an advertisement, no one paid us. So, let's be honest. Previously, we used VuePress. It is a really cool tool for creating documentation, but we encountered problems that we will describe below.

1. 💎 Design

First of all, it's the design. Just compare the design there and here:

VuePress

Starlight

Different people like different designs. These are two good designs, but we used a similar design for about a year. We literally got tired of it, so we chose the first option as the most popular today.

2. 🌊 Freshness

Still, we understand that VuePress needs to be replaced either with VitePress or with Docus from NuxtLabs (which recently joined Vercel). This point, with a full understanding of the two projects, also played a huge role in the choice of the platform.

We, one way or another, work on Vue for projects and are unlikely to choose something else for open source, but the fact is that we will not go anywhere from this design, which reminds us of it everywhere.

So, when we looked at other platforms, it wasn't profitable for us to switch to anything other than Vue, but we also needed something new. Starlight came out somewhere around 2023 (or was actively starting to promote itself), so we decided it was a good option.

3. Support for old files

All of VuePress was built on .md files. It was important for us to transfer it to a platform where it would also be. In the case of Astro, it does support data files. It was only necessary to make a header for old files, but, in general, it is not critical.

--- title: Introduction description: Learn about HMPL --- ## How it works? The HTML you use on your site is enhanced by adding special blocks that resemble components in syntax...

Also, a nice bonus in all this was that the problem with the {{code}} construct was no longer relevant. HMPL uses the following construction:

{{#request}}{{/request}}

And we had to wrap this expression in a pre tag quite often, so that it wouldn't cause errors when compiled into HTML. But, with Astro Starlight there is no such problem.

📚 New in documentation

In general, almost everything (except the content related to the technical part). New components: Tabs, Result, Steps and so on, all this makes the documentation literally a work of art.

With such components, it became much easier to understand how the module works. Previously, for the technical part, we used ecmarkup, but then we realized that it would not be able to give full control over the technical documentation, but just show what is obtained.

Also, almost all the texts were updated, a bunch of new things were added. It felt like a novel came out in terms of the number of words, not documentation 🥶

⚙️ How can you add this documentation to your project?

First of all, you will need to install Node.js version 18 or higher, and run the command:

npx astro add starlight

After this, you will need to configure the site config, which is located in astro.config.mjs, we can only show ours as an example:

// @ts-check import { defineConfig } from "astro/config"; import starlight from "@astrojs/starlight"; import vue from "@astrojs/vue"; import starlightThemeNova from "starlight-theme-nova"; export default defineConfig({ site: "https://hmpl-lang.dev", integrations: [ vue(), starlight({ title: "HMPL Documentation", description: "Server-oriented customizable templating for JavaScript. Alternative to HTMX and Alpine.js.", customCss: ["./src/styles/main.css"], logo: { src: "./src/assets/logo.svg" }, expressiveCode: { themes: ["min-light", "min-light"], useStarlightDarkModeSwitch: false, shiki: { langAlias: { hmpl: "html" } } }, components: { Search: "./src/components/Stars.astro" }, editLink: { baseUrl: "https://github.com/hmpl-language/hmpl/edit/main/www/app" }, favicon: "favicon.ico", social: [ { icon: "github", label: "GitHub", href: "https://github.com/hmpl-language/hmpl" } ], sidebar: [ { label: "Start Here", items: [ { label: "Introduction", link: "/introduction" }, { label: "Getting Started", link: "/getting-started" }, { label: "Installation", link: "/installation" } ] } ], plugins: [] }) ] });

And, there are most of the sidebar and other parameters that are repeated, I will not indicate all 200+ lines here.

✅ Conclusion

When choosing a documentation platform, it is important to consider many different things: from your past work to the number of people in the team. If we were to make documentation purely in Vue, it would take us a couple of months. In this article, we tried to show what kind of documentation can be made and how you can make it as cool as ours (well, we think ours is cool 👽)