今天是模板語言未來發展中最重要的日子之一。
我們製作了非常全面、清晰且看起來非常專業的文件:)
在本文中，我想考慮它的建立過程，並告訴您如何製作它以及它如何對您有用。
讓我們開始吧！ 🏎️
👀 為什麼我們選擇 Astro Starlight 作為新文件？
我想指出的是，這不是廣告，沒有人付錢給我們。所以，說實話吧。我們之前用過 VuePress。它是一個非常棒的文件建立工具，但我們遇到了一些問題，下文會詳細描述。
1.💎 設計
首先，是設計。比較一下那裡和這裡的設計：
VuePress
星光
不同的人喜歡不同的設計。這兩個設計都很不錯，但我們用了差不多一年的類似設計。我們真的厭倦了，所以選擇了第一個，因為它是目前最受歡迎的。
2.🌊 新鮮
儘管如此，我們仍然明白，VuePress 需要被 VitePress 或 NuxtLabs（最近加入了 Vercel）的 Docus 取代。這一點，加上對這兩個專案的充分了解，在平台選擇上也發揮了巨大的作用。
我們以某種方式在專案上使用 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 多行。
結論
選擇文件平台時，需要考慮很多因素：從你過去的工作經驗到團隊人數。如果我們只用 Vue 製作文件，可能需要幾個月的時間。在本文中，我們嘗試展示可以製作什麼樣的文件，以及如何讓它像我們的文件一樣酷炫（好吧，我們認為我們的文件很酷👽）。
🔗 連結：
非常感謝您閱讀這篇文章❤️！
你覺得新文件怎麼樣？歡迎在留言區留言，一定會很有趣！
PS 另外，別忘了幫我並給 HMPL 加星號！
{% cta https://github.com/hmpl-language/hmpl %} 🌱 星標 HMPL {% endcta %}
原文出處：https://dev.to/hmpljs/new-docs-how-we-revamped-hmpl-documentation-with-astro-starlight-19ce
1) --- 會變成分隔線（上一行必須是空白）
2) # 會變成一級標題
3) ## 會變成二級標題
4) ### 會變成三級標題
5) **粗體文字**會顯示粗體文字
6) ```當第一行與最後一行會顯示程式碼
7) 請搜尋 Markdown 語法，了解各種格式