diff options
Diffstat (limited to 'themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/index.zh-cn.md')
| -rw-r--r-- | themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/index.zh-cn.md | 1032 |
1 files changed, 1032 insertions, 0 deletions
diff --git a/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/index.zh-cn.md b/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/index.zh-cn.md new file mode 100644 index 0000000..06029e5 --- /dev/null +++ b/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/index.zh-cn.md @@ -0,0 +1,1032 @@ +--- +weight: 1 +title: "主题文档 - 基本概念" +date: 2020-03-06T21:40:32+08:00 +lastmod: 2020-03-06T21:40:32+08:00 +draft: false +author: "Sunt Programator!" +authorLink: "https://suntprogramator.dev/" +description: "探索 Hugo - CodeIT 主题的全部内容和背后的核心概念." +resources: + - name: "featured-image" + src: "featured-image.jpg" + +tags: ["installation", "configuration"] +categories: ["documentation"] + +lightgallery: true + +toc: + auto: false +--- + +探索 Hugo - **CodeIT** 主题的全部内容和背后的核心概念. + +<!--more--> + +## 1 准备 + +由于 Hugo 提供的便利性, [Hugo](https://gohugo.io/) 本身是这个主题唯一的依赖. + +直接安装满足你操作系统 (**Windows**, **Linux**, **macOS**) 的最新版本 [:(far fa-file-archive fa-fw): Hugo (> 0.78.1)](https://gohugo.io/getting-started/installing/). + +{{< admonition tip "推荐使用 Hugo extended 版本" >}} +由于这个主题的一些特性需要将 :(fab fa-sass fa-fw): SCSS 转换为 :(fab fa-css3 fa-fw): CSS, 推荐使用 Hugo **extended** 版本来获得更好的使用体验. +{{< /admonition >}} + +## 2 安装 + +以下步骤可帮助你初始化新网站. 如果你根本不了解 Hugo, 我们强烈建议你按照此 [快速入门文档](https://gohugo.io/getting-started/quick-start/) 进一步了解它. + +### 2.1 创建你的项目 + +Hugo 提供了一个 `new` 命令来创建一个新的网站: + +```bash +hugo new site my_website +cd my_website +``` + +### 2.2 安装主题 + +**CodeIT** 主题的仓库是: [https://github.com/sunt-programator/CodeIT](https://github.com/sunt-programator/CodeIT). + +你可以下载主题的 [最新版本 :(far fa-file-archive fa-fw): .zip 文件](https://github.com/sunt-programator/CodeIT/releases) 并且解压放到 `themes` 目录. + +另外, 也可以直接把这个主题克隆到 `themes` 目录: + +```bash +git clone https://github.com/sunt-programator/CodeIT.git themes/CodeIT +``` + +或者, 初始化你的项目目录为 git 仓库, 并且把主题仓库作为你的网站目录的子模块: + +```bash +git init +git submodule add https://github.com/sunt-programator/CodeIT.git themes/CodeIT +``` + +### 2.3 基础配置 {#basic-configuration} + +以下是 CodeIT 主题的基本配置: + +```toml +baseURL = "http://example.org/" +# [en, zh-cn, fr, ...] 设置默认的语言 +defaultContentLanguage = "zh-cn" +# 网站语言, 仅在这里 CN 大写 +languageCode = "zh-CN" +# 是否包括中日韩文字 +hasCJKLanguage = true +# 网站标题 +title = "我的全新 Hugo 网站" + +# 更改使用 Hugo 构建网站时使用的默认主题 +theme = "CodeIT" + +[params] + # CodeIT 主题版本 + version = "0.2.X" + +[menu] + [[menu.main]] + identifier = "posts" + # 你可以在名称 (允许 HTML 格式) 之前添加其他信息, 例如图标 + pre = "" + # 你可以在名称 (允许 HTML 格式) 之后添加其他信息, 例如图标 + post = "" + name = "文章" + url = "/posts/" + # 当你将鼠标悬停在此菜单链接上时, 将显示的标题 + title = "" + weight = 1 + [[menu.main]] + identifier = "tags" + pre = "" + post = "" + name = "标签" + url = "/tags/" + title = "" + weight = 2 + [[menu.main]] + identifier = "categories" + pre = "" + post = "" + name = "分类" + url = "/categories/" + title = "" + weight = 3 + +# Hugo 解析文档的配置 +[markup] + # 语法高亮设置 (https://gohugo.io/content-management/syntax-highlighting) + [markup.highlight] + # false 是必要的设置 (https://github.com/sunt-programator/CodeIT/issues/158) + noClasses = false +``` + +{{< admonition >}} +在构建网站时, 你可以使用 `--theme` 选项设置主题. 但是, 我建议你修改配置文件 (**config.toml**) 将本主题设置为默认主题. +{{< /admonition >}} + +### 2.4 创建你的第一篇文章 + +以下是创建第一篇文章的方法: + +```bash +hugo new posts/first_post.md +``` + +通过添加一些示例内容并替换文件开头的标题, 你可以随意编辑文章. + +{{< admonition >}} +默认情况下, 所有文章和页面均作为草稿创建. 如果想要渲染这些页面, 请从元数据中删除属性 `draft: true`, 设置属性 `draft: false` 或者为 `hugo` 命令添加 `-D`/`--buildDrafts` 参数. +{{< /admonition >}} + +### 2.5 在本地启动网站 + +使用以下命令启动网站: + +```bash +hugo serve +``` + +去查看 `http://localhost:1313`. + + + +{{< admonition tip >}} +当你运行 `hugo serve` 时, 当文件内容更改时, 页面会随着更改自动刷新. +{{< /admonition >}} + +{{< admonition >}} +由于本主题使用了 Hugo 中的 `.Scratch` 来实现一些特性, +非常建议你为 `hugo server` 命令添加 `--disableFastRender` 参数来实时预览你正在编辑的文章页面. + +```bash +hugo serve --disableFastRender +``` + +{{< /admonition >}} + +### 2.6 构建网站 + +当你准备好部署你的网站时, 运行以下命令: + +```bash +hugo +``` + +会生成一个 `public` 目录, 其中包含你网站的所有静态内容和资源. 现在可以将其部署在任何 Web 服务器上. + +{{< admonition tip >}} +网站内容可以通过 [Netlify](https://www.netlify.com/) 自动发布和托管 (了解有关[通过 Netlify 进行 HUGO 自动化部署](https://www.netlify.com/blog/2015/07/30/hosting-hugo-on-netlifyinsanely-fast-deploys/) 的更多信息). +或者, 您可以使用 [AWS Amplify](https://gohugo.io/hosting-and-deployment/hosting-on-aws-amplify/), [Github pages](https://gohugo.io/hosting-and-deployment/hosting-on-github/), [Render](https://gohugo.io/hosting-and-deployment/hosting-on-render/) 以及更多... +{{< /admonition >}} + +## 3 配置 + +### 3.1 网站配置 {#site-configuration} + +除了 [Hugo 全局配置](https://gohugo.io/overview/configuration/) 和 [菜单配置](#basic-configuration) 之外, **CodeIT** 主题还允许您在网站配置中定义以下参数 (这是一个示例 `config.toml`, 其内容为默认值). + +请打开下面的代码块查看完整的示例配置 :(far fa-hand-point-down fa-fw):: + +```toml +[params] + # CodeIT 主题版本 + version = "0.2.X" + # 网站描述 + description = "这是我的全新 Hugo 网站" + # 网站关键词 + keywords = ["Theme", "Hugo"] + # 网站默认主题样式 ("light", "dark", "auto") + defaultTheme = "auto" + # 公共 git 仓库路径，仅在 enableGitInfo 设为 true 时有效 + gitRepo = "" + # 哪种哈希函数用来 SRI, 为空时表示不使用 SRI + # ("sha256", "sha384", "sha512", "md5") + fingerprint = "" + # 日期格式 + dateFormat = "2006-01-02" + # 网站图片, 用于 Open Graph 和 Twitter Cards + images = ["/logo.png"] + + # 应用图标配置 + [params.app] + # 当添加到 iOS 主屏幕或者 Android 启动器时的标题, 覆盖默认标题 + title = "CodeIT" + # 是否隐藏网站图标资源链接 + noFavicon = false + # 更现代的 SVG 网站图标, 可替代旧的 .png 和 .ico 文件 + svgFavicon = "" + # Android 浏览器主题色 + themeColor = "#ffffff" + # Safari 图标颜色 + iconColor = "#5bbad5" + # Windows v8-10磁贴颜色 + tileColor = "#da532c" + + # 搜索配置 + [params.search] + enable = true + # 搜索引擎的类型 ("lunr", "algolia") + type = "lunr" + # 文章内容最长索引长度 + contentLength = 4000 + # 搜索框的占位提示语 + placeholder = "" + # 最大结果数目 + maxResultLength = 10 + # 结果内容片段长度 + snippetLength = 50 + # 搜索结果中高亮部分的 HTML 标签 + highlightTag = "em" + # 是否在搜索索引中使用基于 baseURL 的绝对路径 + absoluteURL = false + [params.search.algolia] + index = "" + appID = "" + searchKey = "" + + # 页面头部导航栏配置 + [params.header] + # 桌面端导航栏模式 ("fixed", "normal", "auto") + desktopMode = "fixed" + # 移动端导航栏模式 ("fixed", "normal", "auto") + mobileMode = "auto" + # 页面头部导航栏标题配置 + [params.header.title] + # LOGO 的 URL + logo = "" + # 标题名称 + name = "" + # 你可以在名称 (允许 HTML 格式) 之前添加其他信息, 例如图标 + pre = "" + # 你可以在名称 (允许 HTML 格式) 之后添加其他信息, 例如图标 + post = "" + # 是否为标题显示打字机动画 + typeit = false + + # 页面底部信息配置 + [params.footer] + enable = true + # 自定义内容 (支持 HTML 格式) + custom = '' + # 是否显示 Hugo 和主题信息 + hugo = true + # 是否显示版权信息 + copyright = true + # 是否显示作者 + author = true + # 网站创立年份 + since = 2019 + # ICP 备案信息，仅在中国使用 (支持 HTML 格式) + icp = "" + # 许可协议信息 (支持 HTML 格式) + license = '<a rel="license external nofollow noopener noreffer" href="https://creativecommons.org/licenses/by-nc/4.0/" target="_blank">CC BY-NC 4.0</a>' + + # Section (所有文章) 页面配置 + [params.section] + # section 页面每页显示文章数量 + paginate = 20 + # 日期格式 (月和日) + dateFormat = "01-02" + # RSS 文章数目 + rss = 10 + + # List (目录或标签) 页面配置 + [params.list] + # list 页面每页显示文章数量 + paginate = 20 + # 日期格式 (月和日) + dateFormat = "01-02" + # RSS 文章数目 + rss = 10 + + # 主页配置 + [params.home] + # RSS 文章数目 + rss = 10 + # 主页个人信息 + [params.home.profile] + enable = true + # Gravatar 邮箱，用于优先在主页显示的头像 + gravatarEmail = "" + # 主页显示头像的 URL + avatarURL = "/images/avatar.png" + # 主页显示的网站标题 (支持 HTML 格式) + title = "" + # 主页显示的网站副标题 + subtitle = "这是我的全新 Hugo 网站" + # 是否为副标题显示打字机动画 + typeit = true + # 是否显示社交账号 + social = true + # 免责声明 (支持 HTML 格式) + disclaimer = "" + # 主页文章列表 + [params.home.posts] + enable = true + # 主页每页显示文章数量 + paginate = 6 + # 被 params.page 中的 hiddenFromHomePage 替代 + # 当你没有在文章前置参数中设置 "hiddenFromHomePage" 时的默认行为 + defaultHiddenFromHomePage = false + + # 作者的社交信息设置 + [params.social] + GitHub = "xxxx" + Linkedin = "" + Twitter = "xxxx" + Instagram = "xxxx" + Facebook = "xxxx" + Telegram = "xxxx" + Medium = "" + Gitlab = "" + Youtubelegacy = "" + Youtubecustom = "" + Youtubechannel = "" + Tumblr = "" + Quora = "" + Keybase = "" + Pinterest = "" + Reddit = "" + Codepen = "" + FreeCodeCamp = "" + Bitbucket = "" + Stackoverflow = "" + Weibo = "" + Odnoklassniki = "" + VK = "" + Flickr = "" + Xing = "" + Snapchat = "" + Soundcloud = "" + Spotify = "" + Bandcamp = "" + Paypal = "" + Fivehundredpx = "" + Mix = "" + Goodreads = "" + Lastfm = "" + Foursquare = "" + Hackernews = "" + Kickstarter = "" + Patreon = "" + Steam = "" + Twitch = "" + Strava = "" + Skype = "" + Whatsapp = "" + Zhihu = "" + Douban = "" + Angellist = "" + Slidershare = "" + Jsfiddle = "" + Deviantart = "" + Behance = "" + Dribbble = "" + Wordpress = "" + Vine = "" + Googlescholar = "" + Researchgate = "" + Mastodon = "" + Thingiverse = "" + Devto = "" + Gitea = "" + XMPP = "" + Matrix = "" + Bilibili = "" + Email = "xxxx@xxxx.com" + RSS = true # + + # 文章页面配置 + [params.page] + # 是否在主页隐藏一篇文章 + hiddenFromHomePage = false + # 是否在搜索结果中隐藏一篇文章 + hiddenFromSearch = false + # 是否使用 twemoji + twemoji = false + # 是否使用 lightgallery + lightgallery = false + # 是否使用 ruby 扩展语法 + ruby = true + # 是否使用 fraction 扩展语法 + fraction = true + # 是否使用 fontawesome 扩展语法 + fontawesome = true + # 是否在文章页面显示原始 Markdown 文档链接 + linkToMarkdown = true + # 是否在 RSS 中显示全文内容 + rssFullText = false + # 目录配置 + [params.page.toc] + # 是否使用目录 + enable = true + # 是否保持使用文章前面的静态目录 + keepStatic = true + # 是否使侧边目录自动折叠展开 + auto = true + # 代码配置 + [params.page.code] + # 是否显示代码块的复制按钮 + copy = true + # 默认展开显示的代码行数 + maxShownLines = 10 + # {{< link "https://katex.org/" KaTeX >}} 数学公式 + [params.page.math] + enable = true + # 默认块定界符是 $$ ... $$ 和 \\[ ... \\] + blockLeftDelimiter = "" + blockRightDelimiter = "" + # 默认行内定界符是 $ ... $ 和 \\( ... \\) + inlineLeftDelimiter = "" + inlineRightDelimiter = "" + # KaTeX 插件 copy_tex + copyTex = true + # KaTeX 插件 mhchem + mhchem = true + # {{< link "https://docs.mapbox.com/mapbox-gl-js" "Mapbox GL JS" >}} 配置 + [params.page.mapbox] + # Mapbox GL JS 的 access token + accessToken = "" + # 浅色主题的地图样式 + lightStyle = "mapbox://styles/mapbox/light-v9" + # 深色主题的地图样式 + darkStyle = "mapbox://styles/mapbox/dark-v9" + # 是否添加 {{< link "https://docs.mapbox.com/mapbox-gl-js/api#navigationcontrol" NavigationControl >}} + navigation = true + # 是否添加 {{< link "https://docs.mapbox.com/mapbox-gl-js/api#geolocatecontrol" GeolocateControl >}} + geolocate = true + # 是否添加 {{< link "https://docs.mapbox.com/mapbox-gl-js/api#scalecontrol" ScaleControl >}} + scale = true + # 是否添加 {{< link "https://docs.mapbox.com/mapbox-gl-js/api#fullscreencontrol" FullscreenControl >}} + fullscreen = true + # 文章页面的分享信息设置 + [params.page.share] + enable = true + Twitter = true + Facebook = true + Linkedin = false + Whatsapp = true + Pinterest = false + Tumblr = false + HackerNews = false + Reddit = false + VK = false + Buffer = false + Xing = false + Line = true + Instapaper = false + Pocket = false + Digg = false + Stumbleupon = false + Flipboard = false + Weibo = true + Renren = false + Myspace = true + Blogger = true + Baidu = false + Odnoklassniki = false + Evernote = true + Skype = false + Trello = false + Mix = false + # 评论系统设置 + [params.page.comment] + enable = true + # {{< link "https://disqus.com/" Disqus >}} 评论系统设置 + [params.page.comment.disqus] + enable = false + # Disqus 的 shortname，用来在文章中启用 Disqus 评论系统 + shortname = "" + # {{< link "https://github.com/gitalk/gitalk" Gitalk >}} 评论系统设置 + [params.page.comment.gitalk] + enable = false + owner = "" + repo = "" + clientId = "" + clientSecret = "" + # {{< link "https://github.com/xCss/Valine" Valine >}} 评论系统设置 + [params.page.comment.valine] + enable = false + appId = "" + appKey = "" + placeholder = "" + avatar = "mp" + meta= "" + pageSize = 10 + lang = "" + visitor = true + recordIP = true + highlight = true + enableQQ = false + serverURLs = "" + # emoji 数据文件名称, 默认是 "google.yml" + # ("apple.yml", "google.yml", "facebook.yml", "twitter.yml") + # 位于 "themes/CodeIT/assets/data/emoji/" 目录 + # 可以在你的项目下相同路径存放你自己的数据文件: + # "assets/data/emoji/" + emoji = "" + # {{< link "https://developers.facebook.com/docs/plugins/comments" "Facebook 评论系统" >}}设置 + [params.page.comment.facebook] + enable = false + width = "100%" + numPosts = 10 + appId = "" + languageCode = "zh_CN" + # {{< link "https://comments.app/" "Telegram Comments" >}} 评论系统设置 + [params.page.comment.telegram] + enable = false + siteID = "" + limit = 5 + height = "" + color = "" + colorful = true + dislikes = false + outlined = false + # {{< link "https://commento.io/" "Commento" >}} 评论系统设置 + [params.page.comment.commento] + enable = false + # {{< link "https://utteranc.es/" "Utterances" >}} 评论系统设置 + [params.page.comment.utterances] + enable = false + # owner/repo + repo = "" + issueTerm = "pathname" + label = "" + lightTheme = "github-light" + darkTheme = "github-dark" + # 第三方库配置 + [params.page.library] + [params.page.library.css] + # someCSS = "some.css" + # 位于 "assets/" + # 或者 + # someCSS = "https://cdn.example.com/some.css" + [params.page.library.js] + # someJavascript = "some.js" + # 位于 "assets/" + # 或者 + # someJavascript = "https://cdn.example.com/some.js" + # 页面 SEO 配置 + [params.page.seo] + # 图片 URL + images = [] + # 出版者信息 + [params.page.seo.publisher] + name = "" + logoUrl = "" + + # TypeIt 配置 + [params.typeit] + # 每一步的打字速度 (单位是毫秒) + speed = 100 + # 光标的闪烁速度 (单位是毫秒) + cursorSpeed = 1000 + # 光标的字符 (支持 HTML 格式) + cursorChar = "|" + # 打字结束之后光标的持续时间 (单位是毫秒, "-1" 代表无限大) + duration = -1 + + # 网站验证代码，用于 Google/Bing/Yandex/Pinterest/Baidu + [params.verification] + google = "" + bing = "" + yandex = "" + pinterest = "" + baidu = "" + + # 网站 SEO 配置 + [params.seo] + # 图片 URL + image = "" + # 缩略图 URL + thumbnailUrl = "" + + # 网站分析配置 + [params.analytics] + enable = false + # Google Analytics + [params.analytics.google] + id = "" + # 是否匿名化用户 IP + anonymizeIP = true + # Fathom Analytics + [params.analytics.fathom] + id = "" + # 自行托管追踪器时的主机路径 + server = "" + # {{< version 0.1.0 >}} Plausible Analytics + [params.analytics.plausible] + domain = "" + + # Cookie 许可配置 + [params.cookieconsent] + enable = true + # 用于 Cookie 许可横幅的文本字符串 + [params.cookieconsent.content] + message = "" + dismiss = "" + link = "" + + # 第三方库文件的 CDN 设置 + [params.cdn] + # CDN 数据文件名称, 默认不启用 + # ("jsdelivr.yml") + # 位于 "themes/CodeIT/assets/data/cdn/" 目录 + # 可以在你的项目下相同路径存放你自己的数据文件: + # "assets/data/cdn/" + data = "" + + # 兼容性设置 + [params.compatibility] + # 是否使用 Polyfill.io 来兼容旧式浏览器 + polyfill = false + # 是否使用 object-fit-images 来兼容旧式浏览器 + objectFit = false + +# Hugo 解析文档的配置 +[markup] + # {{< link "https://gohugo.io/content-management/syntax-highlighting" "语法高亮设置" >}} + [markup.highlight] + codeFences = true + guessSyntax = true + lineNos = true + lineNumbersInTable = true + # false 是必要的设置 + # ({{< link "https://github.com/sunt-programator/CodeIT/issues/158" >}}) + noClasses = false + # Goldmark 是 Hugo 0.60 以来的默认 Markdown 解析库 + [markup.goldmark] + [markup.goldmark.extensions] + definitionList = true + footnote = true + linkify = true + strikethrough = true + table = true + taskList = true + typographer = true + [markup.goldmark.renderer] + # 是否在文档中直接使用 HTML 标签 + unsafe = true + # 目录设置 + [markup.tableOfContents] + startLevel = 2 + endLevel = 6 + +# 作者配置 +[author] + name = "xxxx" + email = "" + link = "" + +# 网站地图配置 +[sitemap] + changefreq = "weekly" + filename = "sitemap.xml" + priority = 0.5 + +# {{< link "https://gohugo.io/content-management/urls#permalinks" "Permalinks 配置" >}} +[Permalinks] + # posts = ":year/:month/:filename" + posts = ":filename" + +# {{< link "https://gohugo.io/about/hugo-and-gdpr/" "隐私信息配置" >}} +[privacy] + # Google Analytics 相关隐私 (被 params.analytics.google 替代) + [privacy.googleAnalytics] + # ... + [privacy.twitter] + enableDNT = true + [privacy.youtube] + privacyEnhanced = true + +# 用于输出 Markdown 格式文档的设置 +[mediaTypes] + [mediaTypes."text/plain"] + suffixes = ["md"] + +# 用于输出 Markdown 格式文档的设置 +[outputFormats.MarkDown] + mediaType = "text/plain" + isPlainText = true + isHTML = false + +# 用于 Hugo 输出文档的设置 +[outputs] + home = ["HTML", "RSS", "JSON"] + page = ["HTML", "MarkDown"] + section = ["HTML", "RSS"] + taxonomy = ["HTML", "RSS"] + taxonomyTerm = ["HTML"] +``` + +{{< admonition >}} +请注意, 本文档其他部分将详细解释其中一些参数. +{{< /admonition >}} + +{{< admonition note "Hugo 的运行环境" >}} +`hugo serve` 的默认运行环境是 `development`, +而 `hugo` 的默认运行环境是 `production`. + +由于本地 `development` 环境的限制, +**评论系统**, **CDN** 和 **fingerprint** 不会在 `development` 环境下启用. + +你可以使用 `hugo serve -e production` 命令来开启这些特性. +{{< /admonition >}} + +{{< admonition tip "关于 CDN 配置的技巧" >}} + +```toml +[params.cdn] + # CDN 数据文件名称, 默认不启用 + # ("jsdelivr.yml") + data = "" +``` + +默认的 CDN 数据文件位于 `themes/CodeIT/assets/data/cdn/` 目录. +可以在你的项目下相同路径存放你自己的数据文件: `assets/data/cdn/`. +{{< /admonition >}} + +{{< admonition tip "关于社交链接配置的技巧" >}} + +你可以直接配置你的社交 ID 来生成一个默认社交链接和图标: + +```toml +[params.social] + Mastodon = "@xxxx" +``` + +生成的社交链接是 `https://mastodon.technology/@xxxx`. + +或者你可以通过一个字典来设置更多的选项: + +```toml +[params.social] + [params.social.Mastodon] + # 排列图标时的权重 (权重越大, 图标的位置越靠后) + weight = 0 + # 你的社交 ID + id = "@xxxx" + # 你的社交链接的前缀 + prefix = "https://mastodon.social/" + # 当鼠标停留在图标上时的提示内容 + title = "Mastodon" +``` + +所有支持的社交链接的默认数据位于 `themes/CodeIT/assets/data/social.yaml`. +你可以参考它来配置你的社交链接. +{{< /admonition >}} + + + +### 3.2 网站图标, 浏览器配置, 网站清单 + +强烈建议你把: + +- apple-touch-icon.png (180x180) +- favicon-32x32.png (32x32) +- favicon-16x16.png (16x16) +- mstile-150x150.png (150x150) +- android-chrome-192x192.png (192x192) +- android-chrome-512x512.png (512x512) + +放在 `/static` 目录. 利用 [https://realfavicongenerator.net/](https://realfavicongenerator.net/) 可以很容易地生成这些文件. + +可以自定义 `browserconfig.xml` 和 `site.webmanifest` 文件来设置 theme-color 和 background-color. + +### 3.3 自定义样式 + +{{< admonition >}} +Hugo **extended** 版本对于自定义样式是必需的. +{{< /admonition >}} + +通过定义自定义 `.scss` 样式文件, **CodeIT** 主题支持可配置的样式. + +包含自定义 `.scss` 样式文件的目录相对于 **你的项目根目录** 的路径为 `assets/css`. + +在 `assets/css/_override.scss` 中, 你可以覆盖 `themes/CodeIT/assets/css/_variables.scss` 中的变量以自定义样式. + +这是一个例子: + +```scss +@import url("https://fonts.googleapis.com/css?family=Fira+Mono:400,700&display=swap&subset=latin-ext"); +$code-font-family: Fira Mono, Source Code Pro, Menlo, Consolas, Monaco, + monospace; +``` + +在 `assets/css/_custom.scss` 中, 你可以添加一些 CSS 样式代码以自定义样式. + +## 4 多语言和 i18n + +**CodeIT** 主题完全兼容 Hugo 的多语言模式, 并且支持在网页上切换语言. + + + +### 4.1 兼容性 {#language-compatibility} + +| 语言 | Hugo 代码 | HTML `lang` 属性 | 主题文档 | Lunr.js 支持 | +| :----------- | :-------: | :--------------: | :---------------------------: | :---------------------------: | +| 英语 | `en` | `en` | :(far fa-check-square fa-fw): | :(far fa-check-square fa-fw): | +| 简体中文 | `zh-cn` | `zh-CN` | :(far fa-check-square fa-fw): | :(far fa-check-square fa-fw): | +| 法语 | `fr` | `fr` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| 波兰语 | `pl` | `pl` | :(far fa-square fa-fw): | :(far fa-square fa-fw): | +| 巴西葡萄牙语 | `pt-br` | `pt-BR` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| 意大利语 | `it` | `it` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| 西班牙语 | `es` | `es` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| 德语 | `de` | `de` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| 塞尔维亚语 | `pl` | `pl` | :(far fa-square fa-fw): | :(far fa-square fa-fw): | +| 俄语 | `ru` | `ru` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| 罗马尼亚语 | `ro` | `ro` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| 越南语 | `vi` | `vi` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | + +### 4.2 基本配置 + +学习了 [Hugo 如何处理多语言网站](https://gohugo.io/content-management/multilingual) 之后, 请在 [站点配置](#site-configuration) 中定义你的网站语言. + +例如, 一个支持英语, 中文和法语的网站配置: + +```toml +# [en, zh-cn, fr, pl, ...] 设置默认的语言 +defaultContentLanguage = "zh-cn" + +[languages] + [languages.en] + weight = 1 + title = "My New Hugo Site" + languageCode = "en" + languageName = "English" + [[languages.en.menu.main]] + identifier = "posts" + pre = "" + post = "" + name = "Posts" + url = "/posts/" + title = "" + weight = 1 + [[languages.en.menu.main]] + identifier = "tags" + pre = "" + post = "" + name = "Tags" + url = "/tags/" + title = "" + weight = 2 + [[languages.en.menu.main]] + identifier = "categories" + pre = "" + post = "" + name = "Categories" + url = "/categories/" + title = "" + weight = 3 + + [languages.zh-cn] + weight = 2 + title = "我的全新 Hugo 网站" + # 网站语言, 仅在这里 CN 大写 + languageCode = "zh-CN" + languageName = "简体中文" + # 是否包括中日韩文字 + hasCJKLanguage = true + [[languages.zh-cn.menu.main]] + identifier = "posts" + pre = "" + post = "" + name = "文章" + url = "/posts/" + title = "" + weight = 1 + [[languages.zh-cn.menu.main]] + identifier = "tags" + pre = "" + post = "" + name = "标签" + url = "/tags/" + title = "" + weight = 2 + [[languages.zh-cn.menu.main]] + identifier = "categories" + pre = "" + post = "" + name = "分类" + url = "/categories/" + title = "" + weight = 3 + + [languages.fr] + weight = 3 + title = "Mon nouveau site Hugo" + languageCode = "fr" + languageName = "Français" + [[languages.fr.menu.main]] + identifier = "posts" + pre = "" + post = "" + name = "Postes" + url = "/posts/" + title = "" + weight = 1 + [[languages.fr.menu.main]] + identifier = "tags" + pre = "" + post = "" + name = "Balises" + url = "/tags/" + title = "" + weight = 2 + [[languages.fr.menu.main]] + identifier = "categories" + pre = "" + post = "" + name = "Catégories" + url = "/categories/" + title = "" + weight = 3 +``` + +然后, 对于每个新页面, 将语言代码附加到文件名中. + +单个文件 `my-page.md` 需要分为三个文件: + +- 英语: `my-page.en.md` +- 中文: `my-page.zh-cn.md` +- 法语: `my-page.fr.md` + +{{< admonition >}} +请注意, 菜单中仅显示翻译的页面. 它不会替换为默认语言内容. +{{< /admonition >}} + +{{< admonition tip >}} +也可以使用 [文章前置参数](https://gohugo.io/content-management/multilingual#translate-your-content) 来翻译网址. +{{< /admonition >}} + +### 4.3 修改默认的翻译字符串 + +翻译字符串用于在主题中使用的常见默认值. +目前提供[一些语言](#language-compatibility)的翻译, 但你可能自定义其他语言或覆盖默认值. + +要覆盖默认值, 请在你项目的 i18n 目录 `i18n/<languageCode>.toml` 中创建一个新文件，并从 `themes/CodeIT/i18n/en.toml` 中获得提示. + +另外, 由于你的翻译可能会帮助到其他人, 请花点时间通过 [:(fas fa-code-branch fa-fw): 创建一个 PR](https://github.com/sunt-programator/CodeIT/pulls) 来贡献主题翻译, 谢谢! + +## 5 搜索 + +基于 [Lunr.js](https://lunrjs.com/) 或 [algolia](https://www.algolia.com/), **CodeIT** 主题支持搜索功能. + +### 5.1 输出配置 + +为了生成搜索功能所需要的 `index.json`, 请在你的 [网站配置](#site-configuration) 中添加 `JSON` 输出文件类型到 `outputs` 部分的 `home` 字段中. + +```toml +[outputs] + home = ["HTML", "RSS", "JSON"] +``` + +### 5.2 搜索配置 + +基于 Hugo 生成的 `index.json` 文件, 你可以激活搜索功能. + +这是你的 [网站配置](#site-configuration) 中的搜索部分: + +```toml +[params.search] + enable = true + # 搜索引擎的类型 ("lunr", "algolia") + type = "lunr" + # 文章内容最长索引长度 + contentLength = 4000 + # 搜索框的占位提示语 + placeholder = "" + # 最大结果数目 + maxResultLength = 10 + # 结果内容片段长度 + snippetLength = 50 + # 搜索结果中高亮部分的 HTML 标签 + highlightTag = "em" + # 是否在搜索索引中使用基于 baseURL 的绝对路径 + absoluteURL = false + [params.search.algolia] + index = "" + appID = "" + searchKey = "" +``` + +{{< admonition note "怎样选择搜索引擎?" >}} +以下是两种搜索引擎的对比: + +- `lunr`: 简单, 无需同步 `index.json`, 没有 `contentLength` 的限制, 但占用带宽大且性能低 (特别是中文需要一个较大的分词依赖库) +- `algolia`: 高性能并且占用带宽低, 但需要同步 `index.json` 且有 `contentLength` 的限制 + +文章内容被 `h2` 和 `h3` HTML 标签切分来提高查询效果并且基本实现全文搜索. +`contentLength` 用来限制 `h2` 和 `h3` HTML 标签开头的内容部分的最大长度. +{{< /admonition >}} + +{{< admonition tip "关于 algolia 的使用技巧" >}} +你需要上传 `index.json` 到 algolia 来激活搜索功能. 你可以使用浏览器来上传 `index.json` 文件但是一个自动化的脚本可能效果更好. +[Algolia Atomic](https://github.com/chrisdmacrae/atomic-algolia) 是一个不错的选择. +为了兼容 Hugo 的多语言模式, 你需要上传不同语言的 `index.json` 文件到对应的 algolia index, 例如 `zh-cn/index.json` 或 `fr/index.json`... +{{< /admonition >}} |