每次我們使用產品時,無論是框架還是程式碼編輯器,我們都會遇到它的文件。
如果文件清晰美觀,我們就會立即喜歡上我們所使用的東西。
在本文中,我想告訴您如何為您的 GitHub 儲存庫等製作專業文件。
好吧,讓我們開始吧! 🏎️
對於我們的文件,我們將使用一個名為Astro Starlight的現成解決方案。我們將在本文中將其與同樣流行的VuePress解決方案進行比較,並了解我們為何使用 Astro。
你可以從這裡取得類似的文件。看起來很不錯。
首先,讓我們比較一下預設專案網站提供的兩種設計。這樣,我們就能知道哪種設計比較適合我們:
VuePress
星光
不同的人喜歡不同的設計。這兩個設計都很不錯,但我們用了差不多一年的類似設計。我們真的厭倦了,所以選擇了第一個,因為它是目前最受歡迎的。
儘管如此,我們仍然明白,VuePress 需要被 VitePress 或 NuxtLabs(最近加入了 Vercel)的 Docus 取代。這一點,加上對這兩個專案的充分了解,在平台選擇上也發揮了巨大的作用。
我們以某種方式在專案上使用 Vue,並且不太可能選擇其他開源專案,但事實是,我們不會放棄這種設計,它處處提醒著我們。
所以,當我們檢視其他平台時,我們發現除了 Vue 之外的其他平台對我們來說都無利可圖,但我們也需要一些新的東西。 Starlight 大約在 2023 年左右發布(或者說當時正在積極推廣),所以我們覺得這是一個不錯的選擇。
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 加星號!
{% cta https://github.com/hmpl-language/hmpl %} 🌱 星標 HMPL {% endcta %}
原文出處:https://dev.to/anthonymax/level-up-your-github-repo-with-professional-documentation-1f3p