Scaladoc

靜態文件

此文件頁面專屬於 Scala 3，可能涵蓋 Scala 2 中沒有的新概念。除非另有說明，此頁面中的所有程式碼範例都假設您使用的是 Scala 3。

Scaladoc 可以產生靜態網站，例如 Jekyll 或 Docusaurus。具備結合工具可提供靜態文件和 API 之間的互動，因此兩者可以自然地融合。

建立網站就像在 Jekyll 中一樣簡單。網站根目錄包含網站的版面配置，放在那裡的檔案將被視為靜態檔案，或處理範本擴充。

考慮用於範本擴充的檔案必須以 *.{html,md} 結尾，從這裡開始將它們稱為「範本檔案」或「範本」。

一個簡單的「hello world」網站可能如下所示

.
└── <site-root>/
    └── _docs/
        ├── index.html
        └── getting-started.html

這將提供一個網站，其中包含產生文件中的下列檔案

index.html
getting-started.html

Scaladoc 可以轉換檔案和目錄（將您的文件整理成樹狀結構）。預設情況下，目錄的標題基於檔案名稱，且內容為空。您可以透過在專用目錄中建立 index.html 或 index.md（不可同時建立）來提供每個區段的索引頁面。

在產生靜態網站之前，您需要在文件 scalacOptions 中設定 -siteroot 值。此值是存放文件的目錄。產生文件的基本 URL 也會是 <site-root>。

例如，如果您有一個名為 docs 的目錄，並且您希望將其視為您的網站根目錄

.
└── docs/
    └── _docs/
        ├── index.html
        └── getting-started.html

那麼配置如下

Compile / doc / scalacOptions ++= Seq("-siteroot", "docs")

請記住，要使用所有功能（例如搜尋或摘要）在本地檢視您的網站，需要一個本機伺服器。例如，如果您的輸出目錄是 output，您可以使用 Python 伺服器透過執行下列動作並開啟 localhost:8080 來檢視所有內容

cd output
python3 -m http.server 8080

屬性

Scaladoc 使用 Liquid 範本引擎，並提供數個特定於 Scala 文件的客製化篩選器和標籤。

下列專案相關變數可用，且可以使用雙大括號存取 (例如 ``)

projectTitle 使用 -project 標記定義的專案標題。
projectVersion 使用 -project-version 標記定義的專案版本。

在 Scaladoc 中，所有範本都可以包含 YAML 前置事項。前置事項會被剖析並放入範本中透過 Liquid 可用的 page 變數。

前置事項範例

---
title: My custom title
---

Scaladoc 使用一些預先定義的屬性來控制頁面的某些方面。

預先定義的屬性

title 提供將用於導覽和 HTML 元資料的頁面標題。
extraCss 將包含在此頁面的其他 .css 檔案。路徑應相對於文件根目錄。此設定不會匯出至範本引擎。
extraJs 將包含在此頁面的其他 .js 檔案。路徑應相對於文件根目錄。此設定不會匯出至範本引擎。
hasFrame 當設為 false 時，頁面將不會包含預設版面配置 (導覽、麵包屑等)，而只會包含代幣 HTML 包裝器來提供元資料和資源 (js 和 css 檔案)。此設定不會匯出至範本引擎。
layout - 預先定義的版面配置，請參閱下方。此設定不會匯出至範本引擎。

重新導向屬性

除了預先定義的屬性之外，Scaladoc 還支援重新導向屬性，讓您可以從一個頁面重新導向至另一個頁面。當您將頁面移至新位置，但希望舊的 URL 仍然有效時，這會很有用。

redirectFrom - 指定您要從中重新導向的 URL。透過使用 redirectFrom 屬性，Scaladoc 會在指定的 URL 中產生一個空白頁面，其中包含一個瀏覽器導向至新位置的重新導向。

範例

---
redirectFrom: /absolute/path/to/old/url.html
---

在上面的範例中，如果您將頁面從 /absolute/path/to/old/url.html 移至新位置，您可以使用 redirectFrom 來確保舊的 URL 仍會重新導向至新位置。

請注意，redirectFrom 屬性是受到 Jekyll 外掛程式 jekyll-redirect-from 的啟發。

redirectTo - 指定您要重新導向到的 URL。當您想要重新導向至外部頁面或無法使用 redirectFrom 時，這個屬性會很有用。

範例

---
redirectTo: https://scala-docs.dev.org.tw/
---

在上面的範例中，頁面將會重新導向至 https://scala-docs.dev.org.tw/。

使用現有的範本和版面

為了執行範本擴充，Dottydoc 會查看前置資料中的 layout 欄位。以下是範本系統實際運作的一個簡單範例，index.html

---
layout: main
---

<h1>Hello world!</h1>

使用類似這樣的一個簡單主範本

<html>
    <head>
        <title>Hello, world!</title>
    </head>
    <body>
        {{ content }}
    </body>
</html>

將會導致 {{ content }} 被 index.html 檔案中的 <h1>Hello world!</h1> 取代。

版面必須放置在網站根目錄中的 _layouts 目錄中

├── _layouts
│   └── main.html
└── _docs
    ├── getting-started.md
    └── index.html

資源

為了要與靜態網站一起呈現資源，它們需要放置在網站根目錄中的 _assets 目錄中

├── _assets
│   └── images
│        └── myimage.png
└── _docs
    └── getting-started.md

要在頁面上參照資源，需要建立一個相對於 _assets 目錄的連結

Take a look at the following image: [My image](images/myimage.png)

預設情況下，Scaladoc 會反映已渲染網站中 _docs 目錄的目錄結構。也可以透過在網站根目錄中提供 sidebar.yml 檔案來覆寫它。YAML 組態檔案會描述已渲染靜態網站的結構和目錄

index: index.html
subsection:
    - title: Usage
      index: usage/index.html
      directory: usage
      subsection:
        - title: Dottydoc
          page: usage/dottydoc.html
          hidden: false
        - title: sbt-projects
          page: usage/sbt-projects.html
          hidden: false

根元素需要是 subsection。巢狀小節會產生樹狀的導覽結構。

subsection 屬性為

title - 選擇性字串 - 小節的預設標題。前置標題優先順序較高。
index - 選擇性字串 - 小節索引頁面的路徑。路徑相對於 _docs 目錄。
directory - 選擇性字串 - 在已產生網站中會包含小節的目錄名稱。預設情況下，目錄名稱是小節名稱轉換為 kebab case。
subsection - subsection 或 page 的陣列。

必須定義 index 或 subsection。使用 index 定義且不使用 subsection 的小節，會包含從索引頁面目錄遞迴載入的頁面和目錄。

page 屬性為

title - 選擇性字串 - 頁面的預設標題。前置標題優先順序較高。
page - 字串 - 相對於 _docs 目錄的頁面路徑。
hidden - 選擇性布林值 - 旗標，表示頁面是否應顯示在導覽側欄中。預設設定為 false。

注意：YAML 組態檔案中的所有路徑都相對於 <static-root>/_docs。

標題階層

如果標題指定多次，優先順序如下（從最高到最低優先順序）

頁面

title 來自 markdown/html 檔案的 front-matter
title 屬性來自 sidebar.yml 屬性
檔案名稱

小節

title 來自 markdown/html 索引檔案的 front-matter
title 屬性來自 sidebar.yml 屬性
檔案名稱

請注意，如果您在樹狀結構中跳過 index 檔案，或者您未在 frontmatter 中指定 title，將會給予通用名稱 index。在使用 sidebar.yml 但未指定 title 或 index，只有一個小節時，也會套用相同規則。同樣會出現通用 index 名稱。

部落格

部落格功能說明在另一份文件

進階設定

網站根目錄的完整結構

.
└── <site-root>/
    ├── _layouts/
    │   └── ...
    ├── _docs/
    │   └── ...
    ├── _blog/
    │   ├── index.md
    │   └── _posts/
    │       └── ...
    └── _assets/
        ├── js/
        │   └── ...
        ├── img/
        │   └── ...
        └── ...

它會產生一個包含文件和部落格的靜態網站。它也包含自訂版面和資源。已呈現文件結構可以基於檔案系統，但也可以由 YAML 設定覆寫。

對應目錄結構

使用 YAML 設定檔，我們可以定義原始目錄結構應如何轉換成輸出目錄結構。

看看以下小節定義

- title: Some other subsection
  index: abc/index.html
  directory: custom-directory
  subsection:
    - page: abc2/page1.md
    - page: foo/page2.md

這個小節顯示 YAML 設定對應目錄結構的能力。即使索引頁面和所有定義的子目錄在不同的目錄中，它們仍會在 custom-directory 中呈現。原始頁面 abc/index.html 會產生頁面 custom-directory/index.html，原始頁面 abc2/page1.md 會產生頁面 custom-directory/page1.html，原始頁面 foo/page2.md 會產生頁面 custom-directory/page2.html。

← 上一個 下一個 →