使用专业文档提升您的 GitHub 代码库 🔥
太长不看
每次我们使用某个产品时，无论是框架还是代码编辑器，都会遇到它的文档。
如果文档清晰美观，我们就会立刻喜欢上我们使用的产品。
在本文中，我想告诉大家如何为你的 GitHub 仓库创建专业的文档等等。
好，我们开始吧！🏎️
👀 我们该如何选择？
为了编写文档，我们将使用名为Astro Starlight的现成解决方案。本文将把它与同样流行的VuePress解决方案进行比较，并阐述我们选择 Astro 的原因。
你可以参考这里的文档进行类似的编写。看起来很不错。
1. 💎 设计
首先，我们来比较一下默认项目网站提供的两种设计方案。这样，我们就能知道哪种设计方案更适合我们：
VuePress
星光
不同的人喜欢不同的设计。这两个设计都不错，但我们之前用过类似的设计大约一年，实在是看腻了，所以最终选择了目前最受欢迎的第一个方案。
2. 🌊 新鲜度
不过，我们明白 VuePress 需要被替换，要么用 VitePress，要么用 NuxtLabs 的 Docus（NuxtLabs 最近加入了 Vercel）。充分了解这两个项目之后，这一点也对我们最终选择平台起到了至关重要的作用。
我们无论如何都会在项目中使用 Vue，不太可能选择其他开源框架，但事实是，我们不会偏离这个设计，因为它无处不在，让我们想起它。
所以，当我们考察其他平台时，发现除了 Vue 之外的其他平台对我们来说都不划算，但我们也需要一些新的东西。Starlight 大约在 2023 年左右推出（或者当时正在积极推广），所以我们认为它是一个不错的选择。
3. 🗄️ 支持旧文件
VuePress 的所有功能都基于文件构建.md。因此，将其迁移到一个同样支持文件的平台对我们来说至关重要。Astro 支持数据文件。我们只需要为旧文件添加一个头部信息，但通常来说，这并不是什么关键步骤。
---
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...
此外，还有一个意外收获：之前的结构问题{{code}}已经不再存在。HMPL 使用以下结构：
{{#request}}{{/request}}
我们以前经常需要把这个表达式用pre标签包裹起来，以免编译成 HTML 时出错。但是，使用 Astro Starlight 就不存在这个问题了。
📚 组件
您可以使用类块来更清晰地描述您为产品所做的工作。例如，新增组件Tabs、Result组件Steps等等，所有这些都使文档本身成为一件艺术品。
有了这些组件，理解模块的工作原理就容易多了。之前，我们在技术部分使用过ecmarkup，但后来我们意识到它无法提供对技术文档的全面控制，而只能展示获取到的结果。
⚙️ 如何将此文档添加到您的项目中？
首先，您需要安装Node.js版本 18 或更高版本，然后运行以下命令：
npx astro add starlight
之后，您需要配置站点配置，该配置位于[此处] astro.config.mjs，我们只能以我们自己的配置为例进行说明：
// @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: []
})
]
});
而且，侧边栏和其他参数大多是重复的，这里我就不一一列举全部 200 多行了。
✅ 结论
有了这样的文档，无论主题是什么，你都能打造出非常酷炫且易于推广的产品。你的想法可以通过精美的组件完美呈现，而且无需花费大量资金聘请设计师。
🔗 相关链接：
非常感谢您阅读本文❤️！希望本文能帮助您制作出色的文档！
你觉得这种方法怎么样？还有其他类似的项目吗？欢迎在评论区留言！
PS：也别忘了帮我给HMPL点赞哦！
文章来源：https://dev.to/anthonymax/level-up-your-github-repo-with-professional-documentation-1f3p