Posted on Jul 30

Level Up Your GitHub Repo with Professional Documentation 🔥

#webdev #javascript #programming #opensource

TL;DR

Every time we work with a product, be it a framework or a code editor, we come across its documentation.

And if the documentation is clear and beautiful, then we immediately like what we use.

In this article, I would like to tell you how you can make professional documentation for your GitHub repository and more.

Well, let's get started!🏎️

👀 What do we choose?

For our documentation, we will use a ready-made solution called Astro Starlight. We will compare it with the equally popular VuePress solution and see why we use Astro in this article.

You can make similar documentation taken from here. It looks pretty good.

1. 💎 Design

First of all, let's compare two designs that are provided from the default project sites. This way, we can understand which design suits us:

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.

📚 Components

You can use class blocks to more clearly describe what you made for the product. 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.

⚙️ 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

With such documentation, you will be able to make a really cool and easily promoted product, regardless of what the topic is. Your ideas will be able to be transmitted through beautiful components and you will not have to spend a lot of money on a designer.