diff --git a/docs/src/components/Header/LanguageSelect.tsx b/docs/src/components/Header/LanguageSelect.tsx index 46e3dd0f3..815bef472 100644 --- a/docs/src/components/Header/LanguageSelect.tsx +++ b/docs/src/components/Header/LanguageSelect.tsx @@ -68,7 +68,7 @@ const LanguageSelect: FunctionalComponent<{ lang: string }> = ({ lang }) => { 简体中文 diff --git a/docs/src/config.ts b/docs/src/config.ts index ed59f9557..2ff25dd90 100644 --- a/docs/src/config.ts +++ b/docs/src/config.ts @@ -59,8 +59,11 @@ export const SIDEBAR = { { text: '模板样例', link: 'zh-CN/examples' }, ], 'zh-TW': [ - { text: '起步', header: true }, - { text: '入門指南', link: 'zh-TW/getting-started' }, + { text: '設定', header: true }, + { text: '新手上路', link: 'zh-TW/getting-started' }, + { text: '快速開始', link: 'zh-TW/quick-start' }, + { text: '安裝', link: 'zh-TW/installation' }, + { text: '範例', link: 'zh-TW/examples' }, ], }; diff --git a/docs/src/pages/zh-TW/examples.md b/docs/src/pages/zh-TW/examples.md new file mode 100644 index 000000000..e8e38f6b9 --- /dev/null +++ b/docs/src/pages/zh-TW/examples.md @@ -0,0 +1,9 @@ +--- +layout: ~/layouts/MainLayout.astro +title: 範例 +lang: zh-Hant-TW +--- + +如果喜歡從做中學，可以看看放在 Github 的[範例資源庫](https://github.com/snowpackjs/astro/tree/main/examples)。 + + diff --git a/docs/src/pages/zh-TW/getting-started.md b/docs/src/pages/zh-TW/getting-started.md index aa3974a29..10bfc9270 100644 --- a/docs/src/pages/zh-TW/getting-started.md +++ b/docs/src/pages/zh-TW/getting-started.md @@ -1,63 +1,62 @@ --- layout: ~/layouts/MainLayout.astro -title: 入門指南 -lang: zh-TW +title: 新手上路 +lang: zh-Hant-TW --- -Astro 是一個現代的靜態網站生成工具. 你可以從 [我們的主頁]（https://astro.build/） 或者 [我們的 release 公告]（https://astro.build/blog/introducing-astro） 中瞭解到 Astro 的全部內容，本頁是 Astro 文檔和所有相關資源的概述。 +Astro 是利用現代技術的靜態網站生成工具。可以從[首頁](https://astro.build/)或[釋出版本貼文](https://astro.build/blog/introducing-astro)來了解 Astro 的用途。此頁面是 Astro 文件與所有相關資源的概要。 -想快速瞭解一下什麼是 Astro ？ [瀏覽我們的主頁] (https://astro.build) +在找 Astro 的簡易概要？[請看首頁](https://astro.build)。 -## 嘗試一下 Astro +## 試用 Astro -嘗試 Astro 的最簡單的方法是在新目錄下運行 『npm init astro』。 我們的 CLI 工具會説明你創建啟動一個新的 Astro 專案。 +試用 Astro 最簡單的方法，就是在機器的新資料夾裡執行 `npm init astro`。我們製作的 CLI 精靈會協助開啟全新的 Astro 專案。 -想要快速了解學習使用 Astro， [快速入門指南]（quick-start）. +簡易又迅速 5 步驟就開始使用 Astro 的方法，請看 [快速開始指南](quick-start)。 -另外，請閱讀我們的 [安裝指南]（/installation），瞭解如何使用 Astro 進行安裝的全部步驟。 +或者，閱讀[安裝指南](/installation)，有安裝 Astro 的完整流程。 -### 在線遊樂場 +### 線上玩玩看 -如果你有興趣在瀏覽器中嘗試 Astro，你可以使用一個在線代碼遊樂場。 試試我們在 [CodeSandbox]（https://codesandbox.io/s/astro-template-hugb3） 上的 "Hello World！" 範本。 +有興趣在瀏覽器試玩 Astro 嗎？有線上的程式碼試玩區。試試看放在 [CodeSandbox](https://codesandbox.io/s/astro-template-hugb3) 的「Hello! World」範本。 -注意：一些功能（例如：快速刷新）目前在 CodeSandbox 上是受限的。 +註：有些功能（例如：快速重新整理）目前在 CodeSandbox 的效果有限。 ## 學習 Astro -各種各樣的人來自不同的背景，帶來了不同的學習方式，來到 Astro。 無論你喜歡的是理論性強的方法還是實踐性強的方法，我們希望你會發現本節內容對你有説明。 +每個來到 Astro 的人來自不同背景，使得學習方式也不同。不管是喜歡更為理論，還是實際的方法，希望都可以覺得這部分很有用。 -- 如果你喜歡在**實踐中**學習，請從我們的 [實例庫]（https://github.com/snowpackjs/astro/tree/main/examples） 開始學習。 +- 如果喜歡**從做中學**，從[範例資源庫](https://github.com/snowpackjs/astro/tree/main/examples)開始。 +- 如果喜歡**一步一步學習概念**，就從[基本概念與指南](/core-concepts/project-structure)開始。 -- 如果你喜歡**逐步學習概念**，請從我們的[基本概念和指南]（/core-concepts/project-structure）開始。 +就像任何還不熟悉的技術，Astro 會有一些學習曲線。只不過，只要練習和一些耐心，我們確信很快就會熟悉。 -像任何不熟悉的技術一樣，Astro 也有一個輕量化的學習曲線。 然而我們相信只要有耐心勤於練習你很快就會掌握訣竅的。 +### 學習 `.astro` 語法 -### 學習 '.astro' 語法 +開始學習 Astro 的時候，會看到很多檔案副檔名是 `.astro`。這是 **Astro 的元件語法**：近似於 HTML 的特殊檔案格式，Astro 用來當作範本。設計成有 HTML 或 JSX 經驗的人都覺得和藹可親。 -當你開始學習 Astro 時，你會看到許多檔使用『.astro』檔擴展名。 這是**Astro 的元件語法**：一種特殊的類似 HTML 的檔格式，Astro 用於範本製作。 這樣設計是為了讓任何有 HTML 或 JSX 經驗的人更容易上手。 +[Astro 元件](/core-concepts/astro-components)指南會很有幫助，介紹 Astro 的語法，也是最好的學習方式。 -我們在 [Astro 元件]（/corecepts/astro-components） 上的有用指南向你介紹了 Astro 語法，這也是學習的最好方法。 +### API 參考手冊 -### API 參考文檔 +如果想要深入探討某個 Astro API，這部分的文件會很有幫助。例如：[設定參考](/reference/configuration-reference)列出所有可以使用的設定選項。[內建元件參考](/reference/builtin-components)列出所有可以使用的核心元件，像是 `` 和 ``。 -當你想了解某個特定的 Astro API 的更多細節時，這部分文檔是有用的。 例如 [配置參考]（/reference/configuration-reference） 列出所有可能的配置選項供你使用。 [內置元件參考] （/reference/builtin-components） 列出了所有可用的核心元件，如『』和『』。 +### 先前版本的文件 -### 其他版本文檔 +這份文件就肯定是根據 Astro 最新的穩定版本。一但達到 1.0 里程碑，會增加查閱過去文件版本的功能。 -本文檔總是展示 Astro 的最新穩定版本。 一旦我們達到 V1.0 的里程碑，我們將增加查看版本檔的能力。 +## 獲得最新訊息 -## 瞭解最新消息 +推特帳號 [@astrodotbuild](https://twitter.com/astrodotbuild) 是 Astro 團隊撰寫的官方更新消息來源。 -[@astrodotbuild] (https://twitter.com/astrodotbuild) Twitter 帳戶是 Astro 團隊的官方更新來源。 +我們也會把釋出版本公告貼在 [Discord 社群](https://astro.build/chat) 的 #announcements 頻道。 -我們也在我們的 [Discord 社區]（https://astro.build/chat） 的 #announcements 頻道中發佈 release 公告。 +不是每個 Astro 釋出版本都會有一篇專屬的部落格貼文。然而，還是可以在 [Astro 的 Repository 裡的 `CHANGELOG.md` 檔案](https://github.com/snowpackjs/astro/blob/main/packages/astro/CHANGELOG.md)，找到每個釋出版本的詳細變動記錄。 -當然並非每個 Astro 的發佈都會有自己的 release 公告，你可以在 Astro 倉庫的 ['CHANGELOG.md'檔]（https://github.com/snowpackjs/astro/blob/main/packages/astro/CHANGELOG.md） 中找到每個版本的詳細更新日誌。 +## 還漏了什麼嗎？ -## 勘誤與建議 - -如果你在閱讀的過程中發現文檔中缺少什麼，或者你發現某些部分令人困惑，請 [為文檔提交問題]（https://github.com/snowpackjs/astro/issues/new/choose） ，提出你的改進建議，或者在 [@astrodotbuild]（https://twitter.com/astrodotbuild） Twitter 帳戶上發推文。 我們希望聽到你的建議！ +如果文件裡有東西沒寫到，或是覺得有些地方很難理解，請[開文件的 Issue](https://github.com/snowpackjs/astro/issues/new/choose)，附上改進建議，或推文到推特帳號 [@astrodotbuild](https://twitter.com/astrodotbuild)。我們喜愛聽到回饋！ ## 參考 -本入門指南最初是基於 [React]（https://reactjs.org/） 的入門指南。 +這份新手上路指南一開始是根據 [React](https://reactjs.org/) 的新手上路指南。 diff --git a/docs/src/pages/zh-TW/installation.md b/docs/src/pages/zh-TW/installation.md new file mode 100644 index 000000000..4ff5c4158 --- /dev/null +++ b/docs/src/pages/zh-TW/installation.md @@ -0,0 +1,162 @@ +--- +layout: ~/layouts/MainLayout.astro +title: 安裝 +lang: zh-Hant-TW +--- + +有幾種方式把 Astro 安裝在新專案。 + +## 環境需求 + +- **Node.js** - `v12.20.0`、`v14.13.1` 和 `v16.0.0`，或更之後的版本。 +- **文字編輯器** - 我們推薦使用 [VS Code](https://code.visualstudio.com/) 和 [Astro 官方擴充套件](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode)。 +- **終端機** - Astro 主要透過終端機指令進行。 + +下方範例使用的 [`npm`](https://www.npmjs.com/) 只是用來舉例。也可以使用 [`yarn`](https://yarnpkg.com/) 或 [`pnpm`](https://pnpm.io/) 等 npm 替代方案。 + +## 建立 Astro + +`npm init astro` 是新專案裡，最容易安裝 Astro 的方式。在終端機裡執行這個指令，就可以啟動 `create-astro` 安裝精靈，協助設定新專案。 + +```shell +# 用 NPM +npm init astro + +# Yarn +yarn create astro +``` + +[`create-astro`](https://github.com/snowpackjs/astro/tree/main/packages/create-astro) 精靈提供一些[上手範本](/examples)進行挑選。或者，也可以直接從 Github 匯入自己的 Astro 專案。 + +```bash +# 提醒：把「my-astro-project」改為專案的名稱。 + +# npm 6.x +npm init astro my-astro-project --template starter +# npm 7+（一定要多加上一組雙橫槓） +npm init astro my-astro-project -- --template starter +# yarn +yarn create astro my-astro-project --template starter +# 使用第三方範本 +npm init astro my-astro-project -- --template [GITHUB_USER]/[REPO_NAME] +# 在 Repo 裡，使用第三方範本 +npm init astro my-astro-project -- --template [GITHUB_USER]/[REPO_NAME]/path/to/template +``` + +`create-astro` 架設好專案的基礎外框之後，記得要用 npm 或偏好的套件管理工具，安裝專案的相依套件。範例裡使用 npm： + +```bash +npm install +``` + +現在，可以[啟動](#start-astro) Astro 專案。把 Astro 專案組裝好之後，接著是 [Build](#build-astro) 專案。Astro 就會將應用程式打包起來，準備好靜態檔案，就可以[部署](/guides/deploy)至慣用的主機服務。 + +## 手動安裝 + +沒有 `create-astro` 精靈的協助，也可以設定 Astro。接下來就是要讓 Astro 動起來的一些額外步驟。 + +### 設定專案 + +```bash +# 建立、進入新資料夾 +mkdir my-astro-project +cd my-astro-project +``` + +建立以專案名稱為名的空資料夾，接著進入該處： + +### 建立 `package.json` + +```bash +# 這個指令會建立基本的 package.json +npm init --yes +``` + +Astro 設計成與 npm 套件整體生態一起運作，由專案根目錄裡，稱為 `package.json` 的專案 Manifest 進行管理。如果不熟悉 `package.json` 檔案，強烈建議先將 [npm 文件](https://docs.npmjs.com/creating-a-package-json-file)快速讀過一遍。 + +### 安裝 Astro + +按照上方的指示之後，應該有個資料夾，裡面只有 `package.json` 一個檔案。現在即可在專案裡設定 Astro。 + +```bash +npm install astro +``` + +取代 `package.json` 檔案裡，從 `npm init` 產生、一開始就有的 "script" 部分： + +```diff + "scripts": { +- "test": "echo \"Error: no test specified\" && exit 1" ++ "start": "astro dev", ++ "build": "astro build" + }, +} +``` + +[`start`](#start-astro) 指令在 `http://localhost:3000` 啟動 Astro 開發伺服器。一但專案已經準備好，[`build`](#build-astro) 指令將專案輸出至 `dist/` 資料夾。[在「部署指南」深入閱讀部署 Astro](/guides/deploy)。 + +### 建立第一個頁面 + +打開偏好的文字編輯器，接著在專案裡新增檔案： + +1. 在 `src/pages/index.astro` 新增檔案 +2. 在檔案裡複製貼上以下程式碼片段（包含橫槓 `---` ）： + +```astro +--- +// 在程式碼 fence 之間寫的 JS/TS 程式碼， +// 只會在伺服器端執行！ +console.log('See me in the Terminal') +--- + + + +

Hello, World!

+ + + + + + +``` + +以上就是 Astro 的元件語法範例，同時包含 HTML 和 JSX。 + +在 `src/pages` 資料夾裡還可以加入更多頁面，Astro 就會使用檔案名稱建立網站的新頁面。舉例來說，位在 `src/pages/about.astro` 的檔案（可以重複使用上面的程式碼片段），Astro 就會有網址是 `http://localhost/about` 的新頁面。 + +## [啟動 Astro](#start-astro) + +```bash +npm start +``` + +Astro 會為應用程式打開 `http://localhost:3000` 的伺服器。在瀏覽器開啟網址，就會看到 Astro 的「Hello World」。 + +## [Build Astro](#build-astro) + +```bash +npm run build +``` + +這樣就會指揮 Astro 開始 Build 網站，存在磁碟裡。現在，應用程式已經放在 `dist/` 資料夾裡準備好了。 + +### 下一步 + +成功了！現在即可開始開發！ + +我們建議花點時間更熟悉 Astro 的運作方式。只要在文件裡進一步探索，建議看看這些： + +📚 深入了解 Astro 的專案架構：[專案架構指南。](/core-concepts/project-structure) + +📚 深入了解 Astro 的元件語法：[Astro 元件指南。](/core-concepts/astro-components) + +📚 深入了解 Astro 根據檔案產生的路徑：[路徑指南。](core-concepts/astro-pages) diff --git a/docs/src/pages/zh-TW/quick-start.md b/docs/src/pages/zh-TW/quick-start.md new file mode 100644 index 000000000..9d7ded5ab --- /dev/null +++ b/docs/src/pages/zh-TW/quick-start.md @@ -0,0 +1,71 @@ +--- +layout: ~/layouts/MainLayout.astro +title: 快速開始 +lang: zh-Hant-TW +--- + +```shell +# 環境需求：檢查 Node.js 版本是 12.20.0+、14.13.1+ 或 16+。 +node --version + +# 開新專案資料夾，並且直接移動到該處 +mkdir my-astro-project && cd $_ + +# 準備發射... +npm init astro + +# 安裝相依套件 +npm install + +# 開始開發！ +npm start + +# 做好之後：把靜態網站 build 進 `dist/` +npm run build +``` + +若想要知道還有哪些方法能夠以 Astro 來做專案，請[閱讀安裝指南](installation)。 + +## 開始專案 + +專案目錄裡，在終端機輸入以下指令： + +```bash +npm start +``` + +現在，Astro 就會開啟應用程式的伺服器，位置是 [http://localhost:3000](http://localhost:3000)。在瀏覽器打開這網址，就會看到 Astro 的 「Hello, World」。 + +伺服器會即時監聽 `src/` 資料夾的檔案異動，所以在開發過程的更新毋需重新啟動應用程式。 + +## Build 專案 + +若要將專案 Build 起來，移至資料夾裡面，在終端機輸入指令： + +```bash +npm run build +``` + +這樣就會指揮 Astro 開始 Build 網站，存在磁碟裡。現在，應用程式已經放在 `dist/` 資料夾裡準備好了。 + +## 部署專案 + +Astro 網站是靜態的，所以可以發布至慣用的主機： + +- [Vercel](https://vercel.com/) +- [Netlify](https://www.netlify.com/) +- [S3 bucket](https://aws.amazon.com/s3/) +- [Google Firebase](https://firebase.google.com/) +- [「部署指南」有更多部署 Astro 的細節。](/guides/deploy) + +## 下一步 + +成功了！現在即可開始開發！ + +我們建議花點時間更熟悉 Astro 的運作方式。只要在文件裡進一步探索，建議看看這些： + +📚 深入了解 Astro 的專案架構：[專案架構指南。](/core-concepts/project-structure) + +📚 深入了解 Astro 的元件語法：[Astro 元件指南。](/core-concepts/astro-components) + +📚 深入了解 Astro 根據檔案產生的路徑：[路徑指南。](core-concepts/astro-pages)