Facebook Docusaurus 中文文檔 siteConfig.js 詳解

此係列文章的應用示例已發佈於 GitHub: docusaurus-docs-Zh_CN. 能夠 Fork 幫助改進或 Star 關注更新. 歡迎 Star.

siteConfig.js

網站配置的很大一部分是經過編輯 siteConfig.js 文件完成的。

用戶展現

users 數組用於存儲要在您的站點上顯示的每一個項目/用戶的對象。 目前這個字段被提供給 pages/en/index.js 和 pages/en/users.js 文件使用。 每一個用戶對象應該有 caption，image，infoLink 和 pinned 字段。caption 是當某人懸停在該用戶的 image 上時顯示的文本，而 infoLink 則是點擊該圖片將會某人誰去哪。 pinned 字段決定它是否顯示在 index頁面上。

目前這個 users 數組只用於 index.js 和 users.js 示例文件。 若是您不但願在 index 頁面上顯示用戶頁面或顯示用戶，則能夠刪除此部分。

siteConfig 字段

siteConfig 對象包含你的網站的大部分配置設置。

必選字段

title - 網站的標題

tagline - 網站的標語

url - 網站的 URL

baseUrl - 網站的 baseUrl

projectName - 項目名稱. 這必須匹配你的 GitHub 倉庫項目名稱（區分大小寫）。

noIndex - 布爾。 若是爲真，Docusaurus 會禮貌地要求爬蟲和搜索引擎避免索引您的網站。 這是用 header 標籤完成的，因此只適用於文檔和頁面。 不會試圖隱藏靜態資源。 這是一個盡最大努力的要求。 惡意抓取工具仍然能夠繼續爲您的網站編制索引。

headerLinks - 將在標題導航欄中使用的連接。 每一個對象的 label 字段將成爲連接文本，也將被翻譯爲每種語言。

使用示例:

headerLinks: [
  // 連接到當前 語言/版本 而且 ID 爲 doc1 的文檔
  { doc: "doc1", label: "Getting Started" },
  // 使用當前語言連接到 pages/en/help.js 中找到的頁面，若是不存在，則使用 pages/help.js。
  { page: "help", label: "Help" },
  // 連接到 href 目的地
  { href: "https://github.com/", label: "GitHub" },
  // 由 Docusaurus (${baseUrl}blog) 生成的博客連接
  { blog: true, label: "Blog" },
  // 判斷連接中的搜索欄的位置
  { search: true },
  // 判斷連接中的語言下拉菜單的位置
  { languages: true }
],

headerIcon - 標題導航欄中使用的圖標的 URL。

favicon - 網站 favicon 的 URL。

colors - 網站的顏色配置。

• primaryColor 是用於標題導航欄和側邊欄的顏色。
• secondaryColor 是用於當站點窗口很窄時（包括在移動設備上）在頁眉導航欄的第二行中看到的顏色。
• 也能夠添加自定義顏色配置。 例如，若是用指定爲 $myColor 的顏色添加用戶樣式，則將 myColor 字段添加到 colors 將可讓您輕鬆配置此顏色。

copyright - 網站頁腳和訂閱內的版權字符串

可選字段

默認狀況下，Docusaurus 但願您的文檔位於名爲 docs 的目錄中。 該目錄與 website 目錄處於同一級別（即不在 website 目錄內）。 您可使用此字段指定文檔的自定義路徑。請注意，全部文檔的*.md文件都必須位於平面層次結構中。 不可使用文件嵌套目錄。

customDocsPath: "docs/site"

customDocsPath: "website-docs"

useEnglishUrl - 若是你沒有啓用 翻譯（例如，經過一個 languages.js 文件），那麼仍然須要一個 /docs/en/doc.html 形式的連接 en），將其設置爲 true。

organizationName - 託管此項目的組織或用戶的 GitHub 用戶名。 發佈腳本使用它來肯定您的 GitHub 頁面網站的託管位置。

editUrl - 用於編輯文檔的 URL，用法示例：editUrl + 'en/doc1.md'。 若是此字段被省略，則每一個文檔將不會有 "Edit this Doc" 按鈕。

users - 前面提到的 users 數組。

disableHeaderTitle - 能夠選擇禁止在標題圖標旁邊顯示標題。 排除此字段以保持標題正常，不然設置爲 true。

disableTitleTagline - 禁止在主頁標題中顯示標語的選項。 排除此字段可將頁面標題保留爲 Title • Tagline。 設置爲 true，使頁面標題只是 Title。

separateCss - 其中任何 css 文件不會被處理並鏈接到 Docusaurus 的樣式文件夾。 這是爲了支持靜態的 html 頁面，它能夠與 Docusaurus 樣式徹底獨立的分開。

footerIcon - 頁腳圖標的 URL。 目前在 core/Footer.js 文件中使用，可是能夠從該文件中刪除。

translationRecruitingLink - 當啓用除英文之外的語言時，語言選擇的 Help Translate 選項卡的 URL。 這能夠包括你正在使用的翻譯，但不必定都是這樣。

algolia - Algolia 搜索集成信息。 若是該字段被排除，搜索欄將不會出如今標題中。

gaTrackingId - Google Analytics 跟蹤 ID 來跟蹤頁面瀏覽量。

facebookAppId - 若是你想在你博客文章底部的 Facebook Like/Share 按鈕，提供一個Facebook應用程序ID，而且按鈕將顯示在全部的博客文章。

twitter - 若是你想讓一個 Twitter 的社交按鈕出如今你的博客文章的底部，請將其設置爲 true。

highlight - 語法突出顯示 參數:

• theme 是語法突出顯示時 Highlight.js 使用的主題的名稱。 你能夠在這裏找到支持的主題列表。
• version 指定要使用的特定版本的 Highlight.js。
• hljs 經過將 Highlight.js 的實例傳遞給此處指定的函數來提供一個接口，從而容許註冊語法突出顯示的其餘語言。
• defaultLang 定義一個默認的語言。 若是沒有在代碼塊的頂部指定它，將會使用它。 你能夠在這裏找到支持的語言列表。

markdownPlugins - 一個由 Remarkable 加載的插件數組，Docusaurus 使用的 markdown 解析器和渲染器。 該插件將接收對 Remarkable 實例的引用，容許定義自定義分析和呈現規則。

wrapPagesHTML - 布爾標誌來指示 /pages 中的 html 文件是否應該用網站頁眉和頁腳的Docusaurus 樣式進行封裝。 這個功能是實驗性的，依賴於文件是 html 片斷而不是完整的頁面。 它插入的 html 文件的內容沒有額外的處理。 默認爲 false。

scripts - 要加載的 JavaScript 源數組。 腳本標籤將被插入到 HTML 頭中。

stylesheets - 要加載的 CSS 源數組。 連接標籤將被插入到 HTML 頭中。

cname - 您的網站的 CNAME。 當您的網站創建時，它會進入一個 CNAME 文件。

若是用戶但願跨不一樣文件提供一些數據，用戶也能夠添加本身的自定義字段。

siteConfig.js 全字段示例

const users = [
  {
    caption: "User1",
    image: "/test-site/img/docusaurus.svg",
    infoLink: "https://www.example.com",
    pinned: true
  }
];

const siteConfig = {
  title: "Docusaurus",
  tagline: "Generate websites!",
  url: "https://docusaurus.io",
  baseUrl: "/",
// 對於 github.io 類型的 URLS，你能夠將 url 和 baseUrl 結合起來：
// url: "https://reasonml.github.io",
// url: "/reason-react/",
  organizationName: "facebook",
  projectName: "docusaurus",
  noIndex: false,
  headerLinks: [
    { doc: "doc1", label: "Docs" },
    { page: "help", label: "Help" },
    { search: true },
    { blog: true }
  ],
// 對於頂部導航欄中沒有標題連接 -> headerLinks: [],
  headerIcon: "img/docusaurus.svg",
  favicon: "img/favicon.png",
  colors: {
    primaryColor: "#2E8555",
    secondaryColor: "#205C3B"
  },
  editUrl: "https://github.com/facebook/docusaurus/edit/master/docs/",
  users,
  disableHeaderTitle: true,
  disableTitleTagline: true,
  separateCss: ["static/css/non-docusaurus", "static/assets/separate-css"],
  footerIcon: "img/docusaurus.svg",
  translationRecruitingLink:
    "https://crowdin.com/project/docusaurus",
  algolia: {
    apiKey:
      "0f9f28b9ab9efae89810921a351753b5",
    indexName: "github"
  },
  gaTrackingId: "U-A2352",
  highlight: {
    theme: 'default'
  },
  markdownPlugins: [
    function foo(md) {
      md.renderer.rules.fence_custom.foo = function(tokens, idx, options, env, instance) {
        return '<div class="foo">bar</div>';
      }
    }
  ],
  scripts: [ "https://docusaurus.io/slash.js" ],
  stylesheets: [ "https://docusaurus.io/style.css" ],
  facebookAppId: "1615782811974223",
  twitter: "true"
};

module.exports = siteConfig;

若是這篇文章對您有幫助, 感謝 下方點贊 或 Star GitHub: docusaurus-docs-Zh_CN 支持, 謝謝.