Hugo 主题
深色主题编辑器 | Hugo
深色主题编辑器是一个用于 Hugo 的博客主题。
演示 - https://jingwangtw.github.io/dark-theme-editor/
⚠️ 该主题至少需要 Hugo v0.112.x。
主要特性
- 一个类似编辑器的 Hugo 主题
- 多语言支持
- Mermaid 支持
- LaTeX 数学支持
- Google/Bing SEO 支持
- 更好的代码块
- 可拖动的侧边栏
- 完全响应式
安装方法
手动下载
你可以简单地从 GitHub 仓库下载主题,并将其粘贴到你的 Hugo 站点根目录下的 themes/dark-theme-editor
目录中。
本地安装主题
# Under the root directory of your Hugo site
git clone https://github.com/JingWangTW/dark-theme-editor.git themes/dark-theme-editor
这会将主题仓库直接克隆到 themes/dark-theme-editor
目录中。
将主题作为子模块安装
# Under the root directory of your Hugo site
git submodule add -f https://github.com/JingWangTW/dark-theme-editor.git themes/dark-theme-editor
这会将主题仓库作为子模块安装在 themes/dark-theme-editor
目录中。
用法
常规配置
当使用
dark-theme-editor
作为你的 Hugo 站点的主题时,请记住在你的config.toml
/hugo.toml
文件中设置主题字段。此外,该主题还提供了许多自定义字段,你可以根据需要进行配置。请参考主题中的
hugo.toml
文件,查找所有可用的选项。你可以通过将它们添加到你自己的配置文件中或直接修改主题目录中的文件来覆盖这些值。点击以切换完整的配置列表。
# Theme parameters [params] # Parameters applied in HTML <head> [params.site] # Website ICON faviconUrl = "" # Do you have any CSS in local? List them in an array. # They should be placed inside "/assets" dir. # Please list your files relative to the /assets directory. # Glob pattern is acceptable # If only a few pages need the extra style files, list them in the page metadata. localCss = [] # Do you need to add any external CSS? List their URL in an array. # If only a few pages need the extra style files, list them in the page metadata. # These URLs will be inserted into <link> tags directly without any check. externalCss = [] # Like the one above, but this will download a local copy and combine it with # other CSS files into a single file while in production mode. externalCssDownload = [] # Do you have any script in local? List them in an array. # They should be placed inside "/assets" dir. # Please list your files relative to the /assets directory. # Glob pattern is acceptable # If only a few pages need the extra script files, list them in the page metadata. localJs = [] # Do you have any external Script need to add on? List their URL in an array. # If only a few pages need the extra script files, list them in the page metadata. # These URLs will be inserted into <script> tags directly without any check. externalJs = [] # Like the one above, but this will download a local copy and combine it with # other JS files into a single file while in production mode. externalJsDownload = [] # The code you could get from Google Search Console. # Please patse the value of content xxx in the following items # <meta name="google-site-verification" content="xxxxxxxxxxxxxxxxxxxxxxxxxx" /> googleVerification = "" # The code you could get from Microsoft Bing Webmater # Please patse the value of content xxx in the following items # <meta name="msvalidate.01" content="xxxxxxxxxxxxxxxxxxxx" /> bingVerifivation = "" # Customized info shown in header of the page # Customized info shown in header of the page [params.header] # Website title for header banner. title = "My New Hugo Site" # Subtitle for this site, used in homepage only subtitle = "A Site Built by Hugo" # Config about your's site logo, remove this item to hide the logo [params.header.logo] # Where is your site's URL imgUrl = "" # If the logo is clickable, where should it be linked? # In default, it will linked to the homepage of the site. logoLink = "" # Customized info shown in footer of the page [params.footer] # CopyRight string shown in the footer. Keep it an empty string or remove this item will hide it from the page. copyrightStr = "All Rights Reserved ®." # Should show the counter in the footer or not # In the home page, it will show the numbers of all pages # In the sections pages, it will show the numbers of pages within the section # In the taxonomy pages, it will show the numbers of pages belong to the taxonomy. # In the regular content pages, it will show the word count. counter = true # Should show the language of the page or not language = true # Should show the hugo version or not hugoVersion = true # Should show the theme info or not theme = true # Should show the edited time of the page or not modifiedTime = true # The format of the `modifiedTime`. # Refer to page https://gohugo.com.cn/functions/format/ for more detail. # Below is the default format, please do not remove it, unless you set `false` in `modifiedTime` field. dateFormat = "Jan 02 2006 15:04:05" # Should show the current git HEAD hash or not # To make this show up correctly, please follow the prerequisites in page # https://gohugo.com.cn/variables/git/ gitHash = true # Social link in the footer, listed items are supported, delete unwanted items to hide it. [params.footer.socialLink] github = "" facebook = "" twitter = "" email = "" linkedin = "" instagram = "" telegram = "" medium = "" vimeo = "" youtube = "" # Metadata of the site, value will be used in HTML <header> # These value would be used when they didn't appear in the frontmatter of a single page. # In other words, these value will be overwritten by the frontmatter in the single page. [params.globalFrontmatter] # The author of this site. This will be shown in # 1. the footer of all page # 2. the author filed in the single page. (this could be overwritten by the frontmatter of the single page.) # Keep it an empty string or remove this item will hide it from the page author = "Jing Wang" # Website description for RSS and SEO. Theme will generate a <meta> tag for this item description = "This is my new hugo site" # Website keywords. Theme will generate a <meta> tag for this item. keywords = "hugo,site,new" # Parameters applied in the homepage only [params.homePage] # Long Descripition shown in home page "Start Block". Is is recommended to have the paragraph shorter than 100 words. siteLongDescription = "Hugo is a fast and easy-to-use static website generator written in Go. It renders a complete HTML website from content and templates in a directory, utilizing Markdown files for metadata. It's optimized for speed and suitable for various website types." # If you don't like the title of "siteLongDescription" be "Start" (default), # you may change the value of this item to "Description" or something you like. siteLongDescriptionTitle = "Start" # Param to decide whether to show the most recent blog posts or not. (Default: true) showRecentPostsBlock = true # Param to decide how many recent posts to show in the home page. (Default: 5) numOfRecentPosts = 5 # Parameter to decide whether to show the URL behind the title. # It will be more like an editor if it is shown. However, in general, it can be messy if it is displayed. # (Default: true) recentPostShowUrl = true # Paramater applied in the single page # These values could be overwritten by the frontmatter in the single page. [params.page] # Should include Table of Content in front of the page or not. includeToc = true # Should show the author of the page or not. # The author name will be shown in the single page if and only if # 1. this items been set as true and # 2. "aurthor" filed been provided in the # A. single page frontmatter or # B. "author" filed in above "globalFrontmatter" block showAuthor = true # Should show the date of the page or not showDate = true # The format of the date. # Refer to page https://gohugo.com.cn/functions/format/ for more detail. # Below is the default format, please do not remove it, unless you set `false` in `showDate` field. dateFormat = "2006.01.02" # Should show the estimate reading time in front of the page or not. showTimeToRead = true # Should show the breadcrumb in front of the page or not. showBreadcrumb = true # Should show the "copy" button in the codeblock or not. codeBlockCopible = true # Should include LaTeX support on a single page or not? # This parameter will be overwritten by the page front matter (if it has been set). # Since enabling this configuration loads some external JavaScript, # it will slow down the page loading speed. # It's recommended to keep it turned off by default and only enable this configuration when required. useMath = false # Filed tp describe how should we pass the "trust" params to the `KaTex` module. # Thos params would affect if we could trust the HTML related code in LaTex blocks. # https://katex.org/docs/options.html trustedmath = false [params.preference] # Use "true" to show the real fila name in both breadcrumb and the sidebar # Use "false" to show the tile in the file in both breadcrumb and the sidebar showFileName = false
多语言配置
如果你的站点处于多语言模式,则站点页脚处会有一个语言选择图标。此外,每个翻译页面上都会有一个导航器。
请将需要翻译的配置字段移动到你的
hugo.toml
中相应的语言配置块下。有一个你可以参考的示例hugo.multilang.toml
文件。记住在需要时将其重命名为hugo.toml
。点击以切换示例
hugo.multilang.toml
文件# Multilingual Setting [languages] [languages.en] # hugo multilingual setting languageCode = 'en-US' languageDirection = 'ltr' languageName = 'English' weight = 1 # Configs that were originally in the "params" section but need to be translated. [languages.en.params] [languages.en.params.header] # Website title for header banner. title = "My New Hugo Site" # Subtitle for this site, used in homepage only subtitle = 'A Site Built by Hugo' [languages.en.params.footer] # CopyRight string shown in the footer. Keep it an empty string or remove this item will hide it from the page. copyrightStr = "All Rights Reserved ®." [languages.en.params.globalFrontmatter] # The author of this site. This will be shown in # 1. the footer of all page # 2. the author filed in the single page. (this could be overwritten by the frontmatter of the single page.) # Keep it an empty string or remove this item will hide it from the page author = "Jing Wang" # Website description for RSS and SEO. Theme will generate a <meta> tag for this item description = "This is my new hugo site" # Website keywords. Theme will generate a <meta> tag for this item. keywords = "hugo,site,new" [languages.en.params.homePage] # Long Descripition shown in home page "Start Block". Is is recommended to have the paragraph shorter than 100 words. siteLongDescription = "Hugo is a fast and easy-to-use static website generator written in Go. It renders a complete HTML website from content and templates in a directory, utilizing Markdown files for metadata. It's optimized for speed and suitable for various website types." # If you don't like the title of "siteLongDescription" be "Start" (default), # you may change the value of this item to "Description" or something you like. siteLongDescriptionTitle = "Start" # 設定為繁體中文 [languages.zh] # Hugo 多語言設定 languageCode = 'zh-Hant-TW' languageDirection = 'ltr' languageName = '繁體中文' weight = 2 # 原本位於 "params" 區段但需要翻譯的設定 [languages.zh.params] [languages.zh.params.header] # 頁首橫幅的網站標題。 title = "我的新 Hugo 網站" # 本站的副標題,僅用於首頁 subtitle = '由 Hugo 建立的網站' [languages.zh.params.footer] # 在頁尾顯示的版權字串。將其保留為空字串或刪除此項目可將其從頁面中隱藏。 copyrightStr = "版權所有 ®." [languages.zh.params.globalFrontmatter] # 本站的作者。將顯示於 # 1. 所有頁面的頁尾 # 2. 單頁的作者欄位中(可被單頁的前置資料覆寫) # 將其保留為空字串或刪除此項目可將其從頁面中隱藏 author = "王靖" # 用於 RSS 和 SEO 的網站描述。主題將為此項目生成 <meta> 標籤 description = "這是我的新 Hugo 網站" # 網站關鍵字。主題將為此項目生成 <meta> 標籤 keywords = "hugo,網站,新" [languages.zh.params.homePage] # 在首頁「開始區塊」中顯示的詳細描述。建議段落長度不超過 100 個字。 siteLongDescription = "Hugo 是一個快速且易於使用的靜態網站產生器,用 Go 語言編寫。它可以從目錄中的內容和模板呈現完整的 HTML 網站,利用 Markdown 檔案進行元數據。它針對速度進行了優化,適用於各種類型的網站。" # 如果您不喜歡 "siteLongDescription" 的標題是「開始」(默認值), # 您可以將此項目的值更改為「描述」或您喜歡的其他內容。 siteLongDescriptionTitle = "開始" # Spracheinstellung für Deutsch [languages.de] languageCode = 'de-DE' languageDirection = 'ltr' languageName = 'Deutsch' title = 'Projekt Dokumentation' weight = 3 # Konfigurationen, die ursprünglich im Abschnitt "params" waren, aber übersetzt werden müssen. [languages.de.params] [languages.de.params.header] # Website-Titel für den Kopfzeilenbanner. title = "Meine neue Hugo-Website" # Untertitel für diese Seite, nur auf der Startseite verwendet subtitle = 'Eine Website erstellt von Hugo' [languages.de.params.footer] # Urheberrechtszeichenfolge im Footer angezeigt. Lassen Sie es leer oder entfernen Sie diesen Eintrag, um sie von der Seite auszublenden. copyrightStr = "Alle Rechte vorbehalten ®." [languages.de.params.globalFrontmatter] # Der Autor dieser Website. Dies wird angezeigt in # 1. im Footer auf allen Seiten # 2. dem Autorenfeld auf der Einzelseite. (dies kann durch das Frontmatter der Einzelseite überschrieben werden.) # Lassen Sie es leer oder entfernen Sie diesen Eintrag, um ihn von der Seite auszublenden. author = "Jing Wang" # Website-Beschreibung für RSS und SEO. Das Theme generiert ein <meta>-Tag für diesen Eintrag description = "Das ist meine neue Hugo-Website" # Website-Schlüsselwörter. Das Theme generiert ein <meta>-Tag für diesen Eintrag. keywords = "hugo,website,neu" [languages.de.params.homePage] # Lange Beschreibung im "Start Block" auf der Startseite angezeigt. Es wird empfohlen, den Absatz kürzer als 100 Wörter zu halten. siteLongDescription = "Hugo ist ein schneller und benutzerfreundlicher statischer Website-Generator, der in Go geschrieben ist. Er rendert eine vollständige HTML-Website aus Inhalten und Vorlagen in einem Verzeichnis und verwendet Markdown-Dateien für Metadaten. Er ist optimiert für Geschwindigkeit und für verschiedene Arten von Websites geeignet." # Wenn Ihnen der Titel von "siteLongDescription" nicht gefällt, der standardmäßig "Start" ist, # können Sie den Wert dieses Elements in "Beschreibung" oder etwas ähnliches ändern, das Ihnen gefällt. siteLongDescriptionTitle = "Start" # Theme parameters [params] # Parameters applied in HTML <head> [params.site] # Website ICON faviconUrl = "" # Do you have any CSS in local? List them in an array. # They should be placed inside "/assets" dir. # And don't named the file as "index.css" and "style.css". # These two files are used by the theme. localCss = [] # Do you need to add any external CSS? List them in an array. externalCss = [] # Do you have any script in local? List them in an array. # They should be placed inside "/assets" dir. # And don't named the file as "index.js" # Theis file is used by the theme. localJs = [] # Do you have any external Script need to add on? List them in an array. externalJs = [] # The code you could get from Google Search Console. # Please patse the value of content xxx in the following items # <meta name="google-site-verification" content="xxxxxxxxxxxxxxxxxxxxxxxxxx" /> googleVerification = "" # The code you could get from Microsoft Bing Webmater # Please patse the value of content xxx in the following items # <meta name="msvalidate.01" content="xxxxxxxxxxxxxxxxxxxx" /> bingVerifivation = "" # Customized info shown in header of the page [params.header] # Config about your's site logo, remove this item to hide the logo [params.header.logo] # Where is your site's URL imgUrl = "" # If the logo is clickable, where should it be linked? # In default, it will linked to the homepage of the site. logoLink = "" # Customized info shown in footer of the page [params.footer] # Should show the counter in the footer or not # In the home page, it will show the numbers of all pages # In the sections pages, it will show the numbers of pages within the section # In the taxonomy pages, it will show the numbers of pages belong to the taxonomy. # In the regular content pages, it will show the word count. counter = true # Should show the language of the page or not language = true # Should show the hugo version or not hugoVersion = true # Should show the theme info or not theme = true # Should show the edited time of the page or not modifiedTime = true # The format of the `modifiedTime`. # Refer to page https://gohugo.com.cn/functions/format/ for more detail. # Below is the default format, please do not remove it, unless you set `false` in `modifiedTime` field. dateFormat = "Jan 02 2006 15:04:05" # Should show the current git HEAD hash or not # To make this show up correctly, please follow the prerequisites in page # https://gohugo.com.cn/variables/git/ gitHash = true # Social link in the footer, listed items are supported, delete unwanted items to hide it. [params.footer.socialLink] github = "" facebook = "" twitter = "" email = "" linkedin = "" instagram = "" telegram = "" medium = "" vimeo = "" youtube = "" # Parameters applied in the homepage only [params.homePage] # Param to decide whether to show the most recent blog posts or not. (Default: true) showRecentPostsBlock = true # Param to decide how many recent posts to show in the home page. (Default: 5) numOfRecentPosts = 5 # Parameter to decide whether to show the URL behind the title. # It will be more like an editor if it is shown. However, in general, it can be messy if it is displayed. # (Default: true) recentPostShowUrl = true # Paramater applied in the single page # These values could be overwritten by the frontmatter in the single page. [params.page] # Should include Table of Content in front of the page or not. includeToc = true # Should show the author of the page or not. # The author name will be shown in the single page if and only if # 1. this items been set as true and # 2. "aurthor" filed been provided in the # A. single page frontmatter or # B. "author" filed in above "globalFrontmatter" block showAuthor = true # Should show the date of the page or not showDate = true # The format of the date. # Refer to page https://gohugo.com.cn/functions/format/ for more detail. # Below is the default format, please do not remove it, unless you set `false` in `showDate` field. dateFormat = "2006.01.02" # Should show the estimate reading time in front of the page or not. showTimeToRead = true # Should show the breadcrumb in front of the page or not. showBreadcrumb = true # Should show the "copy" button in the codeblock or not. codeBlockCopible = true # Should include LaTeX support on a single page or not? # This parameter will be overwritten by the page front matter (if it has been set). # Since enabling this configuration loads some external JavaScript, # it will slow down the page loading speed. # It's recommended to keep it turned off by default and only enable this configuration when required. useMath = false # Filed tp describe how should we pass the "trust" params to the `KaTex` module. # Thos params would affect if we could trust the HTML related code in LaTex blocks. # https://katex.org/docs/options.html trustedmath = false [params.preference] # Use "true" to show the real fila name in both breadcrumb and the sidebar # Use "false" to show the tile in the file in both breadcrumb and the sidebar showFileName = false
另外,请根据你使用的语言添加相应的 i18n 翻译表,以便主题可以正确翻译成你使用的语言。我已经在
i18n
文件夹下放置了一个英文示例文件,其中包含主题所需的所有单词。你应该复制它并将其翻译成你需要的语言。
作者分类法
由于 Hugo 默认不会将主题配置中的分类法配置合并到站点配置中,因此需要在你的站点配置中设置作者分类法页面。
- 你可以简单地将主题配置合并到站点配置中。
[taxonomies] _merge = "deep"
- 否则,你可以直接定义你的分类法。
[taxonomies] autor = "author" tag = "tags" category = "categories"
此外,你需要根据你的偏好设置
[params.page.showAuthor]
。params
配置默认会从主题配置合并到站点配置中。
LaTex 数学支持
此主题支持 LaTeX 数学解释,并使用 KaTeX 作为渲染引擎。
要启用此功能,请在单页面的 frontmatter 或站点配置中添加
useMath = true
。默认情况下,此功能是关闭的。单页面配置将覆盖站点配置中的配置。由于启用此功能会在每个页面中添加相关依赖项,这将减慢页面加载的性能,因此建议在需要它的页面中启用此功能,而不是在站点配置中全局启用它。
默认情况下,我们支持以下分隔符
$$ \LaTeX $$
:这将在单行中渲染公式。$ \LaTeX $
:这将内联渲染公式。\\( \LaTeX \\)
:这将内联渲染公式。\\[ \LaTeX \\]
:这将在单行中渲染公式。
此外,由于 Hugo 会将
\
解释为转义字符,请记住使用\\\\
进行换行。仅供参考,这是主题传递给 KaTeX 的配置。
renderMathInElement(document.body, { // customised options // auto-render specific keys, e.g.: delimiters: [ { left: "$$", right: "$$", display: true }, { left: "$", right: "$", display: false }, { left: "\\(", right: "\\)", display: false }, { left: "\\[", right: "\\]", display: true }, ], // rendering keys, e.g.: throwOnError: false, });
运行 & 构建
开发
hugo server
然后,你应该能够在 localhost:1313
上看到你的站点。从现在开始,所有在本地所做的更改都将反映在站点上,而无需每次都刷新浏览器。此外,在此开发模式下,所有文件都不会被缩小或合并,从而更容易调试任何问题。
发布
hugo
这将以发布模式构建你的站点,其中所有 .html
、.css
和 .js
文件将在可能的情况下被缩小和合并。
功能计划
- 标签视图支持
- 在本地存储中存储自定义注释。
- 可访问性支持
- 服务器端 LaTex 数学渲染。
- 提供搜索栏。
鸣谢
这个主题最初的灵感来自于主题 edidor
。
许可
此主题基于 Apache License 2.0 发布。