阿川私房教材:
學 JavaScript 前端,帶作品集去面試!

63 個專案實戰,寫出作品集,讓面試官眼前一亮!

立即開始免費試讀!

TL;DR

每次我們使用產品時,無論是框架還是程式碼編輯器,我們都會遇到它的文件。

如果文件清晰美觀,我們就會立即喜歡上我們所使用的東西。

在本文中,我想告訴您如何為您的 GitHub 儲存庫等製作專業文件。

好吧,讓我們開始吧! 🏎️


👀 我們選擇什麼?

對於我們的文件,我們將使用一個名為Astro Starlight的現成解決方案。我們將在本文中將其與同樣流行的VuePress解決方案進行比較,並了解我們為何使用 Astro。

示範

你可以從這裡取得類似的文件。看起來很不錯。


1.💎 設計

首先,讓我們比較一下預設專案網站提供的兩種設計。這樣,我們就能知道哪種設計比較適合我們:

VuePress

VuePress

星光

星光

不同的人喜歡不同的設計。這兩個設計都很不錯,但我們用了差不多一年的類似設計。我們真的厭倦了,所以選擇了第一個,因為它是目前最受歡迎的。


2.🌊 新鮮

儘管如此,我們仍然明白,VuePress 需要被 VitePress 或 NuxtLabs(最近加入了 Vercel)的 Docus 取代。這一點,加上對這兩個專案的充分了解,在平台選擇上也發揮了巨大的作用。

我們以某種方式在專案上使用 Vue,並且不太可能選擇其他開源專案,但事實是,我們不會放棄這種設計,它處處提醒著我們。

astrojs

所以,當我們檢視其他平台時,我們發現除了 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 就不存在這個問題了。


📚 元件

您可以使用類別區塊更清晰地描述您為產品所做的工作。新的元件: TabsResultSteps等等,所有這些都使文件真正成為一件藝術品。

步驟

有了這樣的元件,模組的工作原理就變得更容易理解了。之前,我們在技術部分使用了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


共有 0 則留言


精選技術文章翻譯,幫助開發者持續吸收新知。

阿川私房教材:
學 JavaScript 前端,帶作品集去面試!

63 個專案實戰,寫出作品集,讓面試官眼前一亮!

立即開始免費試讀!