Initial commit for Hugo site.
This commit is contained in:
Charish Patel
Binary file not shown.
|
After Width: | Height: | Size: 53 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 25 KiB |
@@ -0,0 +1,27 @@
|
||||
function switchHomeLayout() {
|
||||
const pageDiv = document.getElementById("page");
|
||||
const profileDiv = document.getElementById("profile");
|
||||
const layoutCode = document.querySelectorAll("code[id=layout]");
|
||||
if (pageDiv.style.display === "none") {
|
||||
pageDiv.style.display = "block";
|
||||
profileDiv.style.display = "none";
|
||||
layoutCode.forEach(function (el) {
|
||||
el.innerText = "page";
|
||||
});
|
||||
} else {
|
||||
pageDiv.style.display = "none";
|
||||
profileDiv.style.display = "block";
|
||||
layoutCode.forEach(function (el) {
|
||||
el.innerText = "profile";
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
window.addEventListener("DOMContentLoaded", (event) => {
|
||||
document.querySelectorAll("#switch-layout-button").forEach((button) =>
|
||||
button.addEventListener("click", function (e) {
|
||||
e.preventDefault();
|
||||
switchHomeLayout();
|
||||
})
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,13 @@
|
||||
# -- Site Configuration --
|
||||
# Refer to the theme docs for more details about each of these parameters.
|
||||
# https://jpanther.github.io/congo/docs/getting-started/
|
||||
|
||||
theme = "congo"
|
||||
defaultContentLanguage = "en"
|
||||
|
||||
enableRobotsTXT = true
|
||||
paginate = 15
|
||||
summaryLength = 0
|
||||
|
||||
[outputs]
|
||||
home = ["HTML", "RSS", "JSON"]
|
||||
@@ -0,0 +1,25 @@
|
||||
languageCode = "de-DE"
|
||||
languageName = "Deutsch (Deutschland)"
|
||||
languageDirection = "ltr"
|
||||
weight = 4
|
||||
|
||||
title = "Congo"
|
||||
copyright = "© 2023 Congo contributors"
|
||||
|
||||
[params]
|
||||
dateFormat = "2. January 2006"
|
||||
|
||||
mainSections = ["samples"]
|
||||
description = "Ein leistungsstarkes, leichtgewichtiges Theme für Hugo, das mit Tailwind CSS erstellt wurde."
|
||||
|
||||
[params.author]
|
||||
name = "Congo"
|
||||
image = "img/author.jpg"
|
||||
headline = "Nicht dein Durschnitts-Theme!"
|
||||
bio = "Dies ist ein Beispiel für eine Autorenbiografie, und obwohl hier ein Stockfoto eines Hundes zu sehen ist, wurde dieser Artikel tatsächlich von einem Menschen verfasst. :dog:"
|
||||
links = [
|
||||
{ x-twitter = "https://twitter.com/" },
|
||||
{ facebook = "https://facebook.com/" },
|
||||
{ linkedin = "https://linkedin.com/" },
|
||||
{ youtube = "https://youtube.com/" },
|
||||
]
|
||||
@@ -0,0 +1,25 @@
|
||||
languageCode = "en-AU"
|
||||
languageName = "English (Australia)"
|
||||
languageDirection = "ltr"
|
||||
weight = 1
|
||||
|
||||
title = "Congo"
|
||||
copyright = "© 2023 Congo contributors"
|
||||
|
||||
[params]
|
||||
dateFormat = "2 January 2006"
|
||||
|
||||
mainSections = ["samples"]
|
||||
description = "A powerful, lightweight theme for Hugo built with Tailwind CSS."
|
||||
|
||||
[params.author]
|
||||
name = "Congo"
|
||||
image = "img/author.jpg"
|
||||
headline = "Not your ordinary theme!"
|
||||
bio = "This is an example author bio, and although there's a stock photo of a dog here, this article was actually created by a human. :dog:"
|
||||
links = [
|
||||
{ x-twitter = "https://twitter.com/" },
|
||||
{ facebook = "https://facebook.com/" },
|
||||
{ linkedin = "https://linkedin.com/" },
|
||||
{ youtube = "https://youtube.com/" },
|
||||
]
|
||||
@@ -0,0 +1,25 @@
|
||||
languageCode = "es-MX"
|
||||
languageName = "Español (México)"
|
||||
languageDirection = "ltr"
|
||||
weight = 2
|
||||
|
||||
title = "Congo"
|
||||
copyright = "© 2023 Congo contributors"
|
||||
|
||||
[params]
|
||||
dateFormat = "2 January 2006"
|
||||
|
||||
mainSections = ["samples"]
|
||||
description = "Un tema poderoso y liviano para Hugo creado con Tailwind CSS."
|
||||
|
||||
[params.author]
|
||||
name = "Congo"
|
||||
image = "img/author.jpg"
|
||||
headline = "¡No es tu tema ordinario!"
|
||||
bio = "Esta es una biografía de autor de ejemplo, y aunque aquí hay una foto de un perro, este artículo en realidad fue creado por un ser humano. :dog:"
|
||||
links = [
|
||||
{ x-twitter = "https://twitter.com/" },
|
||||
{ facebook = "https://facebook.com/" },
|
||||
{ linkedin = "https://linkedin.com/" },
|
||||
{ youtube = "https://youtube.com/" },
|
||||
]
|
||||
@@ -0,0 +1,25 @@
|
||||
languageCode = "ja"
|
||||
languageName = "日本語"
|
||||
languageDirection = "ltr"
|
||||
weight = 2
|
||||
|
||||
title = "Congo"
|
||||
copyright = "© 2023 Congo contributors"
|
||||
|
||||
[params]
|
||||
dateFormat = "2006年1月2日"
|
||||
|
||||
mainSections = ["samples"]
|
||||
description = "Tailwind CSSをベースに開発された強力で軽量なHugo向けテーマ"
|
||||
|
||||
[params.author]
|
||||
name = "Congo"
|
||||
image = "img/author.jpg"
|
||||
headline = "ただならぬテーマ!"
|
||||
bio = "これは著者の経歴の例で、ここには犬の画像があるが、実際には人間が作成したものである。 :dog:"
|
||||
links = [
|
||||
{ x-twitter = "https://twitter.com/" },
|
||||
{ facebook = "https://facebook.com/" },
|
||||
{ linkedin = "https://linkedin.com/" },
|
||||
{ youtube = "https://youtube.com/" },
|
||||
]
|
||||
@@ -0,0 +1,25 @@
|
||||
languageCode = "zh-CN"
|
||||
languageName = "简体中文"
|
||||
languageDirection = "ltr"
|
||||
weight = 2
|
||||
|
||||
title = "Congo"
|
||||
copyright = "© 2023 Congo contributors"
|
||||
|
||||
[params]
|
||||
dateFormat = "2006年1月2日"
|
||||
|
||||
mainSections = ["samples"]
|
||||
description = "一款基于Tailwindcss的强大且轻量的Hugo主题"
|
||||
|
||||
[params.author]
|
||||
name = "Congo"
|
||||
image = "img/author.jpg"
|
||||
headline = "非凡的主题！"
|
||||
bio = "这是一个作者简介示例，虽然这里有一张狗的库存照片，但实际上这篇文章是由人创建的。 :dog:"
|
||||
links = [
|
||||
{ x-twitter = "https://twitter.com/" },
|
||||
{ facebook = "https://facebook.com/" },
|
||||
{ linkedin = "https://linkedin.com/" },
|
||||
{ youtube = "https://youtube.com/" },
|
||||
]
|
||||
@@ -0,0 +1,13 @@
|
||||
# -- Markup --
|
||||
# These settings are required for the theme to function.
|
||||
|
||||
[goldmark]
|
||||
[goldmark.renderer]
|
||||
unsafe = true
|
||||
|
||||
[highlight]
|
||||
noClasses = false
|
||||
|
||||
[tableOfContents]
|
||||
startLevel = 2
|
||||
endLevel = 3
|
||||
@@ -0,0 +1,56 @@
|
||||
# -- Main Menu --
|
||||
# The main menu is displayed in the header at the top of the page.
|
||||
# Acceptable parameters are name, pageRef, page, url, title, weight.
|
||||
#
|
||||
# The simplest menu configuration is to provide:
|
||||
# name = The name to be displayed for this menu link
|
||||
# pageRef = The identifier of the page or section to link to
|
||||
#
|
||||
# By default the menu is ordered alphabetically. This can be
|
||||
# overridden by providing a weight value. The menu will then be
|
||||
# ordered by weight from lowest to highest.
|
||||
|
||||
[[main]]
|
||||
name = "Dokumentation"
|
||||
pageRef = "docs"
|
||||
weight = 10
|
||||
|
||||
[[main]]
|
||||
name = "Beispiele"
|
||||
pageRef = "samples"
|
||||
weight = 20
|
||||
|
||||
[[main]]
|
||||
name = "Genutzt von"
|
||||
pageRef = "users"
|
||||
weight = 30
|
||||
|
||||
[[main]]
|
||||
name = "GitHub"
|
||||
url = "https://github.com/jpanther/congo"
|
||||
weight = 40
|
||||
[main.params]
|
||||
icon = "github"
|
||||
showName = false
|
||||
target = "_blank"
|
||||
|
||||
[[main]]
|
||||
identifier = "search"
|
||||
weight = 99
|
||||
[main.params]
|
||||
action = "search"
|
||||
|
||||
[[main]]
|
||||
identifier = "locale"
|
||||
weight = 100
|
||||
[main.params]
|
||||
action = "locale"
|
||||
|
||||
# -- Footer Menu --
|
||||
# The footer menu is displayed at the bottom of the page, just before
|
||||
# the copyright notice. Configure as per the main menu above.
|
||||
|
||||
# [[footer]]
|
||||
# name = "Tags"
|
||||
# pageRef = "tags"
|
||||
# weight = 10
|
||||
@@ -0,0 +1,56 @@
|
||||
# -- Main Menu --
|
||||
# The main menu is displayed in the header at the top of the page.
|
||||
# Acceptable parameters are name, pageRef, page, url, title, weight.
|
||||
#
|
||||
# The simplest menu configuration is to provide:
|
||||
# name = The name to be displayed for this menu link
|
||||
# pageRef = The identifier of the page or section to link to
|
||||
#
|
||||
# By default the menu is ordered alphabetically. This can be
|
||||
# overridden by providing a weight value. The menu will then be
|
||||
# ordered by weight from lowest to highest.
|
||||
|
||||
[[main]]
|
||||
name = "Docs"
|
||||
pageRef = "docs"
|
||||
weight = 10
|
||||
|
||||
[[main]]
|
||||
name = "Samples"
|
||||
pageRef = "samples"
|
||||
weight = 20
|
||||
|
||||
[[main]]
|
||||
name = "Users"
|
||||
pageRef = "users"
|
||||
weight = 30
|
||||
|
||||
[[main]]
|
||||
name = "GitHub"
|
||||
url = "https://github.com/jpanther/congo"
|
||||
weight = 40
|
||||
[main.params]
|
||||
icon = "github"
|
||||
showName = false
|
||||
target = "_blank"
|
||||
|
||||
[[main]]
|
||||
identifier = "search"
|
||||
weight = 99
|
||||
[main.params]
|
||||
action = "search"
|
||||
|
||||
[[main]]
|
||||
identifier = "locale"
|
||||
weight = 100
|
||||
[main.params]
|
||||
action = "locale"
|
||||
|
||||
# -- Footer Menu --
|
||||
# The footer menu is displayed at the bottom of the page, just before
|
||||
# the copyright notice. Configure as per the main menu above.
|
||||
|
||||
# [[footer]]
|
||||
# name = "Tags"
|
||||
# pageRef = "tags"
|
||||
# weight = 10
|
||||
@@ -0,0 +1,56 @@
|
||||
# -- Main Menu --
|
||||
# The main menu is displayed in the header at the top of the page.
|
||||
# Acceptable parameters are name, pageRef, page, url, title, weight.
|
||||
#
|
||||
# The simplest menu configuration is to provide:
|
||||
# name = The name to be displayed for this menu link
|
||||
# pageRef = The identifier of the page or section to link to
|
||||
#
|
||||
# By default the menu is ordered alphabetically. This can be
|
||||
# overridden by providing a weight value. The menu will then be
|
||||
# ordered by weight from lowest to highest.
|
||||
|
||||
[[main]]
|
||||
name = "Docs"
|
||||
url = "/docs"
|
||||
weight = 10
|
||||
|
||||
[[main]]
|
||||
name = "Ejemplos"
|
||||
pageRef = "samples"
|
||||
weight = 20
|
||||
|
||||
[[main]]
|
||||
name = "Usuarios"
|
||||
pageRef = "users"
|
||||
weight = 30
|
||||
|
||||
[[main]]
|
||||
name = "GitHub"
|
||||
url = "https://github.com/jpanther/congo"
|
||||
weight = 40
|
||||
[main.params]
|
||||
icon = "github"
|
||||
showName = false
|
||||
target = "_blank"
|
||||
|
||||
[[main]]
|
||||
identifier = "search"
|
||||
weight = 99
|
||||
[main.params]
|
||||
action = "search"
|
||||
|
||||
[[main]]
|
||||
identifier = "locale"
|
||||
weight = 100
|
||||
[main.params]
|
||||
action = "locale"
|
||||
|
||||
# -- Footer Menu --
|
||||
# The footer menu is displayed at the bottom of the page, just before
|
||||
# the copyright notice. Configure as per the main menu above.
|
||||
|
||||
# [[footer]]
|
||||
# name = "Tags"
|
||||
# pageRef = "tags"
|
||||
# weight = 10
|
||||
@@ -0,0 +1,56 @@
|
||||
# -- Main Menu --
|
||||
# The main menu is displayed in the header at the top of the page.
|
||||
# Acceptable parameters are name, pageRef, page, url, title, weight.
|
||||
#
|
||||
# The simplest menu configuration is to provide:
|
||||
# name = The name to be displayed for this menu link
|
||||
# pageRef = The identifier of the page or section to link to
|
||||
#
|
||||
# By default the menu is ordered alphabetically. This can be
|
||||
# overridden by providing a weight value. The menu will then be
|
||||
# ordered by weight from lowest to highest.
|
||||
|
||||
[[main]]
|
||||
name = "ドキュメント"
|
||||
pageRef = "docs"
|
||||
weight = 10
|
||||
|
||||
[[main]]
|
||||
name = "サンプル"
|
||||
pageRef = "samples"
|
||||
weight = 20
|
||||
|
||||
[[main]]
|
||||
name = "利用例"
|
||||
pageRef = "users"
|
||||
weight = 30
|
||||
|
||||
[[main]]
|
||||
name = "GitHub"
|
||||
url = "https://github.com/jpanther/congo"
|
||||
weight = 40
|
||||
[main.params]
|
||||
icon = "github"
|
||||
showName = false
|
||||
target = "_blank"
|
||||
|
||||
[[main]]
|
||||
identifier = "検索"
|
||||
weight = 99
|
||||
[main.params]
|
||||
action = "search"
|
||||
|
||||
[[main]]
|
||||
identifier = "locale"
|
||||
weight = 100
|
||||
[main.params]
|
||||
action = "locale"
|
||||
|
||||
# -- Footer Menu --
|
||||
# The footer menu is displayed at the bottom of the page, just before
|
||||
# the copyright notice. Configure as per the main menu above.
|
||||
|
||||
# [[footer]]
|
||||
# name = "Tags"
|
||||
# pageRef = "tags"
|
||||
# weight = 10
|
||||
@@ -0,0 +1,56 @@
|
||||
# -- Main Menu --
|
||||
# The main menu is displayed in the header at the top of the page.
|
||||
# Acceptable parameters are name, pageRef, page, url, title, weight.
|
||||
#
|
||||
# The simplest menu configuration is to provide:
|
||||
# name = The name to be displayed for this menu link
|
||||
# pageRef = The identifier of the page or section to link to
|
||||
#
|
||||
# By default the menu is ordered alphabetically. This can be
|
||||
# overridden by providing a weight value. The menu will then be
|
||||
# ordered by weight from lowest to highest.
|
||||
|
||||
[[main]]
|
||||
name = "文档"
|
||||
pageRef = "docs"
|
||||
weight = 10
|
||||
|
||||
[[main]]
|
||||
name = "示例"
|
||||
pageRef = "samples"
|
||||
weight = 20
|
||||
|
||||
[[main]]
|
||||
name = "用户"
|
||||
pageRef = "users"
|
||||
weight = 30
|
||||
|
||||
[[main]]
|
||||
name = "GitHub"
|
||||
url = "https://github.com/jpanther/congo"
|
||||
weight = 40
|
||||
[main.params]
|
||||
icon = "github"
|
||||
showName = false
|
||||
target = "_blank"
|
||||
|
||||
[[main]]
|
||||
identifier = "搜索"
|
||||
weight = 99
|
||||
[main.params]
|
||||
action = "search"
|
||||
|
||||
[[main]]
|
||||
identifier = "语言"
|
||||
weight = 100
|
||||
[main.params]
|
||||
action = "locale"
|
||||
|
||||
# -- Footer Menu --
|
||||
# The footer menu is displayed at the bottom of the page, just before
|
||||
# the copyright notice. Configure as per the main menu above.
|
||||
|
||||
# [[footer]]
|
||||
# name = "标签"
|
||||
# pageRef = "tags"
|
||||
# weight = 10
|
||||
@@ -0,0 +1,3 @@
|
||||
[hugoVersion]
|
||||
extended = true
|
||||
min = "0.87.0"
|
||||
@@ -0,0 +1,78 @@
|
||||
# -- Theme Options --
|
||||
# These options control how the theme functions and allow you to
|
||||
# customise the display of your website.
|
||||
#
|
||||
# Refer to the theme docs for more details about each of these parameters.
|
||||
# https://jpanther.github.io/congo/docs/configuration/#theme-parameters
|
||||
|
||||
colorScheme = "congo"
|
||||
defaultAppearance = "light" # valid options: light or dark
|
||||
autoSwitchAppearance = true
|
||||
|
||||
enableSearch = true
|
||||
enableCodeCopy = true
|
||||
enableImageLazyLoading = true
|
||||
enableImageWebp = true
|
||||
enableQuicklink = true
|
||||
|
||||
# robots = ""
|
||||
fingerprintAlgorithm = "sha256"
|
||||
|
||||
[header]
|
||||
layout = "basic" # valid options: basic, hamburger, hybrid, custom
|
||||
# logo = "img/logo.jpg"
|
||||
# logoDark = "img/dark-logo.jpg"
|
||||
showTitle = true
|
||||
|
||||
[footer]
|
||||
showCopyright = true
|
||||
showThemeAttribution = true
|
||||
showAppearanceSwitcher = true
|
||||
showScrollToTop = true
|
||||
|
||||
[homepage]
|
||||
layout = "custom" # valid options: page, profile, custom
|
||||
showRecent = true
|
||||
recentLimit = 5
|
||||
|
||||
[article]
|
||||
showDate = true
|
||||
showDateUpdated = false
|
||||
showAuthor = true
|
||||
showBreadcrumbs = true
|
||||
showDraftLabel = true
|
||||
showEdit = true
|
||||
editURL = "https://github.com/jpanther/congo/tree/dev/exampleSite/content/"
|
||||
editAppendPath = true
|
||||
showHeadingAnchors = true
|
||||
showPagination = true
|
||||
invertPagination = false
|
||||
showReadingTime = true
|
||||
showTableOfContents = true
|
||||
showTaxonomies = false
|
||||
showWordCount = false
|
||||
showComments = false
|
||||
# sharingLinks = ["facebook", "twitter", "mastodon", "pinterest", "reddit", "linkedin", "email", "telegram", "line", "weibo"]
|
||||
|
||||
[list]
|
||||
showBreadcrumbs = true
|
||||
showSummary = false
|
||||
showTableOfContents = true
|
||||
showTaxonomies = false
|
||||
groupByYear = false
|
||||
paginationWidth = 1
|
||||
|
||||
[sitemap]
|
||||
excludedKinds = ["taxonomy", "term"]
|
||||
|
||||
[taxonomy]
|
||||
showTermCount = true
|
||||
|
||||
[fathomAnalytics]
|
||||
# site = "ABC12345"
|
||||
|
||||
[verification]
|
||||
# google = ""
|
||||
# bing = ""
|
||||
# pinterest = ""
|
||||
# yandex = ""
|
||||
@@ -0,0 +1 @@
|
||||
tag = "tags"
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: "Willkommen bei Congo! :tada:"
|
||||
description: "Dies ist eine Demo des Congo-Themes für Hugo."
|
||||
---
|
||||
|
||||
{{< lead >}}
|
||||
Ein mächtiges und gleichzeitig leichtes Theme für Hugo, das mit Tailwind CSS erstellt wurde.
|
||||
{{< /lead >}}
|
||||
|
||||
Dies ist eine Demo-Site, die vollständig mit Congo erstellt wurde. Sie enthält auch eine vollständige [Theme-Dokumentation]({{< ref path="docs" lang="en" >}}). Congo ist flexibel und eignet sich sowohl für statische seitenbasierte Inhalte (wie diese Demo) als auch für einen traditionellen Blog mit einem Feed der letzten Beiträge.
|
||||
|
||||
<div class="flex px-4 py-2 mb-8 text-base rounded-md bg-primary-100 dark:bg-primary-900">
|
||||
<span class="flex items-center pe-3 text-primary-400">
|
||||
{{< icon "triangle-exclamation" >}}
|
||||
</span>
|
||||
<span class="flex items-center justify-between grow dark:text-neutral-300">
|
||||
<span class="prose dark:prose-invert">Dies ist eine Demo des <code id="layout">page</code>-Layouts.</span>
|
||||
<button
|
||||
id="switch-layout-button"
|
||||
class="px-4 !text-neutral !no-underline rounded-md bg-primary-600 hover:!bg-primary-500 dark:bg-primary-800 dark:hover:!bg-primary-700"
|
||||
>
|
||||
Layout ändern ↻
|
||||
</button>
|
||||
</span>
|
||||
</div>
|
||||
|
||||
{{< figure src="festivities.svg" class="m-auto mt-6 max-w-prose" >}}
|
||||
|
||||
Schau dir die [Beispielseiten]({{< ref "samples" >}}) an, um ein Gefühl für die Möglichkeiten von Congo zu bekommen. Wenn dir gefällt, was du siehst, dann schau dir sich das Projekt auf [Github](https://github.com/jpanther/congo) an oder lies die [Installationsanleitung]({{< ref path="docs/installation" lang="en">}}), um loszulegen.
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: "¡Bienvenido a Congo! :tada:"
|
||||
description: "Esta es una demostración del tema Congo para Hugo."
|
||||
---
|
||||
|
||||
{{< lead >}}
|
||||
Un tema poderoso y liviano para Hugo creado con Tailwind CSS.
|
||||
{{< /lead >}}
|
||||
|
||||
Este es un sitio de demostración creado completamente con Congo. También contiene un conjunto completo de artículos con [documentación del tema]({{< ref path="docs" lang="en" >}}). Congo es flexible y es excelente tanto para contenido estático basado en páginas (como es el caso de esta demostración) como para un blog tradicional con un feed de publicaciones recientes.
|
||||
|
||||
<div class="flex px-4 py-2 mb-8 text-base rounded-md bg-primary-100 dark:bg-primary-900">
|
||||
<span class="flex items-center pe-3 text-primary-400">
|
||||
{{< icon "triangle-exclamation" >}}
|
||||
</span>
|
||||
<span class="flex items-center justify-between grow dark:text-neutral-300">
|
||||
<span class="prose dark:prose-invert">Esta es la demostración en formato <code id="layout">page</code></span>
|
||||
<button
|
||||
id="switch-layout-button"
|
||||
class="px-4 !text-neutral !no-underline rounded-md bg-primary-600 hover:!bg-primary-500 dark:bg-primary-800 dark:hover:!bg-primary-700"
|
||||
>
|
||||
Cambiar el diseño ↻
|
||||
</button>
|
||||
</span>
|
||||
</div>
|
||||
|
||||
{{< figure src="festivities.svg" class="m-auto mt-6 max-w-prose" >}}
|
||||
|
||||
Explora las [páginas de ejemplo]({{< ref "samples" >}}) para tener una idea de lo que Congo puede hacer. Si te gusta lo que ves, consulta el proyecto en [Github](https://github.com/jpanther/congo) o lee la [Guía de instalación]({{< ref path="docs/installation" lang="en" >}}) para comenzar.
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: "Congoへようこそ! :tada:"
|
||||
description: "これはHugo向けテーマ、Congoのデモです"
|
||||
---
|
||||
|
||||
{{< lead >}}
|
||||
Tailwind CSSをベースに開発された強力で軽量なHugo向けテーマ。
|
||||
{{< /lead >}}
|
||||
|
||||
これはCongoを使って構築されたデモサイトです。
|
||||
[Congoに関するドキュメント]({{< ref "docs" >}})も含まれています。
|
||||
Congoは柔軟性に富み、静的なコンテンツ配信にも、投稿フィード機能を持つようなBlogにも適しています。
|
||||
|
||||
<div class="flex px-4 py-2 mb-8 text-base rounded-md bg-primary-100 dark:bg-primary-900">
|
||||
<span class="flex items-center pe-3 text-primary-400">
|
||||
{{< icon "triangle-exclamation" >}}
|
||||
</span>
|
||||
<span class="flex items-center justify-between grow dark:text-neutral-300">
|
||||
<span class="prose dark:prose-invert">これは<code id="layout">page</code>レイアウトのデモです。</span>
|
||||
<button
|
||||
id="switch-layout-button"
|
||||
class="px-4 !text-neutral !no-underline rounded-md bg-primary-600 hover:!bg-primary-500 dark:bg-primary-800 dark:hover:!bg-primary-700"
|
||||
>
|
||||
レイアウトを切り替える ↻
|
||||
</button>
|
||||
</span>
|
||||
</div>
|
||||
|
||||
{{< figure src="festivities.svg" class="m-auto mt-6 max-w-prose" >}}
|
||||
|
||||
[例]({{< ref "samples" >}})を見て、Congoの実力を実感してください。気に入ったら[GitHub](https://github.com/jpanther/congo)をチェックするか、[インストール]({{< ref "docs/installation" >}})を読んで実際に使い始めてほしい。
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: "Welcome to Congo! :tada:"
|
||||
description: "This is a demo of the Congo theme for Hugo."
|
||||
---
|
||||
|
||||
{{< lead >}}
|
||||
A powerful, lightweight theme for Hugo built with Tailwind CSS.
|
||||
{{< /lead >}}
|
||||
|
||||
This is a demo site built entirely using Congo. It also contains a complete set of [theme documentation]({{< ref "docs" >}}). Congo is flexible and is great for both static page-based content (like this demo) or a traditional blog with a feed of recent posts.
|
||||
|
||||
<div class="flex px-4 py-2 mb-8 text-base rounded-md bg-primary-100 dark:bg-primary-900">
|
||||
<span class="flex items-center pe-3 text-primary-400">
|
||||
{{< icon "triangle-exclamation" >}}
|
||||
</span>
|
||||
<span class="flex items-center justify-between grow dark:text-neutral-300">
|
||||
<span class="prose dark:prose-invert">This is a demo of the <code id="layout">page</code> layout.</span>
|
||||
<button
|
||||
id="switch-layout-button"
|
||||
class="px-4 !text-neutral !no-underline rounded-md bg-primary-600 hover:!bg-primary-500 dark:bg-primary-800 dark:hover:!bg-primary-700"
|
||||
>
|
||||
Switch layout ↻
|
||||
</button>
|
||||
</span>
|
||||
</div>
|
||||
|
||||
{{< figure src="festivities.svg" class="m-auto mt-6 max-w-prose" >}}
|
||||
|
||||
Explore the [sample pages]({{< ref "samples" >}}) to get a feel for what Congo can do. If you like what you see, check out the project on [Github](https://github.com/jpanther/congo) or read the [Installation guide]({{< ref "docs/installation" >}}) to get started.
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: "欢迎使用Congo! :tada:"
|
||||
description: "这是一个基于Hugo的主题Congo示例。"
|
||||
---
|
||||
|
||||
{{< lead >}}
|
||||
一款基于Tailwindcss的强大且轻量Hugo主题
|
||||
{{< /lead >}}
|
||||
|
||||
这是一个完全使用Congo构建的演示站点。它还包含一个完整的 [主题文档]({{< ref "docs" >}}) 集。Congo是灵活的，非常适合静态基于页面的内容（就像你看到的这个演示）或具有最新文章的传统博客。
|
||||
|
||||
<div class="flex px-4 py-2 mb-8 text-base rounded-md bg-primary-100 dark:bg-primary-900">
|
||||
<span class="flex items-center pe-3 text-primary-400">
|
||||
{{< icon "triangle-exclamation" >}}
|
||||
</span>
|
||||
<span class="flex items-center justify-between grow dark:text-neutral-300">
|
||||
<span class="prose dark:prose-invert">这是一个 <code id="layout">page</code> 布局的示例.</span>
|
||||
<button
|
||||
id="switch-layout-button"
|
||||
class="px-4 !text-neutral !no-underline rounded-md bg-primary-600 hover:!bg-primary-500 dark:bg-primary-800 dark:hover:!bg-primary-700"
|
||||
>
|
||||
切换布局 ↻
|
||||
</button>
|
||||
</span>
|
||||
</div>
|
||||
|
||||
{{< figure src="festivities.svg" class="m-auto mt-6 max-w-prose" >}}
|
||||
|
||||
探索 [示例页面]({{< ref "samples" >}}) 以感受Congo的强大功能。如果你喜欢该主题，请在 [Github](https://github.com/jpanther/congo) 上查看该项目，或阅读 [安装指南]({{< ref "docs/installation" >}}) 开始使用。
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
title: "ドキュメント"
|
||||
description: "Congoの特徴とその使い方について"
|
||||
|
||||
cascade:
|
||||
showDate: false
|
||||
showAuthor: false
|
||||
showSummary: true
|
||||
invertPagination: true
|
||||
---
|
||||
|
||||
{{< lead >}}
|
||||
シンプルでパワフル。Congoの使い方と特徴をご紹介します。
|
||||
{{< /lead >}}
|
||||
|
||||
|
||||
|
||||
このセクションにはCongoの知るべきすべてが含まれています。もしあなたがCongoに触れるのが初めてならば、[インストール]({{< ref "docs/installation" >}})ガイドを読むか、[例]({{< ref "samples" >}})を見て、Congoは何ができるか確認してください。
|
||||
|
||||
_このドキュメントに素晴らしいイラストを提供してくれた[Katerina Limpitsouni](https://ninalimpi.com)に感謝します。_
|
||||
|
||||
---
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
title: "Documentation"
|
||||
description: "Learn how to use Congo and its features."
|
||||
|
||||
cascade:
|
||||
showDate: false
|
||||
showAuthor: false
|
||||
showSummary: true
|
||||
invertPagination: true
|
||||
---
|
||||
|
||||
{{< lead >}}
|
||||
Simple, yet powerful. Learn how to use Congo and its features.
|
||||
{{< /lead >}}
|
||||
|
||||
|
||||
|
||||
This section contains everything you need to know about Congo. If you're new, check out the [Installation]({{< ref "docs/installation" >}}) guide to begin or visit the [Samples]({{< ref "samples" >}}) section to see what Congo can do.
|
||||
|
||||
_Special thanks to [Katerina Limpitsouni](https://ninalimpi.com) for the excellent illustrations that are used throughout these docs!_
|
||||
|
||||
---
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
title: "文档"
|
||||
description: "了解如何使用Congo及其功能。"
|
||||
|
||||
cascade:
|
||||
showDate: false
|
||||
showAuthor: false
|
||||
showSummary: true
|
||||
invertPagination: true
|
||||
---
|
||||
|
||||
{{< lead >}}
|
||||
简单而强大。了解如何使用Congo及其功能。
|
||||
{{< /lead >}}
|
||||
|
||||
|
||||
|
||||
该部分包含关于Congo的所有必要信息。如果您是新手，请查看 [安装]({{< ref "docs/installation" >}}) 指南以开始，或访问 [示例]({{< ref "samples" >}}) 部分查看Congo的功能。
|
||||
|
||||
特别感谢 [Katerina Limpitsouni](https://ninalimpi.com) 为这些文档中使用的出色插图！
|
||||
|
||||
---
|
||||
@@ -0,0 +1,183 @@
|
||||
---
|
||||
title: "高度なカスタマイズ"
|
||||
date: 2020-08-08
|
||||
draft: false
|
||||
description: "Congoを手動で構築する方法"
|
||||
summary: "Congoは、基本的なTailwind設定の変更、手動でのテーマ構築、カスタムCSSの提供など、高度なカスタマイズをサポートしています。"
|
||||
slug: "advanced-customisation"
|
||||
tags: ["advanced", "css", "docs"]
|
||||
---
|
||||
|
||||
Congoに高度な変更を加える方法はたくさんあります。カスタマイズできる内容や、ご希望の結果を得るための最良の方法については、以下をお読みください。
|
||||
|
||||
さらにアドバイスが必要な場合は[GitHub Discussions](https://github.com/jpanther/congo/discussions)に質問を投稿してください。
|
||||
|
||||
## Hugoプロジェクトの構造
|
||||
|
||||
これらの作業に入る前に、[Hugoプロジェクトの構造](https://gohugo.io/getting-started/directory-structure/)とコンテンツやテーマを管理するためのベストプラクティスについて説明します。
|
||||
|
||||
{{< alert >}}
|
||||
**要約:** テーマファイルを直接編集するのではなく、Hugoプロジェクトのサブディレクトリでカスタマイズを行なってください。
|
||||
{{< /alert >}}
|
||||
|
||||
Congoは、Hugoの標準的なプラクティスをすべて活用できるように作られています。コアのテーマファイルを変更することなく、テーマのすべての側面をカスタマイズしたり上書きしたりできるように設計されています。これにより、ウェブサイトのルック＆フィールを完全にコントロールしながら、シームレスなアップグレードが可能になります。
|
||||
|
||||
そのためには、テーマファイルを手動で直接調整してはいけません。Hugo モジュールを使ってインストールする場合でも、git サブモジュールとしてインストールする場合でも、手動でテーマを `themes/` ディレクトリにインクルードする場合でも、これらのファイルは常にそのままにしておくべきです。
|
||||
|
||||
テーマの動作を調整する正しい方法は、Hugoの強力な[file lookup order](https://gohugo.io/templates/lookup-order/)を使ってファイルを上書きすることです。そうすることで、あなたがプロジェクトディレクトリにインクルードしたファイルが自動的にテーマファイルよりも優先されることを保証します。
|
||||
|
||||
例えば、Congoのメイン記事テンプレートをオーバーライドしたい場合、独自の `layouts/_default/single.html` ファイルを作成し、プロジェクトのルートに置くだけです。このファイルはテーマを変更することなく、テーマの `single.html` を上書きします。これは、HTMLテンプレート、パーシャル、ショートコード、設定ファイル、データ、アセットなど、どんなテーマファイルにも使えます。
|
||||
|
||||
このシンプルな慣習に従う限り、あなたのカスタマイズを失うことなく、常にテーマをアップデート（または異なるテーマのバージョンをテスト）することができます。
|
||||
|
||||
## カラースキーム
|
||||
|
||||
Congoにはいくつかのカラースキームが同梱されています。配色を変更するには、 `colorScheme` テーマパラメーターを設定します。組み込みの配色について詳しくは[はじめに]({{< ref "getting-started" >}})セクションを参照してください。
|
||||
|
||||
デフォルトの配色に加えて、独自のスキームを作成し、ウェブサイト全体を好みのスタイルに変更することもできます。スキームは `assets/css/schemes/` ディレクトリに `<scheme-name>.css` ファイルを置くことで作成できます。ファイルを作成したら、テーマ設定の中でその名前を参照するだけです。
|
||||
|
||||
Congoは3色のパレットを定義してテーマ全体に使用しています。この3色は「ニュートラル」、「プライマリー」、「セカンダリー」として定義され、それぞれ10色の濃淡があります。
|
||||
|
||||
Tailwind CSS 3.0が不透明度を用いてカラー値を計算するため、使用するカラーは[特定のフォーマットに準拠](https://github.com/adamwathan/tailwind-css-variable-text-opacity-demo)して指定するする必要があります。
|
||||
|
||||
```css
|
||||
:root {
|
||||
--color-primary-500: 139, 92, 246;
|
||||
}
|
||||
```
|
||||
|
||||
この例では、 `primary-500` をCSS変数として `Red: 139, Green: 92, Blue: 246` に定義しています。
|
||||
|
||||
既存のテーマスタイルシートのいずれかをテンプレートとして使用してください。独自の色を定義するのは自由ですが、インスピレーションを得るために、公式の[Tailwind color palette reference](https://tailwindcss.com/docs/customizing-colors#color-palette-reference)もチェックしてみてください。
|
||||
|
||||
## スタイルのオーバーライド
|
||||
|
||||
独自のHTML要素にスタイルを設定するために、カスタムスタイルを追加する場合があります。Congoでは、独自のCSSスタイルシートでデフォルトのスタイルをオーバーライドすることができます。プロジェクトの `assets/css/` ディレクトリに `custom.css` ファイルを作成するだけです。
|
||||
|
||||
`custom.css` ファイルはHugoによってminifyされ、他のテーマスタイルの後に自動的に読み込まれます。
|
||||
|
||||
### フォントサイズの変更
|
||||
|
||||
`custom.css` を用いてフォントサイズをオーバーライドする例です。Congoでは、ベースとなるHTMLフォントサイズに由来するフォントサイズをテーマ全体で使用するため、フォントサイズの変更は簡単です。デフォルトでは、Tailwindはデフォルトサイズを`12pt`に設定していますが、お好きな値に変更することができます。
|
||||
|
||||
`assets/css/custom.css` を用意して下記のように記述してください:
|
||||
|
||||
```css
|
||||
/* Increase the default font size */
|
||||
html {
|
||||
font-size: 13pt;
|
||||
}
|
||||
```
|
||||
|
||||
この1つの値を変更するだけで、ウェブサイト上のすべてのフォントサイズが新しいサイズに合わせて調整されます。したがって、全体のフォントサイズを大きくするには、値を `12pt` より大きくします。同様に、フォントサイズを小さくするには、値を `12pt` より小さくします。
|
||||
|
||||
## ソースコードから再構築
|
||||
|
||||
大きな変更を加えたい場合は、Tailwind CSSのJITコンパイラを利用し、テーマCSS全体をゼロから再構築することができます。これは、Tailwindの設定を調整したり、メインのスタイルシートに追加のTailwindクラスを追加したい場合に便利です。
|
||||
|
||||
{{< alert >}}
|
||||
**注記:** 手動でテーマを再構築するのは上級者向けです。
|
||||
{{< /alert >}}
|
||||
|
||||
それでは、Tailwind CSSの構築方法を順を追って説明しましょう。
|
||||
|
||||
### Tailwindの設定
|
||||
|
||||
実際に使用されているTailwindのクラスのみを含むCSSファイルを生成するために、JITコンパイラはすべてのHTMLテンプレートとMarkdownファイルをスキャンして、どのスタイルが存在するかをチェックします。コンパイラは、テーマディレクトリのルートに含まれる `tailwind.config.js` ファイルを参照します:
|
||||
|
||||
```js
|
||||
// themes/congo/tailwind.config.js
|
||||
|
||||
module.exports = {
|
||||
content: [
|
||||
"./layouts/**/*.html",
|
||||
"./content/**/*.{html,md}",
|
||||
"./themes/congo/layouts/**/*.html",
|
||||
"./themes/congo/content/**/*.{html,md}",
|
||||
],
|
||||
|
||||
// and more...
|
||||
};
|
||||
```
|
||||
|
||||
デフォルトでは、特定のプロジェクト構造に従っていれば、修正することなく簡単に独自のCSSファイルを生成できるようにコンテンツパスが設定されています。つまり、**Congo を `themes/congo/` のサブディレクトリとしてプロジェクトに含める必要があります。**
|
||||
よって、Hugoモジュールを使って簡単にテーマをインストールすることはできず、 Gitサブモジュール（推奨）か手動インストールのどちらかの方法を取らなければなりません。[インストール]({{< ref "installation" >}})では、これらの方法のいずれかを使ってテーマをインストールする方法を説明しています。
|
||||
|
||||
### プロジェクトの構造
|
||||
|
||||
デフォルト設定の恩恵を授かるには、プロジェクトは下記のような構造になっているべきです。
|
||||
|
||||
```shell
|
||||
.
|
||||
├── assets
|
||||
│ └── css
|
||||
│ └── compiled
|
||||
│ └── main.css # this is the file we will generate
|
||||
├── config # site config
|
||||
│ └── _default
|
||||
├── content # site content
|
||||
│ ├── _index.md
|
||||
│ ├── projects
|
||||
│ │ └── _index.md
|
||||
│ └── blog
|
||||
│ └── _index.md
|
||||
├── layouts # custom layouts for your site
|
||||
│ ├── partials
|
||||
│ │ └── extend-article-link.html
|
||||
│ ├── projects
|
||||
│ │ └── list.html
|
||||
│ └── shortcodes
|
||||
│ └── disclaimer.html
|
||||
└── themes
|
||||
└── congo # git submodule or manual theme install
|
||||
```
|
||||
|
||||
この構造例では、独自のカスタムレイアウトを持つ新しい `projects` コンテンツタイプを、カスタムショートコードと拡張パーシャルとともに追加します。プロジェクトがこの構造に従っていれば、必要なのは `main.css` ファイルを再コンパイルすることだけです。
|
||||
|
||||
### 依存関係のインストール
|
||||
|
||||
上記を動作させるには、 `themes/congo/` ディレクトリにて、プロジェクトの依存関係をインストールする必要がある。このステップには[npm](https://docs.npmjs.com/cli/v7/configuring-npm/install)が必要です。
|
||||
|
||||
```shell
|
||||
cd themes/congo
|
||||
npm install
|
||||
```
|
||||
|
||||
### Tailwindコンパイラの実行
|
||||
|
||||
依存関係のインストールが完了したら、あとは[Tailwind CLI](https://v2.tailwindcss.com/docs/installation#using-tailwind-cli)を使ってJITコンパイラを起動するだけです。Hugoプロジェクトのルートに戻り、以下のコマンドを実行してください:
|
||||
|
||||
```shell
|
||||
cd ../..
|
||||
./themes/congo/node_modules/tailwindcss/lib/cli.js -c ./themes/congo/tailwind.config.js -i ./themes/congo/assets/css/main.css -o ./assets/css/compiled/main.css --jit
|
||||
```
|
||||
|
||||
このコマンドはパス指定の関係で少し醜いですが、基本的にはTailwind CLIを呼び出し、Tailwindの設定ファイル、 `main.css` の場所、そしてコンパイルされたCSSファイルを置く場所（ `assets/css/compiled/` ）を渡しています。
|
||||
|
||||
Tailwindの設定ファイルによって、プロジェクト内のすべてのコンテンツとレイアウト、およびテーマ内のすべてのコンテンツを自動的に走査し、ウェブサイトに必要なすべてのCSSを含む新しいCSSファイルを作成します。Hugoはプロジェクト内のファイルを自動的にテーマに付属するもので上書きします。
|
||||
|
||||
レイアウトを変更して新しいTailwind CSSスタイルが必要になるたびに、コマンドを再実行するだけで、新しいCSSファイルを生成することができます。コマンドの最後に `-w` を追加すると、JITコンパイラをウォッチモードで実行することもできます。
|
||||
|
||||
### buildスクリプトの準備
|
||||
|
||||
私がやっているように、必要なコマンドを含む `package.json` をプロジェクトのルートに追加して、再構築プロセスを簡単にすることもできます。
|
||||
|
||||
```js
|
||||
// package.json
|
||||
|
||||
{
|
||||
"name": "my-website",
|
||||
"version": "1.0.0",
|
||||
"description": "",
|
||||
"scripts": {
|
||||
"server": "hugo server -b http://localhost -p 8000",
|
||||
"dev": "NODE_ENV=development ./themes/congo/node_modules/tailwindcss/lib/cli.js -c ./themes/congo/tailwind.config.js -i ./themes/congo/assets/css/main.css -o ./assets/css/compiled/main.css --jit -w",
|
||||
"build": "NODE_ENV=production ./themes/congo/node_modules/tailwindcss/lib/cli.js -c ./themes/congo/tailwind.config.js -i ./themes/congo/assets/css/main.css -o ./assets/css/compiled/main.css --jit"
|
||||
},
|
||||
// and more...
|
||||
}
|
||||
```
|
||||
|
||||
これで、デザインに取りかかりたいときに `npm run dev` を実行すればコンパイラがウォッチモードで実行されます。デプロイする準備ができたら、 `npm run build` を実行すれば、通常のTailwind CSSビルドが実行されます。
|
||||
|
||||
🙋♀️ ヘルプが必要な場合は、遠慮なく[GitHub Discussions](https://github.com/jpanther/congo/discussions)に質問を投稿してください。
|
||||
@@ -0,0 +1,182 @@
|
||||
---
|
||||
title: "Advanced Customisation"
|
||||
date: 2020-08-08
|
||||
draft: false
|
||||
description: "Learn how to build Congo manually."
|
||||
summary: "Congo supports advanced customisations that include modifying the underlying Tailwind configuration, building the theme manually and providing custom CSS."
|
||||
slug: "advanced-customisation"
|
||||
tags: ["advanced", "css", "docs"]
|
||||
---
|
||||
|
||||
There are many ways you can make advanced changes to Congo. Read below to learn more about what can be customised and the best way of achieving your desired result.
|
||||
|
||||
If you need further advice, post your questions on [GitHub Discussions](https://github.com/jpanther/congo/discussions).
|
||||
|
||||
## Hugo project structure
|
||||
|
||||
Before leaping into it, first a quick note about [Hugo project structure](https://gohugo.io/getting-started/directory-structure/) and best practices for managing your content and theme customisations.
|
||||
|
||||
{{< alert >}}
|
||||
**In summary:** Never directly edit the theme files. Only make customisations in your Hugo project's sub-directories, not in the themes directory itself.
|
||||
{{< /alert >}}
|
||||
|
||||
Congo is built to take advantage of all the standard Hugo practices. It is designed to allow all aspects of the theme to be customised and overridden without changing any of the core theme files. This allows for a seamless upgrade experience while giving you total control over the look and feel of your website.
|
||||
|
||||
In order to achieve this, you should never manually adjust any of the theme files directly. Whether you install using Hugo modules, as a git submodule or manually include the theme in your `themes/` directory, you should always leave these files intact.
|
||||
|
||||
The correct way to adjust any theme behaviour is by overriding files using Hugo's powerful [file lookup order](https://gohugo.io/templates/lookup-order/). In summary, the lookup order ensures any files you include in your project directory will automatically take precedence over any theme files.
|
||||
|
||||
For example, if you wanted to override the main article template in Congo, you can simply create your own `layouts/_default/single.html` file and place it in the root of your project. This file will then override the `single.html` from the theme without ever changing the theme itself. This works for any theme files - HTML templates, partials, shortcodes, config files, data, assets, etc.
|
||||
|
||||
As long as you follow this simple practice, you will always be able to update the theme (or test different theme versions) without worrying that you will lose any of your custom changes.
|
||||
|
||||
## Colour schemes
|
||||
|
||||
Congo ships with a number of colour schemes out of the box. To change the basic colour scheme, you can set the `colorScheme` theme parameter. Refer to the [Getting Started]({{< ref "getting-started#colour-schemes" >}}) section to learn more about the built-in schemes.
|
||||
|
||||
In addition to the default schemes, you can also create your own and re-style the entire website to your liking. Schemes are created by by placing a `<scheme-name>.css` file in the `assets/css/schemes/` folder. Once the file is created, simply refer to it by name in the theme configuration.
|
||||
|
||||
Congo defines a three-colour palette that is used throughout the theme. The three colours are defined as `neutral`, `primary` and `secondary` variants, each containing ten shades of colour.
|
||||
|
||||
Due to the way Tailwind CSS 3.0 calculates colour values with opacity, the colours specified in the scheme need to [conform to a particular format](https://github.com/adamwathan/tailwind-css-variable-text-opacity-demo) by providing the red, green and blue colour values.
|
||||
|
||||
```css
|
||||
:root {
|
||||
--color-primary-500: 139, 92, 246;
|
||||
}
|
||||
```
|
||||
|
||||
This example defines a CSS variable for the `primary-500` colour with a red value of `139`, green value of `92` and blue value of `246`.
|
||||
|
||||
Use one of the existing theme stylesheets as a template. You are free to define your own colours, but for some inspiration, check out the official [Tailwind colour palette reference](https://tailwindcss.com/docs/customizing-colors#color-palette-reference).
|
||||
|
||||
## Overriding the stylesheet
|
||||
|
||||
Sometimes you need to add a custom style to style your own HTML elements. Congo provides for this scenario by allowing you to override the default styles in your own CSS stylesheet. Simply create a `custom.css` file in your project's `assets/css/` folder.
|
||||
|
||||
The `custom.css` file will be minified by Hugo and loaded automatically after all the other theme styles which means anything in your custom file will take precedence over the defaults.
|
||||
|
||||
### Adjusting the font size
|
||||
|
||||
Changing the font size of your website is one example of overriding the default stylesheet. Congo makes this simple as it uses scaled font sizes throughout the theme which are derived from the base HTML font size. By default, Tailwind sets the default size to `12pt`, but it can be changed to whatever value you prefer.
|
||||
|
||||
Create a `custom.css` file using the [instructions above]({{< ref "#overriding-the-stylesheet" >}}) and add the following CSS declaration:
|
||||
|
||||
```css
|
||||
/* Increase the default font size */
|
||||
html {
|
||||
font-size: 13pt;
|
||||
}
|
||||
```
|
||||
|
||||
Simply by changing this one value, all the font sizes on your website will be adjusted to match this new size. Therefore, to increase the overall font sizes used, make the value greater than `12pt`. Similarly, to decrease the font sizes, make the value less than `12pt`.
|
||||
|
||||
## Building the theme CSS from source
|
||||
|
||||
If you'd like to make a major change, you can take advantage of Tailwind CSS's JIT compiler and rebuild the entire theme CSS from scratch. This is useful if you want to adjust the Tailwind configuration or add extra Tailwind classes to the main stylesheet.
|
||||
|
||||
{{< alert >}}
|
||||
**Note:** Building the theme manually is intended for advanced users.
|
||||
{{< /alert >}}
|
||||
|
||||
Let's step through how building the Tailwind CSS works.
|
||||
|
||||
### Tailwind configuration
|
||||
|
||||
In order to generate a CSS file that only contains the Tailwind classes that are actually being used the JIT compiler needs to scan through all the HTML templates and Markdown content files to check which styles are present in the markup. The compiler does this by looking at the `tailwind.config.js` file which is included in the root of the theme directory:
|
||||
|
||||
```js
|
||||
// themes/congo/tailwind.config.js
|
||||
|
||||
module.exports = {
|
||||
content: [
|
||||
"./layouts/**/*.html",
|
||||
"./content/**/*.{html,md}",
|
||||
"./themes/congo/layouts/**/*.html",
|
||||
"./themes/congo/content/**/*.{html,md}",
|
||||
],
|
||||
|
||||
// and more...
|
||||
};
|
||||
```
|
||||
|
||||
This default configuration has been included with these content paths so that you can easily generate your own CSS file without needing to modify it, provided you follow a particular project structure. Namely, **you have to include Congo in your project as a subdirectory at `themes/congo/`**. This means you cannot easily use Hugo Modules to install the theme and you must go down either the git submodule (recommended) or manual install routes. The [Installation docs]({{< ref "installation" >}}) explain how to install the theme using either of these methods.
|
||||
|
||||
### Project structure
|
||||
|
||||
In order to take advantage of the default configuration, your project should look something like this...
|
||||
|
||||
```shell
|
||||
.
|
||||
├── assets
|
||||
│ └── css
|
||||
│ └── compiled
|
||||
│ └── main.css # this is the file we will generate
|
||||
├── config # site config
|
||||
│ └── _default
|
||||
├── content # site content
|
||||
│ ├── _index.md
|
||||
│ ├── projects
|
||||
│ │ └── _index.md
|
||||
│ └── blog
|
||||
│ └── _index.md
|
||||
├── layouts # custom layouts for your site
|
||||
│ ├── partials
|
||||
│ │ └── extend-article-link.html
|
||||
│ ├── projects
|
||||
│ │ └── list.html
|
||||
│ └── shortcodes
|
||||
│ └── disclaimer.html
|
||||
└── themes
|
||||
└── congo # git submodule or manual theme install
|
||||
```
|
||||
|
||||
This example structure adds a new `projects` content type with its own custom layout along with a custom shortcode and extended partial. Provided the project follows this structure, all that's required is to recompile the `main.css` file.
|
||||
|
||||
### Install dependencies
|
||||
|
||||
In order for this to work you'll need to change into the `themes/congo/` directory and install the project dependencies. You'll need [npm](https://docs.npmjs.com/cli/v7/configuring-npm/install) on your local machine for this step.
|
||||
|
||||
```shell
|
||||
cd themes/congo
|
||||
npm install
|
||||
```
|
||||
|
||||
### Run the Tailwind compiler
|
||||
|
||||
With the dependencies installed all that's left is to use [Tailwind CLI](https://v2.tailwindcss.com/docs/installation#using-tailwind-cli) to invoke the JIT compiler. Navigate back to the root of your Hugo project and issue the following command:
|
||||
|
||||
```shell
|
||||
cd ../..
|
||||
./themes/congo/node_modules/tailwindcss/lib/cli.js -c ./themes/congo/tailwind.config.js -i ./themes/congo/assets/css/main.css -o ./assets/css/compiled/main.css --jit
|
||||
```
|
||||
|
||||
It's a bit of an ugly command due to the paths involved but essentially you're calling Tailwind CLI and passing it the location of the Tailwind config file (the one we looked at above), where to find the theme's `main.css` file and then where you want the compiled CSS file to be placed (it's going into the `assets/css/compiled/` folder of your Hugo project).
|
||||
|
||||
The config file will automatically inspect all the content and layouts in your project as well as all those in the theme and build a new CSS file that contains all the CSS required for your website. Due to the way Hugo handles file hierarchy, this file in your project will now automatically override the one that comes with the theme.
|
||||
|
||||
Each time you make a change to your layouts and need new Tailwind CSS styles, you can simply re-run the command and generate the new CSS file. You can also add `-w` to the end of the command to run the JIT compiler in watch mode.
|
||||
|
||||
### Make a build script
|
||||
|
||||
To fully complete this solution, you can simplify this whole process by adding aliases for these commands, or do what I do and add a `package.json` to the root of your project which contains the necessary scripts...
|
||||
|
||||
```js
|
||||
// package.json
|
||||
|
||||
{
|
||||
"name": "my-website",
|
||||
"version": "1.0.0",
|
||||
"description": "",
|
||||
"scripts": {
|
||||
"server": "hugo server -b http://localhost -p 8000",
|
||||
"dev": "NODE_ENV=development ./themes/congo/node_modules/tailwindcss/lib/cli.js -c ./themes/congo/tailwind.config.js -i ./themes/congo/assets/css/main.css -o ./assets/css/compiled/main.css --jit -w",
|
||||
"build": "NODE_ENV=production ./themes/congo/node_modules/tailwindcss/lib/cli.js -c ./themes/congo/tailwind.config.js -i ./themes/congo/assets/css/main.css -o ./assets/css/compiled/main.css --jit"
|
||||
},
|
||||
// and more...
|
||||
}
|
||||
```
|
||||
|
||||
Now when you want to work on designing your site, you can invoke `npm run dev` and the compiler will run in watch mode. When you're ready to deploy, run `npm run build` and you'll get a clean Tailwind CSS build.
|
||||
|
||||
🙋♀️ If you need help, feel free to ask a question on [GitHub Discussions](https://github.com/jpanther/congo/discussions).
|
||||
@@ -0,0 +1,182 @@
|
||||
---
|
||||
title: "高级定制"
|
||||
date: 2020年8月8日
|
||||
draft: false
|
||||
description: "学习如何手动构建 Congo。"
|
||||
summary: "Congo 支持高级定制，包括修改底层的 Tailwind 配置，手动构建主题以及提供自定义 CSS。"
|
||||
slug: "advanced-customisation"
|
||||
tags: ["高级", "CSS", "文档"]
|
||||
---
|
||||
|
||||
有许多方法可以对 Congo 进行高级更改。阅读以下内容，了解可以定制的内容以及实现所需结果的最佳方式。
|
||||
|
||||
如果您需要进一步的建议，请在 [GitHub 讨论区](https://github.com/jpanther/congo/discussions) 上发表您的问题。
|
||||
|
||||
## Hugo 项目结构
|
||||
|
||||
在深入了解之前，首先简要介绍一下[Hugo 项目结构](https://gohugo.io/getting-started/directory-structure/)和管理内容以及主题定制的最佳实践。
|
||||
|
||||
{{< alert >}}
|
||||
**总结：**永远不要直接编辑主题文件。只在 Hugo 项目的子目录中进行定制，而不要在主题目录本身进行定制。
|
||||
{{< /alert >}}
|
||||
|
||||
Congo 的构建旨在充分利用所有标准 Hugo 实践。它被设计为允许定制和覆盖主题的所有方面，而无需更改任何核心主题文件。这样一来，您可以在完全控制网站的外观和感觉的同时，获得无缝的升级体验。
|
||||
|
||||
为了实现这一点，您永远不应直接调整主题文件中的任何文件。无论您是使用 Hugo 模块安装，作为 git 子模块或手动将主题包含在您的 `themes/` 目录中，都应始终保持这些文件不变。
|
||||
|
||||
调整任何主题行为的正确方式是使用 Hugo 强大的[文件查找顺序](https://gohugo.io/templates/lookup-order/)。总体而言，查找顺序确保您在项目目录中包含的任何文件将自动优先于任何主题文件。
|
||||
|
||||
例如，如果您想要覆盖 Congo 中的主文章模板，您只需创建自己的 `layouts/_default/single.html` 文件并将其放置在项目的根目录。该文件将覆盖主题中的 `single.html`，而无需更改主题本身。这适用于任何主题文件 - HTML 模板、局部、短代码、配置文件、数据、资产等。
|
||||
|
||||
只要遵循这个简单的做法，您就始终能够更新主题（或测试不同的主题版本），而不必担心会丢失任何自定义更改。
|
||||
|
||||
## 颜色方案
|
||||
|
||||
Congo 默认提供了许多颜色方案。要更改基本的颜色方案，您可以设置 `colorScheme` 主题参数。请参阅 [入门指南]({{< ref "getting-started#colour-schemes" >}}) 部分，了解内置方案的更多信息。
|
||||
|
||||
除了默认方案之外，您还可以创建自己的方案，并根据自己的喜好重新设计整个网站。通过在 `assets/css/schemes/` 文件夹中放置 `<scheme-name>.css` 文件来创建方案。创建文件后，只需在主题配置中按名称引用即可。
|
||||
|
||||
Congo 定义了一个贯穿整个主题使用的三种颜色的调色板。这三种颜色分别被定义为 `neutral`、`primary` 和 `secondary` 变体，每种颜色包含十个色调。
|
||||
|
||||
由于 Tailwind CSS 3.0 使用不透明度计算颜色值的方式，方案中指定的颜色需要[符合特定格式](https://github.com/adamwathan/tailwind-css-variable-text-opacity-demo)，即提供红色、绿色和蓝色颜色值。
|
||||
|
||||
```css
|
||||
:root {
|
||||
--color-primary-500: 139, 92, 246;
|
||||
}
|
||||
```
|
||||
|
||||
此示例为 `primary-500` 颜色定义了一个 CSS 变量，其红色值为 `139`，绿色值为 `92`，蓝色值为 `246`。
|
||||
|
||||
使用现有的主题样式表作为模板。您可以自定义自己的颜色，但是为了一些灵感，请查看官方的 [Tailwind 颜色调色板参考](https://tailwindcss.com/docs/customizing-colors#color-palette-reference)。
|
||||
|
||||
## 覆盖样式表
|
||||
|
||||
有时您需要添加自定义样式以为自己的 HTML 元素设置样式。Congo 提供了允许您在自己的 CSS 样式表中覆盖默认样式的场景。只需在项目的 `assets/css/` 文件夹中创建一个 `custom.css` 文件。
|
||||
|
||||
`custom.css` 文件将由 Hugo 进行最小化，并在所有其他主题样式之后自动加载，这意味着自定义文件中的任何内容都将覆盖默认值。
|
||||
|
||||
### 调整字体大小
|
||||
|
||||
更改网站的字体大小是覆盖默认样式表的一个示例。Congo 使此变得简单，因为它在整个主题中使用了从基本 HTML 字体大小派生的缩放字体大小。默认情况下，Tailwind 将默认大小设置为 `12pt`，但可以更改为您喜欢的任何值。
|
||||
|
||||
使用上述[说明]({{< ref "#overriding-the-stylesheet" >}})创建一个 `custom.css` 文件，并添加以下 CSS 声明：
|
||||
|
||||
```css
|
||||
/* Increase the default font size */
|
||||
html {
|
||||
font-size: 13pt;
|
||||
}
|
||||
```
|
||||
|
||||
只需更改此一个值，您网站上的所有字体大小就会调整为匹配这个新大小。因此，要增加使用的整体字体大小，请将值设置为大于 `12pt`。同样，要减小字体大小，请将值设置为小于 `12pt`。
|
||||
|
||||
## 从源代码构建主题 CSS
|
||||
|
||||
如果您想进行重大更改，可以利用 Tailwind CSS 的 JIT 编译器从头开始重新构建整个主题 CSS。如果您想要调整 Tailwind 配置或向主样式表添加额外的 Tailwind 类，这将非常有用。
|
||||
|
||||
{{< alert >}}
|
||||
**注意：** 手动构建主题仅适用于高级用户。
|
||||
{{< /alert >}}
|
||||
|
||||
让我们逐步了解构建 Tailwind CSS 的过程。
|
||||
|
||||
### Tailwind 配置
|
||||
|
||||
为了生成一个仅包含实际使用的 Tailwind 类的 CSS 文件，JIT 编译器需要扫描所有 HTML 模板和 Markdown 内容文件，以检查标记中存在哪些样式。编译器通过查看主题目录根目录中包含的 `tailwind.config.js` 文件来执行此操作：
|
||||
|
||||
```js
|
||||
// themes/congo/tailwind.config.js
|
||||
|
||||
module.exports = {
|
||||
content: [
|
||||
"./layouts/**/*.html",
|
||||
"./content/**/*.{html,md}",
|
||||
"./themes/congo/layouts/**/*.html",
|
||||
"./themes/congo/content/**/*.{html,md}",
|
||||
],
|
||||
|
||||
// and more...
|
||||
};
|
||||
```
|
||||
|
||||
这个默认配置已经包含了这些内容路径，以便您可以轻松生成自己的 CSS 文件，而无需修改它，只要您遵循特定的项目结构。换句话说，**您必须将 Congo 作为子目录包含在项目中，即 `themes/congo/`**。这意味着您不能轻松使用 Hugo 模块来安装主题，而必须选择 git 子模块（推荐）或手动安装路线。[安装文档]({{< ref "installation" >}})解释了如何使用这两种方法之一安装主题。
|
||||
|
||||
### 项目结构
|
||||
|
||||
为了充分利用默认配置，您的项目结构应该长得像下面这个样子...
|
||||
|
||||
```shell
|
||||
.
|
||||
├── assets
|
||||
│ └── css
|
||||
│ └── compiled
|
||||
│ └── main.css # this is the file we will generate
|
||||
├── config # site config
|
||||
│ └── _default
|
||||
├── content # site content
|
||||
│ ├── _index.md
|
||||
│ ├── projects
|
||||
│ │ └── _index.md
|
||||
│ └── blog
|
||||
│ └── _index.md
|
||||
├── layouts # custom layouts for your site
|
||||
│ ├── partials
|
||||
│ │ └── extend-article-link.html
|
||||
│ ├── projects
|
||||
│ │ └── list.html
|
||||
│ └── shortcodes
|
||||
│ └── disclaimer.html
|
||||
└── themes
|
||||
└── congo # git submodule or manual theme install
|
||||
```
|
||||
|
||||
这个例子的结构添加了一个新的 `projects` 内容类型，具有自己的自定义布局，以及一个自定义短代码和扩展部分。只要项目遵循这个结构，唯一需要做的就是重新编译 `main.css` 文件。
|
||||
|
||||
### 安装依赖项
|
||||
|
||||
为了使这个工作，你需要切换到 `themes/congo/` 目录并安装项目的依赖项。对于这一步骤，你的本地机器上需要 [npm](https://docs.npmjs.com/cli/v7/configuring-npm/install)。
|
||||
|
||||
```shell
|
||||
cd themes/congo
|
||||
npm install
|
||||
```
|
||||
|
||||
### 运行 Tailwind 编译器
|
||||
|
||||
在安装了依赖项之后，唯一需要做的就是使用 [Tailwind CLI](https://v2.tailwindcss.com/docs/installation#using-tailwind-cli) 调用 JIT 编译器。返回到你的 Hugo 项目的根目录，执行以下命令：
|
||||
|
||||
```shell
|
||||
cd ../..
|
||||
./themes/congo/node_modules/tailwindcss/lib/cli.js -c ./themes/congo/tailwind.config.js -i ./themes/congo/assets/css/main.css -o ./assets/css/compiled/main.css --jit
|
||||
```
|
||||
|
||||
由于涉及到路径，这是一个有点丑陋的命令，但基本上你是在调用 Tailwind CLI 并传递 Tailwind 配置文件的位置（我们上面看到的文件），主题的 `main.css` 文件的位置，以及你想要放置编译后的 CSS 文件的位置（它将放在你的 Hugo 项目的 `assets/css/compiled/` 文件夹中）。
|
||||
|
||||
配置文件将自动检查你的项目中的所有内容和布局，以及主题中的所有内容，并构建一个新的 CSS 文件，其中包含你的网站所需的所有 CSS。由于 Hugo 处理文件层次结构的方式，这个文件在你的项目中现在将自动覆盖主题自带的文件。
|
||||
|
||||
每当你更改布局并需要新的 Tailwind CSS 样式时，只需重新运行该命令并生成新的 CSS 文件。你也可以在命令的末尾添加 `-w` 以在监视模式下运行 JIT 编译器。
|
||||
|
||||
### 创建构建脚本
|
||||
|
||||
为了完全完成这个解决方案，你可以通过为这些命令添加别名，或者像我一样，在你的项目根目录添加一个包含必要脚本的 `package.json` 文件，来简化整个过程...
|
||||
|
||||
```js
|
||||
// package.json
|
||||
|
||||
{
|
||||
"name": "my-website",
|
||||
"version": "1.0.0",
|
||||
"description": "",
|
||||
"scripts": {
|
||||
"server": "hugo server -b http://localhost -p 8000",
|
||||
"dev": "NODE_ENV=development ./themes/congo/node_modules/tailwindcss/lib/cli.js -c ./themes/congo/tailwind.config.js -i ./themes/congo/assets/css/main.css -o ./assets/css/compiled/main.css --jit -w",
|
||||
"build": "NODE_ENV=production ./themes/congo/node_modules/tailwindcss/lib/cli.js -c ./themes/congo/tailwind.config.js -i ./themes/congo/assets/css/main.css -o ./assets/css/compiled/main.css --jit"
|
||||
},
|
||||
// and more...
|
||||
}
|
||||
```
|
||||
|
||||
现在，当你想要设计你的网站时，你可以调用 `npm run dev`，编译器将在监视模式下运行。当你准备部署时，运行 `npm run build`，你将得到一个干净的 Tailwind CSS 构建。
|
||||
|
||||
🙋♀️ 如果你需要帮助，请随时在 [GitHub Discussions](https://github.com/jpanther/congo/discussions) 上提问。
|
||||
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 10 KiB |
@@ -0,0 +1,186 @@
|
||||
---
|
||||
title: "基本設定"
|
||||
date: 2020-08-14
|
||||
draft: false
|
||||
description: "Congoで利用可能なすべての設定"
|
||||
summary: "Congoで利用可能なすべてのサイト、言語、テーマ設定と、それらを使用してプロジェクトをカスタマイズする方法をご覧ください。"
|
||||
slug: "configuration"
|
||||
tags: ["config", "docs"]
|
||||
---
|
||||
|
||||
Congoは高度にカスタマイズ可能なテーマで、最新のHugoの機能のいくつかを使用して、設定方法を簡素化しています。
|
||||
|
||||
このテーマには、基本的なブログまたは静的ウェブサイトを立ち上げて実行できるようにするデフォルト設定が同梱されています。
|
||||
|
||||
> 同梱されている設定ファイルはTOMLフォーマットで提供されています。設定ファイルをYAMLやJSONに変換したい場合はご自由にどうぞ。
|
||||
|
||||
デフォルトのテーマ設定は各ファイルに文書化されているので、ニーズに合わせて自由に設定を調整することができます。
|
||||
|
||||
{{< alert >}}
|
||||
[インストール手順]({{< ref "/docs/installation#set-up-theme-configuration-files" >}})で説明されているように、Hugoプロジェクトの `config/_default/` にあるファイルを修正し、プロジェクトルートにある `config.toml` ファイルを削除することで、テーマの設定を調整します。
|
||||
{{< /alert >}}
|
||||
|
||||
## サイト設定
|
||||
|
||||
Hugoの標準的な設定変数はテーマ全体を通して尊重されますが、最良のエクスペリエンスのために設定すべき特別なものもあります。
|
||||
|
||||
サイトの設定は `config/_default/config.toml` ファイルで管理されます。下の表はCongoが利用するすべての設定の概要です。
|
||||
|
||||
この表で提供される変数名は、TOML構造を簡略化するためにドット記法を使用していることに注意してください（つまり、 `outputs.home` は `[outputs] home` を指します）。
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|Name|Default|Description|
|
||||
|---|---|---|
|
||||
|`theme`|`"congo"`|Hugo Modulesを使用する場合、この設定値は削除してください。他のすべてのインストールタイプでは、テーマを機能させるために `congo` に設定する必要があります。|
|
||||
|`baseURL`|_Not set_|ウェブサイトのルートへのURL。|
|
||||
|`defaultContentLanguage`|`"en"`|この値はテーマコンポーネントとコンテンツのデフォルト言語を決定します。サポートされる言語コードについては、下記の[言語と国際化](#言語と国際化)セクションを参照してください。|
|
||||
|`enableRobotsTXT`|`true`|有効にすると、サイトルートに `robots.txt` ファイルが作成され、検索エンジンがサイト全体をクロールできるようになります。あらかじめ用意されている `robots.txt` を利用したい場合は、`false` に設定して `static` ディレクトリにファイルを置いてください。完全にコントロールしたい場合は、[カスタムレイアウト]({{< ref "content-examples" >}})を指定してこのファイルを生成することができます。|
|
||||
|`paginate`|`10`|記事一覧の各ページに掲載される記事の数。|
|
||||
|`summaryLength`|`0`|記事の要約が[フロントマター]({{< ref "front-matter" >}})で提供されていない場合に、記事の要約を生成するために使われる単語の数。デフォルト値 `0` は最初の文章を使用します。この値は要約が非表示の場合には影響しません。|
|
||||
|`outputs.home`|`["HTML", "RSS", "JSON"]`|生成される出力フォーマット。Congoでは、すべてのテーマコンポーネントが正しく動作するために、HTML、RSS、JSONが必要です。|
|
||||
|`permalinks`|_Not set_|パーマリンクの設定は[Hugo docs](https://gohugo.io/content-management/urls/#permalinks)を参照してください。|
|
||||
|`taxonomies`|_Not set_|Taxonomiesについては、[コンテンツの整理]({{< ref "getting-started" >}})セクションを参照してください。|
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## 言語と国際化
|
||||
|
||||
Congoは完全な多言語ウェブサイト用に最適化されており、テーマのアセットはすぐに複数の言語に翻訳されます。言語設定により、複数バージョンのコンテンツを生成し、訪問者の母国語でカスタマイズされたエクスペリエンスを提供することができます。
|
||||
|
||||
Congoは現在、以下の言語に対応しています:
|
||||
|
||||
| Language | Code |
|
||||
| --------------------------------------- | ------- |
|
||||
| :gb: **English (default)** | `en` |
|
||||
| :egypt: Arabic | `ar` |
|
||||
| :bangladesh: Bengali | `bn` |
|
||||
| :bulgaria: Bulgarian | `bg` |
|
||||
| :cn: Chinese - Simplified (China) | `zh-cn` |
|
||||
| :taiwan: Chinese - Traditional (Taiwan) | `zh-tw` |
|
||||
| :flag-cz: Czech | `cs` |
|
||||
| :netherlands: Dutch | `nl` |
|
||||
| :finland: Finnish | `fi` |
|
||||
| :fr: French | `fr` |
|
||||
| :de: German | `de` |
|
||||
| :israel: Hebrew | `he` |
|
||||
| :hungary: Hungarian | `hu` |
|
||||
| :indonesia: Indonesian | `id` |
|
||||
| :it: Italian | `it` |
|
||||
| :jp: Japanese | `ja` |
|
||||
| :kr: Korean | `ko` |
|
||||
| :poland: Polish | `pl` |
|
||||
| :brazil: Portuguese (Brazil) | `pt-br` |
|
||||
| :portugal: Portuguese (Portugal) | `pt-pt` |
|
||||
| :romania: Romanian | `ro` |
|
||||
| :ru: Russian | `ru` |
|
||||
| :slovakia: Slovak | `sk` |
|
||||
| :es: Spanish (Spain) | `es` |
|
||||
| :sweden: Swedish | `sv` |
|
||||
| :flag-lk: Tamil | `ta` |
|
||||
| :tr: Turkish | `tr` |
|
||||
| :ukraine: Ukrainian | `uk` |
|
||||
| :vietnam: Vietnamese | `vi` |
|
||||
|
||||
翻訳文字列を含むカスタムファイルを `i18n/[code].yaml` に作成することでデフォルトの翻訳をオーバーライドできます。このメソッドを使って新しい言語を追加することもできます。新しい翻訳をコミュニティと共有したい場合、[Pull Request](https://github.com/jpanther/congo/pulls)を作ってください。
|
||||
|
||||
### 設定
|
||||
|
||||
可能な限り柔軟に対応するために、ウェブサイトの言語ごとに言語設定ファイルを作成する必要があります。デフォルトでは、Congoは `config/_default/languages.en.toml` に英語の言語設定を含んでいます。
|
||||
|
||||
英語以外の言語でウェブサイトを作成したい場合は、デフォルトのファイルをテンプレートとして使用したり、ファイル名を変更したりすることができます。ファイル名は `languages.[language-code].toml` という形式にしてください。
|
||||
|
||||
{{< alert >}}
|
||||
**注記:** [サイト設定](#サイト設定)の `defaultContentLanguage` パラメーターが、言語設定ファイル名の `[language-code]` と一致していることを確認してください。
|
||||
{{< /alert >}}
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|Name|Default|Description|
|
||||
|---|---|---|
|
||||
|`languageCode`|`"en"`|このファイルの言語コード。トップレベル言語 (例 `en`)またはサブ変数 (例 `en-AU`)で、ファイル名の `[language-code]` と一致する必要があります。|
|
||||
|`languageName`|`"English"`|言語名。|
|
||||
|`languageDirection`|`"ltr"`|RTL言語かどうか。 `"rtl"` に設定すると、コンテンツを右から左にリフローする。CongoはRTL言語とLTR言語の同時使用を完全にサポートしており、動的に両方の言語に調整します。|
|
||||
|`weight`|`1`|多言語サイトを構築する際の優先順序。|
|
||||
|`title`|`"Congo"`|ウェブサイトのタイトル。サイトのヘッダーとフッターに表示されます。|
|
||||
|`copyright`|_Not set_|サイトのフッターに表示する著作権メッセージを含むMarkdown文字列。何も指定されない場合、Congoは `title` を使って自動的にコピーライト文字列を生成します。|
|
||||
|`params.dateFormat`|`"2 January 2006"`|日付の書式。許容される書式については、[Hugo docs](https://gohugo.io/functions/format/#gos-layout-string)を参照してください。|
|
||||
|`params.mainSections`|_Not set_|最近の記事リストに表示するセクション。指定されていない場合は、記事の数が最も多いセクションが使われます。|
|
||||
|`params.description`|_Not set_|ウェブサイトの説明。これはサイトのメタデータに使用されます。|
|
||||
|`params.author.name`|_Not set_|著者の名前。これは記事のフッターと、プロフィールレイアウトが使用されている場合にホームページに表示されます。|
|
||||
|`params.author.image`|_Not set_|著者の画像ファイルへのパス。画像は縦横比1:1で、 `assets/` に置くこと。|
|
||||
|`params.author.headline`|_Not set_|著者の見出しを含むMarkdown文字列。プロフィールのトップページで著者の名前の下に表示されます。|
|
||||
|`params.author.bio`|_Not set_|著者の経歴を含むMarkdown文字列。記事のフッターに表示されます。|
|
||||
|`params.author.links`|_Not set_|著者の詳細とともに表示するリンク。設定ファイルにはリンクの例が含まれており、コメントを外すだけで有効にすることができます。リンクが表示される順番は、配列に表示される順番によって決まります。 `assets/icons/` に対応するSVGアイコンを用意することで、カスタムリンクを追加することもできます。|
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### メニュー
|
||||
|
||||
Congoは言語別メニュー設定もサポートしている。メニュー設定ファイルは、言語ファイルと同じ命名形式に従っています。ファイル名に言語コードを指定するだけで、そのファイルがどの言語に関連するかをHugoに伝えることができます。
|
||||
|
||||
メニュー設定ファイルは `menus.[language-code].toml` という形式で命名されます。 `[language-code]` が設定と一致していることを常に確認してください。
|
||||
|
||||
[はじめに]({{< ref "getting-started#メニュー" >}})セクションで、このファイルの構造について詳しく説明しています。また、[Hugo menu docs](https://gohugo.io/content-management/menus/)にも設定例があります。
|
||||
|
||||
## テーマパラメーター
|
||||
|
||||
Congoはテーマの機能を制御する多数の設定パラメーターを提供します。下の表は `config/_default/params.toml` ファイルで利用可能なパラメーターの概要です。
|
||||
|
||||
パラメーターの多くは、フロントマターで指定することで、記事ごとに上書きすることができます。詳しくは、[フロントマター]({{< ref "front-matter" >}})セクションを参照してください。
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|Name|Default|Description|
|
||||
|---|---|---|
|
||||
|`colorScheme`|`"congo"`|使用する配色。有効な値は `congo` (デフォルト), `avocado`, `cherry`, `fire`, `ocean`, `sapphire`, `slate` です。詳しくは [カラースキーム]({{< ref "getting-started#カラースキーム" >}})セクションを参照してください。|
|
||||
|`defaultAppearance`|`"light"`|デフォルトのテーマ外観、 `light` または `dark` のいずれか。|
|
||||
|`autoSwitchAppearance`|`true`|テーマの外観を訪問者のオペレーティングシステムの設定に基づいて自動的に切り替えるかどうか。常に `defaultAppearance` を使うようにするには `false` を設定します。|
|
||||
|`enableSearch`|`false`|サイト内検索を有効にするかどうか。検索機能を有効にするには `true` を設定します。検索機能は、[サイト設定](#サイト設定)の `outputs.home` が正しく設定されているかどうかに依存することに注意してください。|
|
||||
|`enableCodeCopy`|`false`|`<code>` ブロックに対してクリップボードへのコピーボタンを有効にするかどうか。 `highlight.noClasses` が `false` に設定されていなければ、コードコピーは正しく機能しません。[その他の設定ファイル](#その他の設定ファイル)については以下を参照してください。|
|
||||
|`enableImageLazyLoading`|`true`|ブラウザが遅延ロードするように画像をマークするかどうか。|
|
||||
|`robots`|_Not set_|ロボットがあなたのサイトをどのように扱うべきかを示す文字列。設定された場合、 `<head>` に出力されます。有効な値については[Googleのドキュメント](https://developers.google.com/search/docs/advanced/robots/robots_meta_tag#directives)を参照してください。|
|
||||
|`fingerprintAlgorithm`|`"sha256"`|`assets` にフィンガープリントを行う際のハッシュアルゴリズム。有効なオプションは `md5`、`sha256`、`sha384` および `sha512` です。|
|
||||
|`header.layout`|`"basic"`|ヘッダーとメニューのレイアウト。有効な値は `basic`、`hamburger`、`hybrid`または`custom`です。 `custom` に設定した場合は、 `/layouts/partials/header/custom.html` ファイルを作成して独自のレイアウトを指定する必要があります。|
|
||||
|`header.logo`|_Not set_|`assets/` 内のロゴファイルへの相対パス。ロゴファイルは2倍の解像度で提供され、任意の画像サイズに対応している必要があります。|
|
||||
|`header.logoDark`|_Not set_|`dark` モード時に使用されるロゴファイルへの相対パス。|
|
||||
|`header.showTitle`|`true`|サイトのタイトルをヘッダーに表示するかどうか。|
|
||||
|`footer.showCopyright`|`true`|サイトフッターにコピーライト文字列を表示するかどうか。[言語と国際化](#言語と国際化)の `copyright` パラメーターを使って文字列自体をカスタマイズできます。|
|
||||
|`footer.showThemeAttribution`|`true`|"Powered by Hugo & Congo" といった帰属表示をフッターに表示するかどうか。この表示を無効にする場合は、サイト上の他の場所（例えば、アバウトページなど）でテーマの帰属を表示することを検討してください。|
|
||||
|`footer.showAppearanceSwitcher`|`false`|フッターに外観スイッチャーを表示するかどうか。訪問者の設定を保持するためにブラウザのローカルストレージが使用されます。|
|
||||
|`footer.showScrollToTop`|`true`|`true` に設定すると、最上部にスクロールする矢印が表示されます。|
|
||||
|`homepage.layout`|`"page"`|ホームページのレイアウト。有効な値は `page`, `profile` または `custom` です。 `custom` に設定した場合は、 `/layouts/partials/home/custom.html` ファイルを作成して、独自のレイアウトを指定する必要があります。詳しくは[ホームページレイアウト]({{< ref "homepage-layout" >}})セクションを参照してください。|
|
||||
|`homepage.showRecent`|`false`|ホームページに最近の記事リストを表示するかどうか。|
|
||||
|`homepage.recentLimit`|`5`|`homepage.showRecent` が `true` の場合に表示する最近の記事の最大数。|
|
||||
|`article.showDate`|`true`|記事が作成された日付を表示するかどうか。|
|
||||
|`article.showDateUpdated`|`false`|記事が更新された日付を表示するかどうか。|
|
||||
|`article.showAuthor`|`true`|記事フッターに著者欄を表示するかどうか。|
|
||||
|`article.showBreadcrumbs`|`false`|記事のヘッダーにパンくずリストを表示するかどうか。|
|
||||
|`article.showDraftLabel`|`true`|`--buildDrafts` でビルドしたときに、記事の横に下書きインジケータを表示するかどうか。|
|
||||
|`article.showEdit`|`false`|記事の内容を編集するためのリンクを表示するかどうか。|
|
||||
|`article.editURL`|_Not set_|`article.showEdit` がアクティブな場合の編集リンクのURL。|
|
||||
|`article.editAppendPath`|`true`|`article.editURL`で設定されたURLに現在の記事へのパスを追加するかどうか。|
|
||||
|`article.showHeadingAnchors`|`true`|見出しアンカーリンクを記事内の見出しと一緒に表示するかどうか。|
|
||||
|`article.showPagination`|`true`|記事のフッターに次/前の記事リンクを表示するかどうか。|
|
||||
|`article.invertPagination`|`false`|次の記事/前の記事リンクの向きを反転させるかどうか。|
|
||||
|`article.showReadingTime`|`true`|記事の予想読了時間を表示するかどうか。|
|
||||
|`article.showTableOfContents`|`false`|記事に目次を表示するかどうか。|
|
||||
|`article.showTaxonomies`|`false`|この記事に関連するTaxonomiesを表示するかどうか。|
|
||||
|`article.showWordCount`|`false`|記事の単語数を表示するかどうか。|
|
||||
|`article.showComments`|`false`|[コメント]({{< ref "partials#コメント" >}})を記事フッターの後に含めるかどうか。|
|
||||
|`article.sharingLinks`|_Not set_|各記事の最後に共有リンクを表示するかどうか。 `false` にすると共有リンクは表示されません。|
|
||||
|`list.showBreadcrumbs`|`false`|リストページのヘッダーにパンくずリストを表示するかどうか。|
|
||||
|`list.showTableOfContents`|`false`|リストページに目次を表示するかどうか。|
|
||||
|`list.showTaxonomies`|`false`|リストページに関連するTaxonomiesを表示するかどうか。|
|
||||
|`list.showSummary`|`false`|リストページに記事の要約を表示するかどうか。もし[フロントマター]({{< ref "front-matter" >}})で要約が提供されていない場合、[サイト設定](#サイト設定)の `summaryLength` パラメーターを使って要約が自動生成されます。|
|
||||
|`list.groupByYear`|`true`|リストページで記事を年ごとにグループ化するかどうか。|
|
||||
|`list.paginationWidth`|`1`|リストページを切り詰める際に、現在のページの両側にいくつのページネーションリンクを出力するか。 `1` の場合、現在のページの両側に1つのリンクを出力します。 _最初のページ_ と _最後のページ_ へのリンクは常に表示され、この値に追加されます。|
|
||||
|`sitemap.excludedKinds`|`["taxonomy", "term"]`|生成される `/sitemap.xml` から除外されるべきコンテンツの種類。許容される値については[Hugo docs](https://gohugo.io/templates/section-templates/#page-kinds)を参照してください。|
|
||||
|`taxonomy.showTermCount`|`true`|TaxonomiesのリストにTermごとの記事数を表示するかどうか。|
|
||||
|`fathomAnalytics.site`|_Not set_|Fathom Analyticsによって生成されたウェブサイトのサイトコード。詳細は[アナリティクス]({{< ref "partials#アナリティクス" >}})を参照してください。|
|
||||
|`verification.google`|_Not set_|サイトのメタデータに含めるGoogleが提供するサイト検証文字列。|
|
||||
|`verification.bing`|_Not set_|サイトのメタデータに含めるBingが提供するサイト検証文字列。|
|
||||
|`verification.pinterest`|_Not set_|サイトのメタデータに含めるPinterestが提供するサイト検証文字列。|
|
||||
|`verification.yandex`|_Not set_|サイトのメタデータに含めるYandexが提供するサイト検証文字列。|
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## その他の設定ファイル
|
||||
|
||||
このテーマには `markup.toml` 設定ファイルも含まれています。このファイルにはいくつかの重要なパラメータが含まれており、Congoで構築されたサイトを生成するためにHugoが正しく設定されるようにします。
|
||||
|
||||
このファイルがconfigディレクトリに存在し、必要な値が設定されていることを常に確認してください。これを行わないと、特定の機能が正しく動作しなかったり、意図しない動作になったりする可能性があります。
|
||||
@@ -0,0 +1,191 @@
|
||||
---
|
||||
title: "Configuration"
|
||||
date: 2020-08-14
|
||||
draft: false
|
||||
description: "All the configuration variables available in Congo."
|
||||
summary: "Discover all the site, language and theme configurations that are available in Congo and how they can be used to customise your project."
|
||||
slug: "configuration"
|
||||
tags: ["config", "docs"]
|
||||
---
|
||||
|
||||
Congo is a highly customisable theme and uses some of the latest Hugo features to simplify how it is configured.
|
||||
|
||||
The theme ships with a default configuration that gets you up and running with a basic blog or static website.
|
||||
|
||||
> Configuration files bundled with the theme are provided in TOML format as this is the default Hugo syntax. Feel free to convert your config to YAML or JSON if you wish.
|
||||
|
||||
The default theme configuration is documented in each file so you can freely adjust the settings to meet your needs.
|
||||
|
||||
{{< alert >}}
|
||||
As outlined in the [installation instructions]({{< ref "/docs/installation#set-up-theme-configuration-files" >}}), you should adjust your theme configuration by modifying the files in the `config/_default/` folder of your Hugo project and delete the `config.toml` file in your project root.
|
||||
{{< /alert >}}
|
||||
|
||||
## Site configuration
|
||||
|
||||
Standard Hugo configuration variables are respected throughout the theme, however there are some specific things that should be configured for the best experience.
|
||||
|
||||
The site configuration is managed through the `config/_default/config.toml` file. The table below outlines all the settings that the Congo takes advantage of.
|
||||
|
||||
Note that the variable names provided in this table use dot notation to simplify the TOML data structure (ie. `outputs.home` refers to `[outputs] home`).
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|Name|Default|Description|
|
||||
|---|---|---|
|
||||
|`theme`|`"congo"`|When using Hugo Modules this config value should be removed. For all other installation types, this must be set to `congo` for the theme to function.|
|
||||
|`baseURL`|_Not set_|The URL to the root of the website.|
|
||||
|`defaultContentLanguage`|`"en"`|This value determines the default language of theme components and content. Refer to the [language and i18n](#language-and-i18n) section below for supported language codes.|
|
||||
|`enableRobotsTXT`|`true`|When enabled, a `robots.txt` file will be created in the site root that allows search engines to crawl the entire site. If you prefer to provide your own pre-made `robots.txt`, set to `false` and place your file in the `static` directory. For complete control, you may provide a [custom layout]({{< ref "content-examples#custom-layouts" >}}) to generate this file.|
|
||||
|`paginate`|`10`|The number of articles listed on each page of the article listing.|
|
||||
|`summaryLength`|`0`|The number of words that are used to generate the article summary when one is not provided in the [front matter]({{< ref "front-matter" >}}). A value of `0` will use the first sentence. This value has no effect when summaries are hidden.|
|
||||
|`outputs.home`|`["HTML", "RSS", "JSON"]`|The output formats that are generated for the site. Congo requires HTML, RSS and JSON for all theme components to work correctly.|
|
||||
|`permalinks`|_Not set_|Refer to the [Hugo docs](https://gohugo.io/content-management/urls/#permalinks) for permalink configuration.|
|
||||
|`taxonomies`|_Not set_|Refer to the [Organising content]({{< ref "getting-started#organising-content" >}}) section for taxonomy configuration.|
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## Language and i18n
|
||||
|
||||
Congo is optimised for full multilingual websites and theme assets are translated into several languages out of the box. The language configuration allows you to generate multiple versions of your content to provide a customised experience to your visitors in their native language.
|
||||
|
||||
The theme currently supports the following languages out of the box:
|
||||
|
||||
| Language | Code |
|
||||
| --------------------------------------- | ------- |
|
||||
| :gb: **English (default)** | `en` |
|
||||
| :egypt: Arabic | `ar` |
|
||||
| :bangladesh: Bengali | `bn` |
|
||||
| :bulgaria: Bulgarian | `bg` |
|
||||
| :cn: Chinese - Simplified (China) | `zh-cn` |
|
||||
| :taiwan: Chinese - Traditional (Taiwan) | `zh-tw` |
|
||||
| :flag-cz: Czech | `cs` |
|
||||
| :netherlands: Dutch | `nl` |
|
||||
| :finland: Finnish | `fi` |
|
||||
| :fr: French | `fr` |
|
||||
| :de: German | `de` |
|
||||
| :israel: Hebrew | `he` |
|
||||
| :hungary: Hungarian | `hu` |
|
||||
| :indonesia: Indonesian | `id` |
|
||||
| :it: Italian | `it` |
|
||||
| :jp: Japanese | `ja` |
|
||||
| :kr: Korean | `ko` |
|
||||
| :poland: Polish | `pl` |
|
||||
| :brazil: Portuguese (Brazil) | `pt-br` |
|
||||
| :portugal: Portuguese (Portugal) | `pt-pt` |
|
||||
| :romania: Romanian | `ro` |
|
||||
| :ru: Russian | `ru` |
|
||||
| :slovakia: Slovak | `sk` |
|
||||
| :es: Spanish (Spain) | `es` |
|
||||
| :sweden: Swedish | `sv` |
|
||||
| :flag-lk: Tamil | `ta` |
|
||||
| :tr: Turkish | `tr` |
|
||||
| :ukraine: Ukrainian | `uk` |
|
||||
| :vietnam: Vietnamese | `vi` |
|
||||
|
||||
The default translations can be overridden by creating a custom file in `i18n/[code].yaml` that contains the translation strings. You can also use this method to add new languages. If you'd like to share a new translation with the community, please [open a pull request](https://github.com/jpanther/congo/pulls).
|
||||
|
||||
### Configuration
|
||||
|
||||
In order to be as flexible as possible, a language configuration file needs to be created for each language on the website. By default Congo includes an English language configuration at `config/_default/languages.en.toml`.
|
||||
|
||||
The default file can be used as a template to create additional languages, or renamed if you wish to author your website in a language other than English. Simply name the file using the format `languages.[language-code].toml`.
|
||||
|
||||
{{< alert >}}
|
||||
**Note:** Ensure the `defaultContentLanguage` parameter in the [site configuration](#site-configuration) matches the language code in your language config filename.
|
||||
{{< /alert >}}
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|Name|Default|Description|
|
||||
|---|---|---|
|
||||
|`languageCode`|`"en"`|The Hugo language code for this file. It can be a top-level language (ie. `en`) or a sub-variant (ie. `en-AU`) and should match the language code in the filename.|
|
||||
|`languageName`|`"English"`|The name of the language.|
|
||||
|`languageDirection`|`"ltr"`|Whether or not this is an RTL language. Set to `"rtl"` to reflow content from right-to-left. Congo fully supports using RTL and LTR languages at the same time and will dynamically adjust to both.|
|
||||
|`weight`|`1`|The weight determines the order of languages when building multilingual sites.|
|
||||
|`title`|`"Congo"`|The title of the website. This will be displayed in the site header and footer.|
|
||||
|`copyright`|_Not set_|A Markdown string containing the copyright message to be displayed in the site footer. If none is provided, Congo will automatically generate a copyright string using the site `title`.|
|
||||
|`params.dateFormat`|`"2 January 2006"`|How dates are formatted in this language. Refer to the [Hugo docs](https://gohugo.io/functions/format/#gos-layout-string) for acceptable formats.|
|
||||
|`params.mainSections`|_Not set_|The sections that should be displayed in the recent articles list. If not provided the section with the greatest number of articles is used.|
|
||||
|`params.description`|_Not set_|The website description. This will be used in the site metadata.|
|
||||
|`params.author.name`|_Not set_|The author's name. This will be displayed in article footers, and on the homepage when the profile layout is used.|
|
||||
|`params.author.image`|_Not set_|Path to the image file of the author. The image should be a 1:1 aspect ratio and placed in the site's `assets/` folder.|
|
||||
|`params.author.headline`|_Not set_|A Markdown string containing the author's headline. It will be displayed on the profile homepage under the author's name.|
|
||||
|`params.author.bio`|_Not set_|A Markdown string containing the author's bio. It will be displayed in article footers.|
|
||||
|`params.author.links`|_Not set_|The links to display alongside the author's details. The config file contains example links which can simply be uncommented to enable. The order that the links are displayed is determined by the order they appear in the array. Custom links can be added by providing corresponding SVG icon assets in `assets/icons/`.|
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### Menus
|
||||
|
||||
Congo also supports language-specific menu configurations. Menu config files follow the same naming format as the languages file. Simply provide the language code in the file name to tell Hugo which language the file relates to.
|
||||
|
||||
Menu config files are named with the format `menus.[language-code].toml`. Always ensure that the language code used in the menus configuration matches the languages configuration.
|
||||
|
||||
The [Getting Started]({{< ref "getting-started#menus" >}}) section explains more about the structure of this file. You can also refer to the [Hugo menu docs](https://gohugo.io/content-management/menus/) for more configuration examples.
|
||||
|
||||
## Theme parameters
|
||||
|
||||
Congo provides a large number of configuration parameters that control how the theme functions. The table below outlines every available parameter in the `config/_default/params.toml` file.
|
||||
|
||||
Many of the article defaults here can be overridden on a per article basis by specifying it in the front matter. Refer to the [Front Matter]({{< ref "front-matter" >}}) section for further details.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|Name|Default|Description|
|
||||
|---|---|---|
|
||||
|`colorScheme`|`"congo"`|The theme colour scheme to use. Valid values are `congo` (default), `avocado`, `cherry`, `fire`, `ocean`, `sapphire` and `slate`. Refer to the [Colour Schemes]({{< ref "getting-started#colour-schemes" >}}) section for more details.|
|
||||
|`defaultAppearance`|`"light"`|The default theme appearance, either `light` or `dark`.|
|
||||
|`autoSwitchAppearance`|`true`|Whether the theme appearance automatically switches based upon the visitor's operating system preference. Set to `false` to force the site to always use the `defaultAppearance`.|
|
||||
|`enableSearch`|`false`|Whether site search is enabled. Set to `true` to enable search functionality. Note that the search feature depends on the `outputs.home` setting in the [site configuration](#site-configuration) being set correctly.|
|
||||
|`enableCodeCopy`|`false`|Whether copy-to-clipboard buttons are enabled for `<code>` blocks. The `highlight.noClasses` parameter must be set to `false` for code copy to function correctly. Read more about [other configuration files](#other-configuration-files) below.|
|
||||
|`enableImageLazyLoading`|`true`|Whether images should be marked for lazy loading by the browser.|
|
||||
|`enableImageWebp`|`true`|Whether images should be output in the more performant WebP format.|
|
||||
|`enableQuicklink`|`true`|Whether the [Quicklink](https://getquick.link/) library should be included in the site. Quicklink prefetches links based upon the user's viewport and leads to faster page navigation.|
|
||||
|`robots`|_Not set_|String that indicates how robots should handle your site. If set, it will be output in the page head. Refer to [Google's docs](https://developers.google.com/search/docs/advanced/robots/robots_meta_tag#directives) for valid values.|
|
||||
|`fingerprintAlgorithm`|`"sha256"`|String that indicates which hashing algorithm is used when fingerprinting assets. Valid options include `md5`, `sha256`, `sha384` and `sha512`.|
|
||||
|`header.layout`|`"basic"`|The layout of the page header and menu. Valid values are `basic`, `hamburger`, `hybrid` or `custom`. When set to `custom`, you must provide your own layout by creating a `/layouts/partials/header/custom.html` file.|
|
||||
|`header.logo`|_Not set_|The relative path to the site logo file within the `assets/` folder. The logo file should be provided at 2x resolution and supports any image dimensions.|
|
||||
|`header.logoDark`|_Not set_|As per the `header.logo` parameter, however this image is used whenever dark mode is active.|
|
||||
|`header.showTitle`|`true`|Whether the site title is displayed in the header.|
|
||||
|`footer.showCopyright`|`true`|Whether or not to show the copyright string in the site footer. Note that the string itself can be customised using the `copyright` parameter in the [languages configuration](#language-and-i18n).|
|
||||
|`footer.showThemeAttribution`|`true`|Whether or not to show the "powered by" theme attribution in the site footer. If you choose to disable this message, please consider attributing the theme somewhere else on your site (for example, on your about page).|
|
||||
|`footer.showAppearanceSwitcher`|`false`|Whether or not to show the appearance switcher in the site footer. The browser's local storage is used to persist the visitor's preference.|
|
||||
|`footer.showScrollToTop`|`true`|When set to `true` the scroll to top arrow is displayed.|
|
||||
|`homepage.layout`|`"page"`|The layout of the homepage. Valid values are `page`, `profile` or `custom`. When set to `custom`, you must provide your own layout by creating a `/layouts/partials/home/custom.html` file. Refer to the [Homepage Layout]({{< ref "homepage-layout" >}}) section for more details.|
|
||||
|`homepage.showRecent`|`false`|Whether or not to display the recent articles list on the homepage.|
|
||||
|`homepage.recentLimit`|`5`|The maximum number of recent articles to display when `homepage.showRecent` is `true`.|
|
||||
|`article.showDate`|`true`|Whether or not article dates are displayed.|
|
||||
|`article.showDateUpdated`|`false`|Whether or not the dates articles were updated are displayed.|
|
||||
|`article.showAuthor`|`true`|Whether or not the author box is displayed in the article footer.|
|
||||
|`article.showBreadcrumbs`|`false`|Whether or not breadcrumbs are displayed in the article header.|
|
||||
|`article.showDraftLabel`|`true`|Whether or not the draft indicator is shown next to articles when site is built with `--buildDrafts`.|
|
||||
|`article.showEdit`|`false`|Whether or not the link to edit the article content should be displayed.|
|
||||
|`article.editURL`|_Not set_|When `article.showEdit` is active, the URL for the edit link.|
|
||||
|`article.editAppendPath`|`true`|When `article.showEdit` is active, whether or not the path to the current article should be appended to the URL set at `article.editURL`.|
|
||||
|`article.showHeadingAnchors`|`true`|Whether or not heading anchor links are displayed alongside headings within articles.|
|
||||
|`article.showPagination`|`true`|Whether or not the next/previous article links are displayed in the article footer.|
|
||||
|`article.invertPagination`|`false`|Whether or not to flip the direction of the next/previous article links.|
|
||||
|`article.showReadingTime`|`true`|Whether or not article reading times are displayed.|
|
||||
|`article.showTableOfContents`|`false`|Whether or not the table of contents is displayed on articles.|
|
||||
|`article.showTaxonomies`|`false`|Whether or not the taxonomies related to this article are displayed.|
|
||||
|`article.showWordCount`|`false`|Whether or not article word counts are displayed.|
|
||||
|`article.showComments`|`false`|Whether or not the [comments partial]({{< ref "partials#comments" >}}) is included after the article footer.|
|
||||
|`article.sharingLinks`|_Not set_|An array of sharing links to display at the end of each article. Valid options include `facebook`, `x-twitter`, `mastodon`, `pinterest`, `reddit`, `linkedin`, `email`, `telegram` and `line`. When not provided, or set to `false`, no links will be displayed.|
|
||||
|`list.showBreadcrumbs`|`false`|Whether or not breadcrumbs are displayed in the header on list pages.|
|
||||
|`list.showTableOfContents`|`false`|Whether or not the table of contents is displayed on list pages.|
|
||||
|`list.showTaxonomies`|`false`|Whether or not the taxonomies related to this article are displayed on list pages.|
|
||||
|`list.showSummary`|`false`|Whether or not article summaries are displayed on list pages. If a summary is not provided in the [front matter]({{< ref "front-matter" >}}), one will be auto generated using the `summaryLength` parameter in the [site configuration](#site-configuration).|
|
||||
|`list.groupByYear`|`true`|Whether or not articles are grouped by year on list pages.|
|
||||
|`list.paginationWidth`|`1`|How many pagination links to output either side of the current page when the page list needs to be truncated. A width of `1` will output one link either side of the current page when the list needs to be truncated. Links to the current, first and last pages are always displayed and are in addition to this value.|
|
||||
|`sitemap.excludedKinds`|`["taxonomy", "term"]`|Kinds of content that should be excluded from the generated `/sitemap.xml` file. Refer to the [Hugo docs](https://gohugo.io/templates/section-templates/#page-kinds) for acceptable values.|
|
||||
|`taxonomy.showTermCount`|`true`|Whether or not the number of articles within a taxonomy term is displayed on the taxonomy listing.|
|
||||
|`fathomAnalytics.site`|_Not set_|The site code generated by Fathom Analytics for the website. Refer to the [Analytics docs]({{< ref "partials#analytics" >}}) for more details.|
|
||||
|`plausibleAnalytics.domain`|_Not set_|Enter the domain of the website you want to track. Refer to the [Analytics docs]({{< ref "partials#analytics" >}}) for more details.|
|
||||
|`plausibleAnalytics.event`|_Not set_|Plausible api event proxied URL. Refer to the [Analytics docs]({{< ref "partials#analytics" >}}) for more details.|
|
||||
|`plausibleAnalytics.script`|_Not set_|Plausible analysis script proxied URL. Refer to the [Analytics docs]({{< ref "partials#analytics" >}}) for more details.|
|
||||
|`verification.google`|_Not set_|The site verification string provided by Google to be included in the site metadata.|
|
||||
|`verification.bing`|_Not set_|The site verification string provided by Bing to be included in the site metadata.|
|
||||
|`verification.pinterest`|_Not set_|The site verification string provided by Pinterest to be included in the site metadata.|
|
||||
|`verification.yandex`|_Not set_|The site verification string provided by Yandex to be included in the site metadata.|
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## Other configuration files
|
||||
|
||||
The theme also includes a `markup.toml` configuration file. This file contains some important parameters that ensure that Hugo is correctly configured to generate sites built with Congo.
|
||||
|
||||
Always ensure this file is present in the config directory and that the required values are set. Failure to do so may cause certain features to function incorrectly and could result in unintended behaviour.
|
||||
@@ -0,0 +1,185 @@
|
||||
---
|
||||
title: "基本配置"
|
||||
date: 2020-08-14
|
||||
draft: false
|
||||
description: "Congo中所有可使用的设定变量"
|
||||
summary: "探索一下 Congo 中所有的站点、语言和主题配置变量，以及如何用于自定义你的项目。"
|
||||
slug: "configuration"
|
||||
tags: ["config", "docs"]
|
||||
---
|
||||
|
||||
Congo 是一个高度可定制的主题，利用一些最新的 Hugo 特性来简化配置过程。
|
||||
|
||||
该主题附带了一个默认配置，让你可以快速启动一个基本的博客或静态网站。
|
||||
|
||||
> 主题附带的配置文件采用 TOML 格式，因为这是 Hugo 的默认语法。如果你愿意，可以将配置转换为 YAML 或 JSON。
|
||||
|
||||
每个文件中都有默认主题配置的文档，因此你可以自由调整设置以满足你的需求。
|
||||
|
||||
{{< alert >}}
|
||||
正如在[安装说明]({{< ref "/docs/installation#set-up-theme-configuration-files" >}})中所述，你应该通过修改 Hugo 项目的 `config/_default/` 文件夹中的文件来调整主题配置，并删除项目根目录中的 `config.toml` 文件。
|
||||
{{< /alert >}}
|
||||
|
||||
## 网站配置
|
||||
|
||||
Congo主题全面遵循标准 Hugo 配置变量，但是有一些特定的配置项需要进行设置以获得最佳体验。
|
||||
|
||||
网站配置通过 `config/_default/config.toml` 文件管理。下表概述了 Congo 主题所使用的所有设置。
|
||||
|
||||
请注意，此表中提供的变量名使用点表示法来简化 TOML 数据结构（即 `outputs.home` 指的是 `[outputs] home`）。
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|名称|默认值|描述|
|
||||
|---|---|---|
|
||||
|`theme`|`"congo"`|使用 Hugo 模块方法安装时，应删除此配置值。对于所有其他安装类型，必须将其设置为 `congo`，以使主题正常运行。|
|
||||
|`baseURL`|_未设置_|网站根目录的 URL。|
|
||||
|`defaultContentLanguage`|`"en"`|此值确定主题组件和内容的默认语言。有关受支持的语言代码，请参阅下面的[语言和国际化](#language-and-i18n)部分。|
|
||||
|`enableRobotsTXT`|`true`|启用时，在站点根目录将创建一个 `robots.txt` 文件，允许搜索引擎爬取整个站点。如果你更喜欢提供自己制作的 `robots.txt`，请设置为 `false` 并将文件放置在 `static` 目录中。为了完全控制，你可以提供一个[自定义布局]({{< ref "content-examples#custom-layouts" >}})来生成此文件。|
|
||||
|`paginate`|`10`|在文章列表中每页列出的文章数。|
|
||||
|`summaryLength`|`0`|在[front matter]({{< ref "front-matter" >}})中未提供摘要时，用于生成文章摘要的字数。值为 `0` 将使用第一句。当摘要被隐藏时，此值无效。|
|
||||
|`outputs.home`|`["HTML", "RSS", "JSON"]`|生成站点的输出格式。Congo 需要 HTML、RSS 和 JSON 才能使所有主题组件正常工作。|
|
||||
|`permalinks`|_未设置_|有关固定链接配置，请参阅[Hugo文档](https://gohugo.io/content-management/urls/#permalinks)。|
|
||||
|`taxonomies`|_未设置_|有关分类法配置，请参阅[组织内容]({{< ref "getting-started#organising-content" >}})部分。|
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## 语言和国际化
|
||||
|
||||
Congo 针对完整的多语言网站进行了优化，并且主题assets中已经默认翻译成多种语言。语言配置允许您生成多个版本的内容，以为访问者提供在其母语中的定制体验。
|
||||
|
||||
该主题目前支持以下语言：
|
||||
|
||||
| 语言 | 代码 |
|
||||
| --------------------------------------- | ------- |
|
||||
| :gb: **英语（默认）** | `en` |
|
||||
| :egypt: 阿拉伯语 | `ar` |
|
||||
| :bangladesh: 孟加拉语 | `bn` |
|
||||
| :bulgaria: 保加利亚语 | `bg` |
|
||||
| :cn: 中文 - 简体（中国） | `zh-cn` |
|
||||
| :taiwan: 中文 - 繁体（台湾） | `zh-tw` |
|
||||
| :flag-cz: 捷克语 | `cs` |
|
||||
| :netherlands: 荷兰语 | `nl` |
|
||||
| :finland: 芬兰语 | `fi` |
|
||||
| :fr: 法语 | `fr` |
|
||||
| :de: 德语 | `de` |
|
||||
| :israel: 希伯来语 | `he` |
|
||||
| :hungary: 匈牙利语 | `hu` |
|
||||
| :indonesia: 印尼语 | `id` |
|
||||
| :it: 意大利语 | `it` |
|
||||
| :jp: 日语 | `ja` |
|
||||
| :poland: 波兰语 | `pl` |
|
||||
| :brazil: 葡萄牙语（巴西） | `pt-br` |
|
||||
| :portugal: 葡萄牙语（葡萄牙） | `pt-pt` |
|
||||
| :romania: 罗马尼亚语 | `ro` |
|
||||
| :ru: 俄语 | `ru` |
|
||||
| :slovakia: 斯洛伐克语 | `sk` |
|
||||
| :es: 西班牙语（西班牙） | `es` |
|
||||
| :tr: 土耳其语 | `tr` |
|
||||
| :ukraine: 乌克兰语 | `uk` |
|
||||
|
||||
默认翻译可以通过在 `i18n/[code].yaml` 中创建自定义文件来覆盖，其中包含翻译字符串。您还可以使用此方法添加新语言。如果您希望与社区分享新的翻译，请[Pull Request](https://github.com/jpanther/congo/pulls)。
|
||||
|
||||
### 配置
|
||||
|
||||
为了尽可能灵活，需要为网站上的每种语言创建一个语言配置文件。默认情况下，Congo 在 `config/_default/languages.en.toml` 中包含英语语言配置。
|
||||
|
||||
默认文件可以用作创建其他语言的模板，或者如果希望使用英语以外的语言编写网站，则可以重命名。只需使用格式 `languages.[language-code].toml` 命名文件。
|
||||
|
||||
{{< alert >}}
|
||||
**注意：** 确保[网站配置](#site-configuration)中的 `defaultContentLanguage` 参数与语言配置文件名中的语言代码匹配。
|
||||
{{< /alert >}}
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|名称|默认值|描述|
|
||||
|---|---|---|
|
||||
|`languageCode`|`"en"`|此文件的 Hugo 语言代码。它可以是顶级语言（即 `en`）或子变体（即 `en-AU`），并应与文件名中的语言代码匹配。|
|
||||
|`languageName`|`"English"`|语言的名称。|
|
||||
|`languageDirection`|`"ltr"`|这是否是 RTL 语言。设置为 `"rtl"` 以从右到左重新排列内容。Congo 完全支持同时使用 RTL 和 LTR 语言，并会动态调整到两者。|
|
||||
|`weight`|`1`|构建多语言站点时语言的顺序的权重。|
|
||||
|`title`|`"Congo"`|网站的标题。这将显示在站点标题和页脚中。|
|
||||
|`copyright`|_未设置_|包含要显示在站点页脚中的版权消息的 Markdown 字符串。如果未提供，则 Congo 将使用站点 `title` 自动生成版权字符串。|
|
||||
|`params.dateFormat`|`"2 January 2006"`|此语言中日期的格式。有关可接受格式，请参阅[Hugo文档](https://gohugo.io/functions/format/#gos-layout-string)。|
|
||||
|`params.mainSections`|_未设置_|显示在最新文章列表中的部分。如果未提供，则使用文章数最多的部分。|
|
||||
|`params.description`|_未设置_|网站描述。这将用于站点元数据。|
|
||||
|`author.name`|_未设置_|作者的姓名。这将显示在文章页脚和使用配置文件布局时在主页上。|
|
||||
|`author.image`|_未设置_|作者的图像文件路径。图像应为1:1的宽高比，并放置在站点的 `assets/` 文件夹中。|
|
||||
|`author.headline`|_未设置_|包含作者头衔的 Markdown 字符串。它将显示在主页上作者姓名下方。|
|
||||
|`author.bio`|_未设置_|包含作者简介的 Markdown 字符串。它将显示在文章页脚中。|
|
||||
|`author.links`|_未设置_|要显示在作者详细信息旁边的链接。配置文件包含可以取消注释以启用的示例链接。显示链接的顺序由它们在数组中出现的顺序确定。可以通过在 `assets/icons/` 中提供相应的 SVG 图标资产来添加自定义链接。|
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### 菜单
|
||||
|
||||
Congo 还支持语言特定的菜单配置。菜单配置文件遵循与语言文件相同的命名格式。只需在文件名中提供语言代码，以告诉 Hugo 该文件与哪种语言相关。
|
||||
|
||||
菜单配置文件的命名格式为 `menus.[language-code].toml`。始终确保菜单配置中使用的语言代码与语言配置相匹配。
|
||||
|
||||
[快速开始]({{< ref "getting-started#menus" >}})部分更详细地解释了此文件的结构。您还可以参考[Hugo 菜单文档](https://gohugo.io/content-management/menus/)以获取更多配置示例。
|
||||
|
||||
## 主题参数
|
||||
|
||||
Congo 提供了大量的配置参数，用于控制主题的功能。下表概述了 `config/_default/params.toml` 文件中的每个可用参数。
|
||||
|
||||
这里的许多文章默认值可以通过在 front matter 中指定来覆盖每篇文章的默认值。有关详细信息，请参阅[Front Matter]({{< ref "front-matter" >}})部分。
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|名称|默认值|描述|
|
||||
|---|---|---|
|
||||
|`colorScheme`|`"congo"`|要使用的主题颜色方案。有效值为 `congo`（默认）、`avocado`、`cherry`、`fire`、`ocean`、`sapphire` 和 `slate`。有关详细信息，请参阅[颜色方案]({{< ref "getting-started#颜色方案" >}})部分。|
|
||||
|`defaultAppearance`|`"light"`|默认的主题外观，可以是 `light` 或 `dark`。|
|
||||
|`autoSwitchAppearance`|`true`|主题外观是否根据访问者的操作系统首选项自动切换。设置为 `false` 以始终使用 `defaultAppearance`。|
|
||||
|`enableSearch`|`false`|是否启用站内搜索。设置为 `true` 以启用搜索功能。请注意，搜索功能取决于 [站点配置](#site-configuration) 中的 `outputs.home` 设置正确。|
|
||||
|`enableCodeCopy`|`false`|是否启用 `<code>` 块的复制到剪贴板按钮。`highlight.noClasses` 参数必须设置为 `false`，以使代码复制正常工作。有关[其他配置文件](#other-configuration-files)的详细信息，请阅读下文。|
|
||||
|`enableImageLazyLoading`|`true`|是否将图像标记为浏览器的延迟加载。|
|
||||
|`robots`|_未设置_|指示机器人如何处理您的站点的字符串。如果设置，将在页面头部输出。有关有效值，请参阅[Google 文档](https://developers.google.com/search/docs/advanced/robots/robots_meta_tag#directives)。|
|
||||
|`fingerprintAlgorithm`|`"sha256"`|指示在对assets进行指纹识别时使用的哈希算法。有效选项包括 `md5`、`sha256`、`sha384` 和 `sha512`。|
|
||||
|`header.layout`|`"basic"`|页面头部和菜单的布局。有效值为 `basic`、`hamburger`、`hybrid` 或 `custom`。当设置为 `custom` 时，您必须通过创建 `/layouts/partials/header/custom.html` 文件提供自己的布局。|
|
||||
|`header.logo`|_未设置_|站点徽标文件在 `assets/` 文件夹内的相对路径。徽标文件应以 2x 分辨率提供，并支持任何图像尺寸。|
|
||||
|`header.logoDark`|_未设置_|与 `header.logo` 参数相同，但此图像在启用深色模式时使用。|
|
||||
|`header.showTitle`|`true`|是否在页眉中显示站点标题。|
|
||||
|`footer.showCopyright`|`true`|是否在站点页脚显示版权字符串。请注意，可以使用[语言配置](#language-and-i18n)中的 `copyright` 参数自定义字符串。|
|
||||
|`footer.showThemeAttribution`|`true`|是否在站点页脚显示 "由...强力驱动" 的主题归属。如果选择禁用此消息，请考虑在站点的其他地方（例如关于页面）写上主题归属。|
|
||||
|`footer.showAppearanceSwitcher`|`false`|是否在站点页脚显示外观切换器。使用浏览器的本地存储来保留访问者的首选项。|
|
||||
|`footer.showScrollToTop`|`true`|设置为 `true` 时，将显示返回顶部箭头。|
|
||||
|`homepage.layout`|`"page"`|主页的布局。有效值为 `page`、`profile` 或 `custom`。当设置为 `custom` 时，您必须通过创建 `/layouts/partials/home/custom.html` 文件提供自己的布局。有关详细信息，请参阅[主页布局]({{< ref "homepage-layout" >}})部分。|
|
||||
|`homepage.showRecent`|`false`|是否在主页上显示最近的文章列表。|
|
||||
|`homepage.recentLimit`|`5`|当 `homepage.showRecent` 为 `true` 时，显示的最大最近文章数。|
|
||||
|`article.showDate`|`true`|是否显示文章日期。|
|
||||
|`article.showDateUpdated`|`false`|是否显示文章更新日期。|
|
||||
|`article.showAuthor`|`true`|是否在文章页脚显示作者框。|
|
||||
|`article.showBreadcrumbs`|`false`|是否在文章头部显示面包屑。|
|
||||
|`article.showDraftLabel`|`true`|在使用 `--buildDrafts` 构建站点时，是否显示文章旁边的草稿标签。|
|
||||
|`article.showEdit`|`false`|是否显示编辑文章内容的链接。|
|
||||
|`article.editURL`|_未设置_|当 `article.showEdit` 激活时，编辑链接的 URL。|
|
||||
|`article.editAppendPath`|`true`|当 `article.showEdit` 激活时，是否将当前文章的路径附加到设置为 `article.editURL` 的 URL。|
|
||||
|`article.showHeadingAnchors`|`true`|是否在文章内的标题旁边显示锚链接。|
|
||||
|`article.showPagination`|`true`|是否在文章页脚显示下一篇/上一篇文章的链接。|
|
||||
|`article.invertPagination`|`false`|是否翻转下一篇/上一篇文章链接的方向。|
|
||||
|`article.showReadingTime`|`true`|是否显示文章阅读时间。|
|
||||
|`article.showTableOfContents`|`false`|是否在文章上显示目录。|
|
||||
|`article.showTaxonomies`|`false`|是否在与文章相关的分类法上显示。|
|
||||
|`article.showWordCount`|`false`|是否显示文章字数。|
|
||||
|`article.showComments`|`false`|是否在文章页脚之后包含[comments partial]({{< ref "partials#comments" >}})。|
|
||||
|`article.sharingLinks`|_未设置_|要在每篇文章末尾显示的分享链接。如果未提供或设置为 `false`，则不会显示任何链接。|
|
||||
|`list.showBreadcrumbs`|`false`|是否在列表页面的页眉中显示面包屑。|
|
||||
|`list.showTableOfContents`|`false`|是否在列表页面上显示目录。|
|
||||
|`list.showTaxonomies`|`false`|是否在列表页面上显示与此文章相关的分类法。|
|
||||
|`list.showSummary`|`false`|是否在列表页面上显示文章摘要。如果在[Front Matter]({{< ref "front-matter" >}})中未提供摘要，则将使用[站点配置](#site-configuration)中的 `summaryLength` 参数自动生成一个摘要。|
|
||||
|`list.groupByYear`|`true`|是否在列表页面上按年份对文章进行分组。|
|
||||
|`list.paginationWidth`|`1`|在需要截断页面列表时，输出当前页面两侧的分页链接数。宽度为 `1` 将在需要截断列表时输出当前页面两侧的一个链接。当前、第一个和最后一个页面的链接始终会显示，并且是在此值之外的链接。|
|
||||
|`sitemap.excludedKinds`|`["taxonomy", "term"]`|应从生成的 `/sitemap.xml` 文件中排除的内容类型。有关可接受的值，请参阅[Hugo 文档](https://gohugo.io/templates/section-templates/#page-kinds)。|
|
||||
|`taxonomy.showTermCount`|`true`|是否在分类法列表上显示分类术语内文章的数量。|
|
||||
|`fathomAnalytics.site`|_未设置_|由 Fathom Analytics 为网站生成的站点代码。有关详细信息，请参阅[分析文档]({{< ref "partials#analytics" >}})。|
|
||||
|`fathomAnalytics.domain`|_未设置_|如果在 Fathom Analytics 中使用自定义域，请在此提供以从自定义域提供 `script.js`。|
|
||||
|`plausibleAnalytics.domain`|_未设置_|输入要跟踪的网站的域。有关详细信息，请参阅[分析文档]({{< ref "partials#analytics" >}})。|
|
||||
|`plausibleAnalytics.event`|_未设置_|可寻址 Plausible api 事件的 URL。有关详细信息，请参阅[分析文档]({{< ref "partials#analytics" >}})。|
|
||||
|`plausibleAnalytics.script`|_未设置_|可寻址 Plausible 分析脚本的 URL。有关详细信息，请参阅[分析文档]({{< ref "partials#analytics" >}})。|
|
||||
|`verification.google`|_未设置_|由 Google 提供的要包含在站点元数据中的站点验证字符串。|
|
||||
|`verification.bing`|_未设置_|由 Bing 提供的要包含在站点元数据中的站点验证字符串。|
|
||||
|`verification.pinterest`|_未设置_|由 Pinterest 提供的要包含在站点元数据中的站点验证字符串。|
|
||||
|`verification.yandex`|_未设置_|由 Yandex 提供的要包含在站点元数据中的站点验证字符串。|
|
||||
|
||||
## 其他配置文件
|
||||
|
||||
主题还包括一个 `markup.toml` 配置文件。该文件包含一些重要的参数，确保 Hugo 正确配置以生成使用 Congo 构建的站点。
|
||||
|
||||
始终确保此文件存在于配置目录中，并设置所需的值。否则，可能导致某些功能不正确地运行，并可能导致意外的行为。
|
||||
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 14 KiB |
@@ -0,0 +1,317 @@
|
||||
---
|
||||
title: "コンテンツの例"
|
||||
date: 2020-08-09
|
||||
draft: false
|
||||
description: "コンテンツがどのように作成され、構成されるべきかを示すいくつかの例"
|
||||
summary: "コンテンツがどのように構成されるべきかを示すいくつかの例です。"
|
||||
slug: "content-examples"
|
||||
tags: ["content", "example"]
|
||||
---
|
||||
|
||||
ドキュメントを順番に読んできたのなら、Congoで利用可能な機能と設定についてはすべて知っているはずです。このページでは、それらをまとめて、あなたがHugoプロジェクトで使いたくなるような例をいくつか紹介します。
|
||||
|
||||
{{< alert >}}
|
||||
**ヒント:** もしあなたがHugoに慣れていないのであれば、[Hugo docs](https://gohugo.io/content-management/page-bundles/)をチェックし、ページバンドルとリソースの概念について学んでください。
|
||||
{{< /alert >}}
|
||||
|
||||
このページで紹介する例はさまざまなシナリオに適用できますが、個々のプロジェクトで特定のコンテンツ項目をフォーマットする方法について、いくつかのアイデアが得られることを願っています。
|
||||
|
||||
## ブランチページ
|
||||
|
||||
Hugoのブランチページバンドルは、ホームページ、セクションリスト、Taxonomyページのような項目をカバーしています。ブランチバンドルについて覚えておくべき重要なことは、このコンテンツタイプのファイル名は **`_index.md`** であるということです。
|
||||
|
||||
Congoはブランチページで指定されたフロントマターを尊重し、デフォルト設定を上書きします。例えば、ブランチページで `title` パラメーターを設定すると、ページタイトルを上書きすることができます。
|
||||
|
||||
### ホームページ
|
||||
|
||||
| | |
|
||||
| ------------ | -------------------- |
|
||||
| **Layout:** | `layouts/index.html` |
|
||||
| **Content:** | `content/_index.md` |
|
||||
|
||||
Congoのホームページは、ホームページレイアウト設定パラメーターによって包括的なデザインが制御されるという点で特別です。これについては[ホームページレイアウト]({{< ref "homepage-layout" >}})セクションで詳しく説明しています。
|
||||
|
||||
このページにカスタムコンテンツを追加したい場合は、 `content/_index.md` ファイルを作成するだけです。このファイルにあるものはすべてホームページに含まれます。
|
||||
|
||||
**例:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Congoへようこそ！"
|
||||
description: "これはホームページにコンテンツを追加するデモです"
|
||||
---
|
||||
私のウェブサイトへようこそ！立ち寄ってくれて本当に嬉しいです。
|
||||
```
|
||||
|
||||
_この例では、カスタムタイトルを設定し、ページ本文にいくつかの追加テキストを追加します。ショートコード、画像、リンクを含め、どのようなMarkdownフォーマットのテキストでも構いません。_
|
||||
|
||||
### リストページ
|
||||
|
||||
| | |
|
||||
| ------------ | ---------------------------- |
|
||||
| **Layout:** | `layouts/_default/list.html` |
|
||||
| **Content:** | `content/../_index.md` |
|
||||
|
||||
リストページは、セクション内のすべてのページをグループ化し、訪問者が各ページに到達するための方法を提供します。ブログやポートフォリオは、記事やプロジェクトをグループ化したリストページの例です。
|
||||
|
||||
リストページの作成は、 `content` 内にサブディレクトリを作成するのと同じくらい簡単です。例えば、"Projects"セクションを作成するには、 `content/projects/` を作成します。そして、プロジェクトごとにMarkdownファイルを作成します。
|
||||
|
||||
デフォルトではリストページが生成されますが、コンテンツをカスタマイズするために、この新しいディレクトリに`_index.md`ページも作成してください。
|
||||
|
||||
```shell
|
||||
.
|
||||
└── content
|
||||
└── projects
|
||||
├── _index.md # /projects
|
||||
├── first-project.md # /projects/first-project
|
||||
└── another-project
|
||||
├── index.md # /projects/another-project
|
||||
└── project.jpg
|
||||
```
|
||||
|
||||
Hugoは、 `content/projects` 内のページのURLを適宜生成します。
|
||||
|
||||
ホームページと同じように、 `_index.md` ファイルのコンテンツは生成されたリストインデックスに出力されます。Congoはこのセクションのすべてのページをリストします。
|
||||
|
||||
**例:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Projects"
|
||||
description: "私のプロジェクトについて"
|
||||
cascade:
|
||||
showReadingTime: false
|
||||
---
|
||||
このセクションには、私が現在取り組んでいるすべてのプロジェクトが含まれています。
|
||||
```
|
||||
|
||||
_この例では、特別な `cascade` パラメーターを使って、このセクション内のサブページの読書時間を非表示にしています。こうすることで、どのプロジェクトページでも読書時間が表示されなくなります。これは、個々のページにデフォルトのテーマパラメーターを含めなくても、セクション全体のデフォルトのテーマパラメーターを上書きすることができる素晴らしい方法です。_
|
||||
|
||||
このサイトの[サンプル]({{< ref "samples" >}})はリストページの一例です。
|
||||
|
||||
### Taxonomyページ
|
||||
|
||||
| | |
|
||||
| ---------------- | -------------------------------- |
|
||||
| **List layout:** | `layouts/_default/taxonomy.html` |
|
||||
| **Term layout:** | `layouts/_default/term.html` |
|
||||
| **Content:** | `content/../_index.md` |
|
||||
|
||||
Taxonomyページには、TaxonomyのリストとTaxonomyのTermという2つの形式があります。リストはTaxonomy内の各Termのリストを表示し、Termは指定されたTermに関連するページのリストを表示します。
|
||||
|
||||
Termは少し混乱しやすいので、`animals` というTaxonomyを使って例を探ってみましょう。
|
||||
|
||||
まず、HugoでTaxonomyを使うには設定が必要です。 `config/_default/taxonomies.toml` に設定ファイルを作成し、Taxonomyの名前を定義します。
|
||||
|
||||
```toml
|
||||
# config/_default/taxonomies.toml
|
||||
|
||||
animal = "animals"
|
||||
```
|
||||
|
||||
HugoはTaxonomyを単数形と複数形でリストすることを想定しているので、単数形の `animal` と複数形の `animals` を追加して、例のTaxonomyを作成します。
|
||||
|
||||
これで `animals` Taxonomyが存在することになったので、個々のコンテンツに追加する必要があります。フロントマターに挿入するだけです:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "ライオンの巣へ"
|
||||
description: "今週はライオンについて学びます"
|
||||
animals: ["lion", "cat"]
|
||||
---
|
||||
```
|
||||
|
||||
これで `animals` Taxonomyの中に `lion` と `cat` というTermができたことになります。
|
||||
|
||||
この時点では明らかではありませんが、Hugoはこの新しいTaxonomyリストとTermのページを生成します。デフォルトでは、リストは `/animals/` に、Termページは `/animals/lion/` と `/animals/cat/` になります。
|
||||
|
||||
リストページはTaxonomyに含まれるすべてのTermをリストアップします。この例では、 `/animals/` に移動すると、 `lion` と `cat` のリンクがあるページが表示され、訪問者はそれぞれのTermページに移動できます。
|
||||
|
||||
TermページはそのTermが含まれるすべてのページをリストアップします。これらのTermリストは基本的に通常の[リストページ](#リストページ)とほとんど同じように動作します。
|
||||
|
||||
Taxonomyページにカスタムコンテンツを追加するには、Taxonomy名をサブディレクトリとして、 `content` 内に `_index.md` ファイルを作成するだけです。
|
||||
|
||||
```shell
|
||||
.
|
||||
└── content
|
||||
└── animals
|
||||
├── _index.md # /animals
|
||||
└── lion
|
||||
└── _index.md # /animals/lion
|
||||
```
|
||||
|
||||
これらのコンテンツファイルにあるものは生成されたTaxonomyページに配置されます。他のコンテンツと同じように、フロントマターはデフォルトを上書きするために使うことができます。このように、 `lion` という名前のタグがあっても、 `title` を"Lion"に上書きすることができます。
|
||||
|
||||
これが実際にどのように見えるかは、このサイトの[Tags]({{< ref "tags" >}})をチェックしてください。
|
||||
|
||||
## リーフページ
|
||||
|
||||
| | |
|
||||
| ------------------------- | ------------------------------- |
|
||||
| **Layout:** | `layouts/_default/single.html` |
|
||||
| **Content (standalone):** | `content/../page-name.md` |
|
||||
| **Content (bundled):** | `content/../page-name/index.md` |
|
||||
|
||||
Hugoのリーフページは基本的に標準的なコンテンツページです。サブページを含まないページとして定義されます。例えば、アバウトページや、ウェブサイトのブログセクションにある個々のブログ記事などです。
|
||||
|
||||
リーフページについて覚えておくべき最も重要なことは、ブランチページとは異なり、リーフページはアンダースコアなしで `index.md` と名前をつけるべきということです。リーフページはまた、セクションのトップレベルにまとめて一意な名前をつけることができるという点で特別です。
|
||||
|
||||
```shell
|
||||
.
|
||||
└── content
|
||||
└── blog
|
||||
├── first-post.md # /blog/first-post
|
||||
├── second-post.md # /blog/second-post
|
||||
└── third-post
|
||||
├── index.md # /blog/third-post
|
||||
└── image.jpg
|
||||
```
|
||||
|
||||
画像などをページに含める場合、ページバンドルを使用する必要があります。ページバンドルは `index.md` ファイルを含むサブディレクトリを使って作成します。ショートコードやその他のテーマロジックの多くは、リソースがページと一緒にバンドルされていることを前提としているので、コンテンツと一緒に独自のディレクトリにグループ化することが重要です。
|
||||
|
||||
**例:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "初めてのブログ投稿"
|
||||
date: 2022-01-25
|
||||
description: "私のブログへようこそ！"
|
||||
summary: "私について、そして私がなぜこのブログを始めたのか、もっと知ってください。"
|
||||
tags: ["welcome", "new", "about", "first"]
|
||||
---
|
||||
_これ_ が私のブログ記事の内容です。
|
||||
```
|
||||
|
||||
リーフページには様々な[フロントマター]({{< ref "front-matter" >}})パラメーターがあり、それらを使って表示方法をカスタマイズすることができます。
|
||||
|
||||
### 外部リンク
|
||||
|
||||
Congoには、外部ページへのリンクを記事リストに表示できる特別な機能があります。これは、Mediumのようなサードパーティのウェブサイトや研究論文にコンテンツがあり、Hugoのサイトにコンテンツを複製することなくリンクを張りたい場合に便利です。
|
||||
|
||||
外部リンク記事を作成するには、特別なフロントマターを設定する必要があります:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "私のMediumの記事"
|
||||
date: 2022-01-25
|
||||
externalUrl: "https://medium.com/"
|
||||
summary: "私はMediumに記事を書きました。"
|
||||
showReadingTime: false
|
||||
_build:
|
||||
render: "false"
|
||||
list: "local"
|
||||
---
|
||||
```
|
||||
|
||||
`title` や `summary` のような通常のフロントマターパラメーターとともに、 `externalUrl` パラメーターはこの記事が普通の記事ではないことを伝えるために使われます。ここで指定されたURLは、訪問者がこの記事を選択したときに誘導される場所になります。
|
||||
|
||||
さらに、このコンテンツの通常のページが生成されないように（外部URLにリンクしているので、ページを生成する意味がありません！）、Hugoの特別なフロントマターパラメーターである `_build` を使用しています。
|
||||
|
||||
テーマには、このような外部リンク記事を簡単に生成するためのアーキタイプが含まれています。新しいコンテンツを作るときに `-k external` を指定するだけです。
|
||||
|
||||
```shell
|
||||
hugo new -k external posts/my-post.md
|
||||
```
|
||||
|
||||
### シンプルページ
|
||||
|
||||
| | |
|
||||
| ----------------- | ------------------------------ |
|
||||
| **Layout:** | `layouts/_default/simple.html` |
|
||||
| **Front Matter:** | `layout: "simple"` |
|
||||
|
||||
Congoにはシンプルなページのための特別なレイアウトも含まれています。シンプル・レイアウトは全幅のテンプレートで、特別なテーマ機能なしにMarkdownコンテンツをページに配置するだけです。
|
||||
|
||||
シンプルレイアウトで利用できる唯一の機能はパンくずリストと共有リンクです。これらの動作は通常のページと同様に[フロントマター]({{< ref "front-matter" >}})パラメーターを使って制御することができます。
|
||||
|
||||
特定のページでシンプルレイアウトを有効にするには、 `layout` フロントマター変数に `"simple"` という値を追加します:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "ランディングページ"
|
||||
date: 2022-03-08
|
||||
layout: "simple"
|
||||
---
|
||||
このページのコンテンツは全幅になりました。
|
||||
```
|
||||
|
||||
## カスタムレイアウト
|
||||
|
||||
Hugoの利点のひとつは、サイト全体や個々のセクション、ページのカスタムレイアウトを簡単に作成できることです。
|
||||
|
||||
レイアウトは通常のHugoのテンプレート規則に従います。詳細は[Hugo公式ドキュメント](https://gohugo.io/templates/introduction/)をご覧ください。
|
||||
|
||||
### デフォルトレイアウトのオーバーライド
|
||||
|
||||
上で説明した各コンテンツタイプには、各タイプのページを生成するために使用されるレイアウトファイルが記載されています。このファイルをローカルプロジェクトに作成すると、テーマテンプレートを上書きするので、ウェブサイトのデフォルトスタイルをカスタマイズするために使用することができます。
|
||||
|
||||
例えば、 `layouts/_default/single.html` ファイルを作成すれば、リーフページのレイアウトを完全にカスタマイズすることができます。
|
||||
|
||||
### カスタムセクションレイアウト
|
||||
|
||||
また、個々のコンテンツセクションのカスタムレイアウトを作成するのも簡単です。これは、特定のコンテンツを特定のスタイルで一覧表示するセクションを作りたい場合に便利です。
|
||||
|
||||
特殊なレイアウトでプロジェクトを一覧表示するカスタム「Projects」ページを作成する例を見てみましょう。
|
||||
|
||||
これを行うには、通常のHugoコンテンツルールを使用してコンテンツを構成し、プロジェクト用のセクションを作成します。さらに、コンテンツと同じディレクトリ名を使い、 `list.html` ファイルを追加して、プロジェクトセクション用の新しいレイアウトを作成します。
|
||||
|
||||
```shell
|
||||
.
|
||||
└── content
|
||||
│ └── projects
|
||||
│ ├── _index.md
|
||||
│ ├── first-project.md
|
||||
│ └── second-project.md
|
||||
└── layouts
|
||||
└── projects
|
||||
└── list.html
|
||||
```
|
||||
|
||||
この `list.html` ファイルはデフォルトのリストテンプレートをオーバーライドします。このファイルを見る前に、まず個々のプロジェクトファイルを見てみましょう。
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Congo"
|
||||
date: 2021-08-11
|
||||
icon: "github"
|
||||
description: "Tailwind CSSで作られたHugoのテーマ"
|
||||
topics: ["Hugo", "Web", "Tailwind"]
|
||||
externalUrl: "https://github.com/jpanther/congo/"
|
||||
---
|
||||
```
|
||||
|
||||
_この例では、各プロジェクトにメタデータを割り当て、リストテンプレートで使用できるようにしています。ページのコンテンツはありませんが、それを含めることを妨げるものも何もありません。あなたのカスタムテンプレートなのですから！_
|
||||
|
||||
プロジェクトが定義されたので、各プロジェクトの詳細を出力するリストテンプレートを作成することができます。
|
||||
|
||||
```go
|
||||
{{ define "main" }}
|
||||
<section class="mt-8">
|
||||
{{ range .Pages }}
|
||||
<article class="pb-6">
|
||||
<a class="flex" href="{{ .Params.externalUrl }}">
|
||||
<div class="mr-3 text-3xl text-neutral-300">
|
||||
<span class="relative inline-block align-text-bottom">
|
||||
{{ partial "icon.html" .Params.icon }}
|
||||
</span>
|
||||
</div>
|
||||
<div>
|
||||
<h3 class="flex text-xl font-semibold">
|
||||
{{ .Title }}
|
||||
</h3>
|
||||
<p class="text-sm text-neutral-400">
|
||||
{{ .Description }}
|
||||
</p>
|
||||
</div>
|
||||
</a>
|
||||
</article>
|
||||
{{ end }}
|
||||
</section>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
これは非常にわかりやすい例ですが、このセクションの各ページ（つまり各プロジェクト）を順に見ていき、各プロジェクトへのHTMLリンクをアイコンと一緒に出力していることがわかります。各プロジェクトのフロントマターのメタデータは、どの情報を表示するかを決定するために使われます。
|
||||
|
||||
関連するスタイルとクラスが利用可能であることを確認する必要があり、Tailwind CSSを再コンパイルする必要があるかもしれないことを覚えておいてください。これについては、[高度なカスタマイズ]({{< ref "advanced-customisation" >}})セクションで詳しく説明します。
|
||||
|
||||
このようなカスタムテンプレートを作成する場合、デフォルトのCongoテンプレートがどのように動作するかを見て、それをガイドとして使用するのが最も簡単です。[Hugo docs](https://gohugo.io/templates/introduction/)はテンプレートの作成についてもっと学ぶための素晴らしいリソースです。
|
||||
@@ -0,0 +1,317 @@
|
||||
---
|
||||
title: "Content Examples"
|
||||
date: 2020-08-09
|
||||
draft: false
|
||||
description: "Some examples that demonstrate how content should be created and structured."
|
||||
summary: "It's time to bring everything together with some examples that demonstrate how content should be created and structured."
|
||||
slug: "content-examples"
|
||||
tags: ["content", "example"]
|
||||
---
|
||||
|
||||
If you've been reading the documentation in order, you should now know about all the features and configurations available in Congo. This page is designed to pull everything together and offer some worked examples that you might like to use in your Hugo project.
|
||||
|
||||
{{< alert >}}
|
||||
**Tip:** If you're new to Hugo, be sure to check out the [official docs](https://gohugo.io/content-management/page-bundles/) to learn more about the concept of page bundles and resources.
|
||||
{{< /alert >}}
|
||||
|
||||
The examples on this page can all be adapted to different scenarios but hopefully give you some ideas about how to approach formatting a particular content item for your individual project.
|
||||
|
||||
## Branch pages
|
||||
|
||||
Branch page bundles in Hugo cover items like the homepage, section listings, and taxonomy pages. The important thing to remember about branch bundles is that the filename for this content type is **`_index.md`**.
|
||||
|
||||
Congo will honour the front matter parameters specified in branch pages and these will override the default settings for that particular page. For example, setting the `title` parameter in a branch page will allow overriding the page title.
|
||||
|
||||
### Homepage
|
||||
|
||||
| | |
|
||||
| ------------ | -------------------- |
|
||||
| **Layout:** | `layouts/index.html` |
|
||||
| **Content:** | `content/_index.md` |
|
||||
|
||||
The homepage in Congo is special in that it's overarching design is controlled by the homepage layout config parameter. You can learn more about this in the [Homepage Layout]({{< ref "homepage-layout" >}}) section.
|
||||
|
||||
If you want to add custom content to this page, you simply need to create a `content/_index.md` file. Anything in this file will then be included in your homepage.
|
||||
|
||||
**Example:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Welcome to Congo!"
|
||||
description: "This is a demo of adding content to the homepage."
|
||||
---
|
||||
Welcome to my website! I'm really happy you stopped by.
|
||||
```
|
||||
|
||||
_This example sets a custom title and adds some additional text to the body of the page. Any Markdown formatted text is acceptable, including shortcodes, images and links._
|
||||
|
||||
### List pages
|
||||
|
||||
| | |
|
||||
| ------------ | ---------------------------- |
|
||||
| **Layout:** | `layouts/_default/list.html` |
|
||||
| **Content:** | `content/../_index.md` |
|
||||
|
||||
List pages group all the pages within into a section and provide a way for visitors to reach each page. A blog or portfolio are examples of a list page as they group together posts or projects.
|
||||
|
||||
Creating a list page is as simple as making a sub-directory in the content folder. For example, to create a "Projects" section, you would create `content/projects/`. Then create a Markdown file for each of your projects.
|
||||
|
||||
A list page will be generated by default, however to customise the content, you should also create an `_index.md` page in this new directory.
|
||||
|
||||
```shell
|
||||
.
|
||||
└── content
|
||||
└── projects
|
||||
├── _index.md # /projects
|
||||
├── first-project.md # /projects/first-project
|
||||
└── another-project
|
||||
├── index.md # /projects/another-project
|
||||
└── project.jpg
|
||||
```
|
||||
|
||||
Hugo will generate URLs for the pages in your projects folder accordingly.
|
||||
|
||||
Just like the homepage, content in the `_index.md` file will be output into the generated list index. Congo will then list any pages in this section below the content.
|
||||
|
||||
**Example:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Projects"
|
||||
description: "Learn about some of my projects."
|
||||
cascade:
|
||||
showReadingTime: false
|
||||
---
|
||||
This section contains all my current projects.
|
||||
```
|
||||
|
||||
_In this example, the special `cascade` parameter is being used to hide the reading time on any sub-pages within this section. By doing this, any project pages will not have their reading time showing. This is a great way to override default theme parameters for an entire section without having to include them in every individual page._
|
||||
|
||||
The [samples section]({{< ref "samples" >}}) of this site is an example of a list page.
|
||||
|
||||
### Taxonomy pages
|
||||
|
||||
| | |
|
||||
| ---------------- | -------------------------------- |
|
||||
| **List layout:** | `layouts/_default/taxonomy.html` |
|
||||
| **Term layout:** | `layouts/_default/term.html` |
|
||||
| **Content:** | `content/../_index.md` |
|
||||
|
||||
Taxonomy pages come in two forms - taxonomy lists and taxonomy terms. Lists display a listing of each of the terms within a given taxonomy, while terms display a list of pages that are related to a given term.
|
||||
|
||||
The terminology can get a little confusing so let's explore an example using a taxonomy named `animals`.
|
||||
|
||||
Firstly, to use taxonomies in Hugo, they have to be configured. This is done by creating a config file at `config/_default/taxonomies.toml` and defining the taxonomy name.
|
||||
|
||||
```toml
|
||||
# config/_default/taxonomies.toml
|
||||
|
||||
animal = "animals"
|
||||
```
|
||||
|
||||
Hugo expects taxonomies to be listed using their singular and plural forms, so we add the singular `animal` equals the plural `animals` to create our example taxonomy.
|
||||
|
||||
Now that our `animals` taxonomy exists, it needs to be added to individual content items. It's as simple as inserting it into the front matter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Into the Lion's Den"
|
||||
description: "This week we're learning about lions."
|
||||
animals: ["lion", "cat"]
|
||||
---
|
||||
```
|
||||
|
||||
This has now created two _terms_ within our `animals` taxonomy - `lion` and `cat`.
|
||||
|
||||
Although it's not obvious at this point, Hugo will now be generating list and term pages for this new taxonomy. By default the listing can be accessed at `/animals/` and the term pages can be found at `/animals/lion/` and `/animals/cat/`.
|
||||
|
||||
The list page will list all the terms contained within the taxonomy. In this example, navigating to `/animals/` will show a page that has links for "lion" and "cat" which take visitors to the individual term pages.
|
||||
|
||||
The term pages will list all the pages contained within that term. These term lists are essentially the same as normal [list pages](#list-pages) and behave in much the same way.
|
||||
|
||||
In order to add custom content to taxonomy pages, simply create `_index.md` files in the content folder using the taxonomy name as the sub-directory name.
|
||||
|
||||
```shell
|
||||
.
|
||||
└── content
|
||||
└── animals
|
||||
├── _index.md # /animals
|
||||
└── lion
|
||||
└── _index.md # /animals/lion
|
||||
```
|
||||
|
||||
Anything in these content files will now be placed onto the generated taxonomy pages. As with other content, the front matter variables can be used to override defaults. In this way you could have a tag named `lion` but override the `title` to be "Lion".
|
||||
|
||||
To see how this looks in reality, check out the [tags taxonomy listing]({{< ref "tags" >}}) on this site.
|
||||
|
||||
## Leaf pages
|
||||
|
||||
| | |
|
||||
| ------------------------- | ------------------------------- |
|
||||
| **Layout:** | `layouts/_default/single.html` |
|
||||
| **Content (standalone):** | `content/../page-name.md` |
|
||||
| **Content (bundled):** | `content/../page-name/index.md` |
|
||||
|
||||
Leaf pages in Hugo are basically standard content pages. They are defined as pages that don't contain any sub-pages. These could be things like an about page, or an individual blog post that lives in the blog section of the website.
|
||||
|
||||
The most important thing to remember about leaf pages is that unlike branch pages, leaf pages should be named `index.md` _without_ an underscore. Leaf pages are also special in that they can be grouped together at the top level of the section and named with a unique name.
|
||||
|
||||
```shell
|
||||
.
|
||||
└── content
|
||||
└── blog
|
||||
├── first-post.md # /blog/first-post
|
||||
├── second-post.md # /blog/second-post
|
||||
└── third-post
|
||||
├── index.md # /blog/third-post
|
||||
└── image.jpg
|
||||
```
|
||||
|
||||
When including assets in a page, like an image, a page bundle should be used. Page bundles are created using a sub-directory with an `index.md` file. Grouping the assets with the content in its own directory is important as many of the shortcodes and other theme logic assumes that resources are bundled alongside pages.
|
||||
|
||||
**Example:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "My First Blog Post"
|
||||
date: 2022-01-25
|
||||
description: "Welcome to my blog!"
|
||||
summary: "Learn more about me and why I am starting this blog."
|
||||
tags: ["welcome", "new", "about", "first"]
|
||||
---
|
||||
_This_ is the content of my blog post.
|
||||
```
|
||||
|
||||
Leaf pages have a wide variety of [front matter]({{< ref "front-matter" >}}) parameters that can be used to customise how they are displayed.
|
||||
|
||||
### External links
|
||||
|
||||
Congo has a special feature that allows links to external pages to appear alongside articles in the article listings. This is useful if you have content on third party websites like Medium, or research papers that you'd like to link to, without replicating the content in your Hugo site.
|
||||
|
||||
In order to create an external link article, some special front matter needs to be set:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "My Medium post"
|
||||
date: 2022-01-25
|
||||
externalUrl: "https://medium.com/"
|
||||
summary: "I wrote a post on Medium."
|
||||
showReadingTime: false
|
||||
_build:
|
||||
render: "false"
|
||||
list: "local"
|
||||
---
|
||||
```
|
||||
|
||||
Along with the normal front matter parameters like `title` and `summary`, the `externalUrl` parameter is used to tell Congo that this is not an ordinary article. The URL provided here will be where visitors are directed when they select this article.
|
||||
|
||||
Additionally, we use a special Hugo front matter parameter `_build` to prevent a normal page for this content being generated - there's no point generating a page since we're linking to an external URL!
|
||||
|
||||
The theme includes an archetype to make generating these external link articles simple. Just specify `-k external` when making new content.
|
||||
|
||||
```shell
|
||||
hugo new -k external posts/my-post.md
|
||||
```
|
||||
|
||||
### Simple pages
|
||||
|
||||
| | |
|
||||
| ----------------- | ------------------------------ |
|
||||
| **Layout:** | `layouts/_default/simple.html` |
|
||||
| **Front Matter:** | `layout: "simple"` |
|
||||
|
||||
Congo also includes a special layout for simple pages. The simple layout is a full-width template that just places Markdown content into the page without any special theme features.
|
||||
|
||||
The only features available in the simple layout are breadcrumbs and sharing links. However, the behaviour of these can still be controlled using the normal page [front matter]({{< ref "front-matter" >}}) variables.
|
||||
|
||||
To enable the simple layout on a particular page, add the `layout` front matter variable with a value of `"simple"`:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "My landing page"
|
||||
date: 2022-03-08
|
||||
layout: "simple"
|
||||
---
|
||||
This page content is now full-width.
|
||||
```
|
||||
|
||||
## Custom layouts
|
||||
|
||||
One of the benefits of Hugo is that it makes it easy to create custom layouts for the whole site, individual sections or pages.
|
||||
|
||||
Layouts follow all the normal Hugo templating rules and more information is available in the [official Hugo docs](https://gohugo.io/templates/introduction/).
|
||||
|
||||
### Overriding default layouts
|
||||
|
||||
Each of the content types discussed above lists the layout file that is used to generate each type of page. If this file is created in your local project it will override the theme template and thus can be used to customise the default style of the website.
|
||||
|
||||
For example, creating a `layouts/_default/single.html` file will allow the layout of leaf pages to be completely customised.
|
||||
|
||||
### Custom section layouts
|
||||
|
||||
It is also simple to create custom layouts for individual content sections. This is useful when you want to make a section that lists a certain type of content using a particular style.
|
||||
|
||||
Let's step through an example that creates a custom "Projects" page that lists projects using a special layout.
|
||||
|
||||
In order to do this, structure your content using the normal Hugo content rules and create a section for your projects. Additionally, create a new layout for the projects section by using the same directory name as the content and adding a `list.html` file.
|
||||
|
||||
```shell
|
||||
.
|
||||
└── content
|
||||
│ └── projects
|
||||
│ ├── _index.md
|
||||
│ ├── first-project.md
|
||||
│ └── second-project.md
|
||||
└── layouts
|
||||
└── projects
|
||||
└── list.html
|
||||
```
|
||||
|
||||
This `list.html` file will now override the default list template, but only for the `projects` section. Before we look at this file, lets first look at the individual project files.
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Congo"
|
||||
date: 2021-08-11
|
||||
icon: "github"
|
||||
description: "A theme for Hugo built with Tailwind CSS."
|
||||
topics: ["Hugo", "Web", "Tailwind"]
|
||||
externalUrl: "https://github.com/jpanther/congo/"
|
||||
---
|
||||
```
|
||||
|
||||
_In this example we are assigning some metadata for each project that we can then use in our list template. There's no page content, but there's nothing stopping you from including it. It's your own custom template after all!_
|
||||
|
||||
With the projects defined, now we can create a list template that outputs the details of each project.
|
||||
|
||||
```go
|
||||
{{ define "main" }}
|
||||
<section class="mt-8">
|
||||
{{ range .Pages }}
|
||||
<article class="pb-6">
|
||||
<a class="flex" href="{{ .Params.externalUrl }}">
|
||||
<div class="mr-3 text-3xl text-neutral-300">
|
||||
<span class="relative inline-block align-text-bottom">
|
||||
{{ partial "icon.html" .Params.icon }}
|
||||
</span>
|
||||
</div>
|
||||
<div>
|
||||
<h3 class="flex text-xl font-semibold">
|
||||
{{ .Title }}
|
||||
</h3>
|
||||
<p class="text-sm text-neutral-400">
|
||||
{{ .Description }}
|
||||
</p>
|
||||
</div>
|
||||
</a>
|
||||
</article>
|
||||
{{ end }}
|
||||
</section>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Although this is quite a straightforward example, you can see that it steps through each of the pages in this section (ie. each project), and then outputs HTML links to each project alongside an icon. The metadata in the front matter for each project is used to determine which information is displayed.
|
||||
|
||||
Keep in mind that you'll need to ensure the relevant styles and classes are available, which may require the Tailwind CSS to be recompiled. This is discussed in more detail in the [Advanced Customisation]({{< ref "advanced-customisation" >}}) section.
|
||||
|
||||
When making custom templates like this one, it's always easiest to take a look at how the default Congo template works and then use that as a guide. Remember, the [Hugo docs](https://gohugo.io/templates/introduction/) are a great resource to learn more about creating templates too.
|
||||
@@ -0,0 +1,316 @@
|
||||
---
|
||||
title: "内容示例"
|
||||
date: 2020-08-09
|
||||
draft: false
|
||||
description: "一些演示如何创建和组织内容的示例。"
|
||||
summary: "是时候通过一些演示示例将所有内容整合起来，展示如何创建和组织内容了。"
|
||||
slug: "content-examples"
|
||||
tags: ["content", "example"]
|
||||
---
|
||||
|
||||
如果你按顺序阅读文档，现在应该对 Congo 中提供的所有功能和配置有所了解。本页面旨在将所有内容整合在一起，并提供一些你可能想在 Hugo 项目中使用的实际示例。
|
||||
|
||||
{{< alert >}}
|
||||
**提示：** 如果你是 Hugo 新手，请务必查阅[官方文档](https://gohugo.io/content-management/page-bundles/)，了解有关page bundles和资源概念的更多信息。
|
||||
{{< /alert >}}
|
||||
|
||||
本页面的示例可以根据不同的情境进行调整，但希望能为你提供一些关于如何处理特定内容项格式的思路，以适应你个人项目的需要。
|
||||
|
||||
## 分支页面
|
||||
|
||||
在 Hugo 中，分支页面包括主页、部分列表和分类页面等。需要记住的一点是，此类内容的文件名是 **`_index.md`**。
|
||||
|
||||
Congo 将遵循分支页面中指定的 front matter 参数，这些参数将覆盖该特定页面的默认设置。例如，在分支页面中设置 `title` 参数将允许覆盖页面标题。
|
||||
|
||||
### 主页
|
||||
|
||||
| | |
|
||||
| ------------ | -------------------- |
|
||||
| **布局：** | `layouts/index.html` |
|
||||
| **内容：** | `content/_index.md` |
|
||||
|
||||
在 Congo 中，主页是特殊的，因为其总体设计由主页布局配置参数控制。你可以在 [主页布局]({{< ref "homepage-layout" >}}) 部分了解更多信息。
|
||||
|
||||
如果你想在这个页面上添加自定义内容，只需创建一个 `content/_index.md` 文件。然后，此文件中的任何内容都将包含在你的主页中。
|
||||
|
||||
**示例:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "欢迎来到 Congo！"
|
||||
description: "这是向主页添加内容的演示。"
|
||||
---
|
||||
欢迎来到我的网站！我真的很高兴你停留在这里。
|
||||
```
|
||||
|
||||
_此示例设置了自定义标题，并在页面正文中添加了一些额外的文本。任何 Markdown 格式的文本都是可以接受的，包括短代码、图片和链接。_
|
||||
|
||||
### 列表页面
|
||||
|
||||
| | |
|
||||
| ------------ | ---------------------------- |
|
||||
| **布局：** | `layouts/_default/list.html` |
|
||||
| **内容：** | `content/../_index.md` |
|
||||
|
||||
列表页面将其内部的所有页面分组到一个部分，并提供一种让访问者访问每个页面的方式。博客或投影集是列表页面的示例，因为它们将帖子或项目分组在一起。
|
||||
|
||||
创建列表页面就像在 content 文件夹中创建一个子目录一样简单。例如，要创建一个 "Projects" 部分，你将创建 `content/projects/`。然后为你的每个项目创建一个 Markdown 文件。
|
||||
|
||||
列表页面将默认生成，但为了自定义内容，你还应该在这个新目录中创建一个 `_index.md` 页面。
|
||||
|
||||
```shell
|
||||
.
|
||||
└── content
|
||||
└── projects
|
||||
├── _index.md # /projects
|
||||
├── first-project.md # /projects/first-project
|
||||
└── another-project
|
||||
├── index.md # /projects/another-project
|
||||
└── project.jpg
|
||||
```
|
||||
|
||||
Hugo 将相应地为项目文件夹中的页面生成 URL。
|
||||
|
||||
就像主页一样，`_index.md` 文件中的内容将输出到生成的列表索引中。Congo 然后会在内容下方列出此部分中的任何页面。
|
||||
|
||||
**示例:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "项目"
|
||||
description: "了解我的一些项目。"
|
||||
cascade:
|
||||
showReadingTime: false
|
||||
---
|
||||
这个部分包含所有我的当前项目。
|
||||
```
|
||||
|
||||
_在此示例中，使用了特殊的 `cascade` 参数来隐藏此部分中任何子页面上的阅读时间。通过这样做，任何项目页面将不显示其阅读时间。这是在整个部分中覆盖默认主题参数的好方法，而无需在每个单独页面中包含它们。_
|
||||
|
||||
此站点的 [样本部分]({{< ref "samples" >}}) 是列表页面的示例。
|
||||
|
||||
### 分类页面
|
||||
|
||||
| | |
|
||||
| ---------------- | -------------------------------- |
|
||||
| **列表布局:** | `layouts/_default/taxonomy.html` |
|
||||
| **术语布局:** | `layouts/_default/term.html` |
|
||||
| **内容:** | `content/../_index.md` |
|
||||
|
||||
分类页面有两种形式 - 分类列表和分类术语。列表显示给定分类中每个术语的列表，而术语显示与给定术语相关的页面列表。
|
||||
|
||||
术语可能会有点混淆，所以让我们通过一个使用名为 `animals` 的分类的示例来探讨一下。
|
||||
|
||||
首先，在 Hugo 中使用分类，必须进行配置。这是通过在 `config/_default/taxonomies.toml` 创建配置文件并定义分类名称来完成的。
|
||||
|
||||
```toml
|
||||
# config/_default/taxonomies.toml
|
||||
|
||||
animal = "animals"
|
||||
```
|
||||
|
||||
Hugo 期望以它们的单数和复数形式列出分类，因此我们添加了单数 `animal` 等于复数 `animals` 来创建我们的示例分类。
|
||||
|
||||
现在我们的 `animals` 分类存在了，它需要被添加到各个内容项中。只需将其插入到前置元数据中：
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Into the Lion's Den"
|
||||
description: "This week we're learning about lions."
|
||||
animals: ["lion", "cat"]
|
||||
---
|
||||
```
|
||||
|
||||
这样就在我们的 `animals` 分类中创建了两个 _术语_ - `lion` 和 `cat`。
|
||||
|
||||
虽然此时并不明显，但 Hugo 现在将为这个新的分类生成列表和术语页面。默认情况下，可以通过 `/animals/` 访问列表，而术语页面可以在 `/animals/lion/` 和 `/animals/cat/` 找到。
|
||||
|
||||
列表页面将列出分类中包含的所有术语。在这个例子中，导航到 `/animals/` 将显示一个页面，其中包含指向各个术语页面的链接，如 "lion" 和 "cat"。
|
||||
|
||||
术语页面将列出该术语中包含的所有页面。这些术语列表本质上与普通的 [列表页面](#list-pages) 相同，并以相似的方式运作。
|
||||
|
||||
要向分类页面添加自定义内容，只需在使用分类名称作为子目录名的内容文件夹中创建 `_index.md` 文件。
|
||||
|
||||
```shell
|
||||
.
|
||||
└── content
|
||||
└── animals
|
||||
├── _index.md # /animals
|
||||
└── lion
|
||||
└── _index.md # /animals/lion
|
||||
```
|
||||
|
||||
这些内容文件中的任何内容都将放置到生成的分类页面上。与其他内容一样，前置元数据变量可用于覆盖默认设置。通过这种方式，您可以拥有一个名为 `lion` 的标签，但可以覆盖 `title` 为 "Lion"。
|
||||
|
||||
要了解实际效果，请查看此站点上的 [标签分类列表]({{< ref "tags" >}})。
|
||||
|
||||
## 单页
|
||||
|
||||
| | |
|
||||
| ------------------------- | ------------------------------- |
|
||||
| **布局：** | `layouts/_default/single.html` |
|
||||
| **内容（独立）：** | `content/../page-name.md` |
|
||||
| **内容（打包）：** | `content/../page-name/index.md` |
|
||||
|
||||
Hugo 中的单页基本上是标准内容页面。它们被定义为不包含任何子页面的页面。这可能是关于页面，或者是博客部分中的单个博客文章。
|
||||
|
||||
关于单页的最重要的事情是，与分支页面不同，单页应该命名为 `index.md`，**没有**下划线。单页还很特殊，因为它们可以在部分的顶层进行分组，并以独特的名称命名。
|
||||
|
||||
```shell
|
||||
.
|
||||
└── content
|
||||
└── blog
|
||||
├── first-post.md # /blog/first-post
|
||||
├── second-post.md # /blog/second-post
|
||||
└── third-post
|
||||
├── index.md # /blog/third-post
|
||||
└── image.jpg
|
||||
```
|
||||
|
||||
在页面中包含资产，比如图片，应该使用页面包。页面包使用带有 `index.md` 文件的子目录创建。将资产与内容一起分组到自己的目录中是重要的，因为许多 shortcodes 和其他主题逻辑假定资源与页面一起打包。
|
||||
|
||||
**示例:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "我的第一篇博客文章"
|
||||
date: 2022-01-25
|
||||
description: "欢迎来到我的博客！"
|
||||
summary: "了解更多关于我以及我为什么开始写这个博客的信息。"
|
||||
tags: ["欢迎", "新", "关于", "第一篇"]
|
||||
---
|
||||
_这_ 是我的博客文章的内容。
|
||||
```
|
||||
|
||||
单页有各种可以用于自定义显示方式的 [前置元数据]({{< ref "front-matter" >}}) 参数。
|
||||
|
||||
### 外部链接
|
||||
|
||||
Congo 具有一个特殊功能，允许外部页面的链接出现在文章列表中。如果您在第三方网站（如 Medium）上有内容，或者有研究论文希望链接，而不想在 Hugo 站点中复制内容，这将非常有用。
|
||||
|
||||
要创建外部链接文章，需要设置一些特殊的前置元数据：
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "我的 Medium 文章"
|
||||
date: 2022-01-25
|
||||
externalUrl: "https://medium.com/"
|
||||
summary: "我在 Medium 上写了一篇文章。"
|
||||
showReadingTime: false
|
||||
_build:
|
||||
render: "false"
|
||||
list: "local"
|
||||
---
|
||||
```
|
||||
|
||||
除了正常的前置元数据参数如 `title` 和 `summary` 外，`externalUrl` 参数用于告诉 Congo 这不是一篇普通文章。此处提供的 URL 将是访问者选择该文章时的目标链接。
|
||||
|
||||
此外，我们使用了一个特殊的 Hugo 前置元数据参数 `_build` 来阻止生成此内容的正常页面 - 因为我们正在链接到外部 URL，生成正常页面没有意义！
|
||||
|
||||
主题包含一个原型，使生成这些外部链接文章变得简单。只需在创建新内容时指定 `-k external`。
|
||||
|
||||
```shell
|
||||
hugo new -k external posts/my-post.md
|
||||
```
|
||||
|
||||
### 简单页面
|
||||
|
||||
| | |
|
||||
| ----------------- | ------------------------------ |
|
||||
| **Layout:** | `layouts/_default/simple.html` |
|
||||
| **Front Matter:** | `layout: "simple"` |
|
||||
|
||||
Congo 还包括一个专门用于简单页面的特殊布局。简单布局是一个全宽度的模板，只需将 Markdown 内容放入页面，而不包含任何特殊的主题功能。
|
||||
|
||||
简单布局中唯一可用的功能是面包屑和分享链接。但是，这些的行为仍然可以通过使用正常页面 [前置元数据]({{< ref "front-matter" >}}) 变量进行控制。
|
||||
|
||||
要在特定页面上启用简单布局，请添加 `layout` 前置元数据变量，其值为 `"simple"`：
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "我的落地页"
|
||||
date: 2022-03-08
|
||||
layout: "simple"
|
||||
---
|
||||
此页面内容现在是全宽度的。
|
||||
|
||||
## 自定义布局
|
||||
|
||||
Hugo 的一个好处是它使得为整个站点、单独的部分或页面创建自定义布局变得很容易。
|
||||
|
||||
布局遵循所有常规的 Hugo 模板规则，更多信息请参阅[官方 Hugo 文档](https://gohugo.io/templates/introduction/)。
|
||||
|
||||
### 覆盖默认布局
|
||||
|
||||
上面讨论的每种内容类型都列出了用于生成每种页面类型的布局文件。如果在本地项目中创建了此文件，它将覆盖主题模板，因此可用于自定义网站的默认样式。
|
||||
|
||||
例如，创建一个 `layouts/_default/single.html` 文件将允许完全自定义叶页面的布局。
|
||||
|
||||
### 自定义部分布局
|
||||
|
||||
为个别内容部分创建自定义布局也很简单。当您想要使用特定样式列出某种类型内容的部分时，这将非常有用。
|
||||
|
||||
让我们通过一个示例来创建一个自定义的“项目”页面，该页面使用特殊布局列出项目。
|
||||
|
||||
为了做到这一点，使用常规的 Hugo 内容规则构建您的内容，并为您的项目创建一个新部分。此外，通过使用与内容相同的目录名称并添加一个 `list.html` 文件来为项目部分创建一个新布局。
|
||||
|
||||
```shell
|
||||
.
|
||||
└── content
|
||||
│ └── projects
|
||||
│ ├── _index.md
|
||||
│ ├── first-project.md
|
||||
│ └── second-project.md
|
||||
└── layouts
|
||||
└── projects
|
||||
└── list.html
|
||||
```
|
||||
|
||||
这个 `list.html` 文件现在将覆盖默认的列表模板，但仅适用于 `projects` 部分。在我们查看这个文件之前，让我们首先查看个别项目文件。
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Congo"
|
||||
date: 2021-08-11
|
||||
icon: "github"
|
||||
description: "A theme for Hugo built with Tailwind CSS."
|
||||
topics: ["Hugo", "Web", "Tailwind"]
|
||||
externalUrl: "https://github.com/jpanther/congo/"
|
||||
---
|
||||
```
|
||||
|
||||
_在这个示例中，我们为每个项目分配了一些元数据，然后我们可以在我们的列表模板中使用这些元数据。这里没有页面内容，但没有阻止您包含它。毕竟这是您自己的自定义模板！_
|
||||
|
||||
有了定义的项目，现在我们可以创建一个列表模板，输出每个项目的详细信息。
|
||||
|
||||
```go
|
||||
{{ define "main" }}
|
||||
<section class="mt-8">
|
||||
{{ range .Pages }}
|
||||
<article class="pb-6">
|
||||
<a class="flex" href="{{ .Params.externalUrl }}">
|
||||
<div class="mr-3 text-3xl text-neutral-300">
|
||||
<span class="relative inline-block align-text-bottom">
|
||||
{{ partial "icon.html" .Params.icon }}
|
||||
</span>
|
||||
</div>
|
||||
<div>
|
||||
<h3 class="flex text-xl font-semibold">
|
||||
{{ .Title }}
|
||||
</h3>
|
||||
<p class="text-sm text-neutral-400">
|
||||
{{ .Description }}
|
||||
</p>
|
||||
</div>
|
||||
</a>
|
||||
</article>
|
||||
{{ end }}
|
||||
</section>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
虽然这是一个相当简单的示例，但您可以看到它逐步处理此部分中的每个页面（即每个项目），然后输出到每个项目旁边的 HTML 链接和图标。每个项目的前置元数据用于确定显示哪些信息。
|
||||
|
||||
请记住，您需要确保相关的样式和类可用，这可能需要重新编译 Tailwind CSS。这在 [高级自定义]({{< ref "advanced-customisation" >}}) 部分中有更详细的讨论。
|
||||
|
||||
在创建此类自定义模板时，最简单的方法始终是查看默认 Congo 模板的工作方式，然后将其用作指南。记住，[Hugo 文档](https://gohugo.io/templates/introduction/)也是学习有关创建模板的更多信息的绝佳资源。
|
||||
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 17 KiB |
@@ -0,0 +1,51 @@
|
||||
---
|
||||
title: "フロントマター"
|
||||
date: 2020-08-12
|
||||
draft: false
|
||||
description: "Congoにおけるフロントマターの設定について"
|
||||
summary: "CongoはほとんどのHugoのデフォルト設定をサポートしつつ、個々の記事の表示をカスタマイズするための多くのフロントマターを追加しています。"
|
||||
slug: "front-matter"
|
||||
tags: ["front matter", "config", "docs"]
|
||||
---
|
||||
|
||||
[Hugoのフロントマターパラメーター](https://gohugo.io/content-management/front-matter/#front-matter-variables)に加えて、Congoは個々の記事の表示をカスタマイズするためのオプションを追加しています。利用可能なフロントマターのパラメーターを以下に示します。
|
||||
|
||||
フロントマターパラメーターのデフォルト値はテーマの[基本設定]({{< ref "configuration" >}})から継承されるので、デフォルトを上書きしたい場合にのみフロントマターでこれらのパラメーターを指定する必要があります。
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|Name|Default|Description|
|
||||
|---|---|---|
|
||||
|`title`|_Not set_|記事の名前。|
|
||||
|`description`|_Not set_|記事の説明文。HTMLメタデータで使用されます。|
|
||||
|`feature`|`"*feature*"`|この記事の `feature` 画像のファイル名にマッチするテキストパターン。|
|
||||
|`featureAlt`|`""`|`feature` 画像の代替テキスト説明。|
|
||||
|`cover`|`"*cover*"`|この記事の `cover` 画像のファイル名にマッチするテキストパターン。|
|
||||
|`coverAlt`|`featureAlt`|`cover` 画像の代替テキスト説明。|
|
||||
|`coverCaption`|_Not set_|`cover` 画像の下に表示されるキャプションテキスト。|
|
||||
|`thumbnail`|`"*thumb*"`_|この記事の `thumb` 画像のファイル名にマッチするテキストパターン。|
|
||||
|`thumbnailAlt`|`featureAlt`|`thumb` 画像の代替テキスト説明。|
|
||||
|`externalUrl`|_Not set_|この記事が第三者のウェブサイトで公開されている場合のURL。URLを提供することで、コンテンツページが生成されるのを防ぎ、この記事への参照はすべて第三者のウェブサイトに直接リンクされます。|
|
||||
|`editURL`|`article.editURL`|`showEdit` がアクティブな場合の編集リンクのURL。|
|
||||
|`editAppendPath`|`article.editAppendPath`|`editURL`で設定されたURLに現在の記事へのパスを追加するかどうか。|
|
||||
|`groupByYear`|`list.groupByYear`|一覧ページで記事を年ごとにグループ化するかどうか。|
|
||||
|`keywords`|_Not set_|記事のメタデータに含めるべきキーワード。|
|
||||
|`menu`|_Not set_|値が指定されると、指定されたメニューにこの記事へのリンクが表示されます。有効な値は `main` または `footer` です。|
|
||||
|`robots`|_Not set_|ロボットがこの記事をどのように扱うべきかを示す文字列。設定された場合、 `<head>` に出力されます。有効な値については[Googleのドキュメント](https://developers.google.com/search/docs/advanced/robots/robots_meta_tag#directives)を参照してください。|
|
||||
|`sharingLinks`|`article.sharingLinks`|この記事の最後にどの共有リンクを表示するか。 `false` に設定すると共有リンクは表示されません。|
|
||||
|`showAuthor`|`article.showAuthor`|記事フッターに著者欄を表示するかどうか。|
|
||||
|`showBreadcrumbs`|`article.showBreadcrumbs` or `list.showBreadcrumbs`|パンくずリストを記事のヘッダーに表示するか、リストのヘッダーに表示するか。|
|
||||
|`showDate`|`article.showDate`|記事が作成された日付を表示するかどうか。日付は `date` パラメーターで設定します。|
|
||||
|`showDateUpdated`|`article.showDateUpdated`|記事が更新された日付を表示するかどうか。日付は `lastmod` パラメーターで設定します。|
|
||||
|`showEdit`|`article.showEdit`|記事の内容を編集するためのリンクを表示するかどうか。|
|
||||
|`showHeadingAnchors`|`article.showHeadingAnchors`|見出しアンカーリンクを記事内の見出しと一緒に表示するかどうか。|
|
||||
|`showPagination`|`article.showPagination`|記事のフッターに次/前の記事リンクを表示するかどうか。|
|
||||
|`invertPagination`|`article.invertPagination`|次の記事/前の記事リンクの向きを反転させるかどうか。|
|
||||
|`showReadingTime`|`article.showReadingTime`|記事の予想読了時間を表示するかどうか。|
|
||||
|`showTaxonomies`|`article.showTaxonomies`|この記事に関連するTaxonomiesを表示するかどうか。|
|
||||
|`showTableOfContents`|`article.showTableOfContents`|この記事に目次を表示するかどうか。|
|
||||
|`showWordCount`|`article.showWordCount`|記事の単語数を表示するかどうか。|
|
||||
|`showComments`|`article.showComments`|[コメント]({{< ref "partials#コメント" >}})を記事フッターの後に含めるかどうか。|
|
||||
|`showSummary`|`list.showSummary`|リストページに記事の要約を表示するかどうか。|
|
||||
|`summary`|Auto generated using `summaryLength` (see [site configuration]({{< ref "configuration#site-configuration" >}}))|`showSummary` が有効な場合、この記事の要約として使用されるMarkdown文字列。|
|
||||
|`xml`|`true` unless excluded by `sitemap.excludedKinds`|この記事が `/sitemap.xml` ファイルに含まれるかどうか。|
|
||||
<!-- prettier-ignore-end -->
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
title: "Front Matter"
|
||||
date: 2020-08-12
|
||||
draft: false
|
||||
description: "All the front matter variables available in Congo."
|
||||
summary: "While supporting most Hugo defaults, Congo adds a number of front matter parameters to customise the presentation of individual articles."
|
||||
slug: "front-matter"
|
||||
tags: ["front matter", "config", "docs"]
|
||||
---
|
||||
|
||||
In addition to the [default Hugo front matter parameters](https://gohugo.io/content-management/front-matter/#front-matter-variables), Congo adds a number of additional options to customise the presentation of individual articles. All the available theme front matter parameters are listed below.
|
||||
|
||||
Front matter parameter default values are inherited from the theme's [base configuration]({{< ref "configuration" >}}), so you only need to specify these parameters in your front matter when you want to override the default.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|Name|Default|Description|
|
||||
|---|---|---|
|
||||
|`title`|_Not set_|The name of the article.|
|
||||
|`description`|_Not set_|The text description for the article. It is used in the HTML metadata.|
|
||||
|`feature`|`"*feature*"`|The text pattern to match the feature image filename for this article.|
|
||||
|`featureAlt`|`""`|The alternative text description for the feature image.|
|
||||
|`cover`|`"*cover*"`|The text pattern to match the cover image filename for this article.|
|
||||
|`coverAlt`|`featureAlt`|The alternative text description for the cover image.|
|
||||
|`coverCaption`|_Not set_|The figure caption text to be displayed beneath the cover image.|
|
||||
|`thumbnail`|`"*thumb*"`_|The text pattern to match the thumbnail image filename for this article.|
|
||||
|`thumbnailAlt`|`featureAlt`|The alternative text description for the thumbnail image.|
|
||||
|`externalUrl`|_Not set_|If this article is published on a third-party website, the URL to this article. Providing a URL will prevent a content page being generated and any references to this article will link directly to the third-party website.|
|
||||
|`editURL`|`article.editURL`|When `showEdit` is active, the URL for the edit link.|
|
||||
|`editAppendPath`|`article.editAppendPath`|When `showEdit` is active, whether or not the path to the current article should be appended to the URL set at `editURL`.|
|
||||
|`groupByYear`|`list.groupByYear`|Whether or not articles are grouped by year on list pages.|
|
||||
|`keywords`|_Not set_|Any keywords that should be included in the article metadata.|
|
||||
|`menu`|_Not set_|When a value is provided, a link to this article will appear in the named menus. Valid values are `main` or `footer`.|
|
||||
|`robots`|_Not set_|String that indicates how robots should handle this article. If set, it will be output in the page head. Refer to [Google's docs](https://developers.google.com/search/docs/advanced/robots/robots_meta_tag#directives) for valid values.|
|
||||
|`sharingLinks`|`article.sharingLinks`|Which sharing links to display at the end of this article. When not provided, or set to `false` no links will be displayed.|
|
||||
|`showAuthor`|`article.showAuthor`|Whether or not the author box is displayed in the article footer.|
|
||||
|`showBreadcrumbs`|`article.showBreadcrumbs` or `list.showBreadcrumbs`|Whether the breadcrumbs are displayed in the article or list header.|
|
||||
|`showDate`|`article.showDate`|Whether or not the article date is displayed. The date is set using the `date` parameter.|
|
||||
|`showDateUpdated`|`article.showDateUpdated`|Whether or not the date the article was updated is displayed. The date is set using the `lastmod` parameter.|
|
||||
|`showEdit`|`article.showEdit`|Whether or not the link to edit the article content should be displayed.|
|
||||
|`showHeadingAnchors`|`article.showHeadingAnchors`|Whether or not heading anchor links are displayed alongside headings within this article.|
|
||||
|`showPagination`|`article.showPagination`|Whether or not the next/previous article links are displayed in the article footer.|
|
||||
|`invertPagination`|`article.invertPagination`|Whether or not to flip the direction of the next/previous article links.|
|
||||
|`showReadingTime`|`article.showReadingTime`|Whether or not the article reading time is displayed.|
|
||||
|`showTaxonomies`|`article.showTaxonomies`|Whether or not the taxonomies that relate to this article are displayed.|
|
||||
|`showTableOfContents`|`article.showTableOfContents`|Whether or not the table of contents is displayed on this article.|
|
||||
|`showWordCount`|`article.showWordCount`|Whether or not the article word count is displayed.|
|
||||
|`showComments`|`article.showComments`|Whether or not the [comments partial]({{< ref "partials#comments" >}}) is included after the article footer.|
|
||||
|`showSummary`|`list.showSummary`|Whether or not the article summary should be displayed on list pages.|
|
||||
|`summary`|Auto generated using `summaryLength` (see [site configuration]({{< ref "configuration#site-configuration" >}}))|When `showSummary` is enabled, this is the Markdown string to be used as the summary for this article.|
|
||||
|`xml`|`true` unless excluded by `sitemap.excludedKinds`|Whether or not this article is included in the generated `/sitemap.xml` file.|
|
||||
<!-- prettier-ignore-end -->
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
title: "Front Matter"
|
||||
date: 2020-08-12
|
||||
draft: false
|
||||
description: "Congo中可用的所有Front Matter 变量。"
|
||||
summary: "虽然支持大多数 Hugo 默认值，但 Congo 添加了许多前置参数，以定制单个文章的呈现方式。"
|
||||
slug: "front-matter"
|
||||
tags: ["front matter", "config", "docs"]
|
||||
---
|
||||
|
||||
除了[默认 Hugo 的Front Matter变量](https://gohugo.io/content-management/front-matter/#front-matter-variables)之外，Congo 添加了许多额外的选项，以定制单个文章的呈现方式。以下是所有可用的主题前置变量参数。
|
||||
|
||||
Front Matter参数的默认值是从主题的[基础配置]({{< ref "configuration" >}})中继承的，因此只有在要覆盖默认值时才需要在Front Matter变量中指定这些参数。
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|Name|Default|Description|
|
||||
|---|---|---|
|
||||
|`title`|_未设置_|文章的标题。|
|
||||
|`description`|_未设置_|文章的文本描述。用于 HTML 元数据。|
|
||||
|`feature`|`"*feature*"`|用于匹配此文章的feature图片文件名的文本模式。|
|
||||
|`featureAlt`|`""`|feature图片的替代文本描述。|
|
||||
|`cover`|`"*cover*"`|用于匹配此文章的封面图片文件名的文本模式。|
|
||||
|`coverAlt`|`featureAlt`|封面图片的替代文本描述。|
|
||||
|`coverCaption`|_未设置_|在封面图片下方显示的图注文本。|
|
||||
|`thumbnail`|`"*thumb*"`_|用于匹配此文章的缩略图图片文件名的文本模式。|
|
||||
|`thumbnailAlt`|`featureAlt`|缩略图图片的替代文本描述。|
|
||||
|`externalUrl`|_未设置_|如果此文章发表在第三方网站上，则为此文章的 URL。提供 URL 将阻止生成内容页面，并且对此文章的任何引用将直接链接到第三方网站。|
|
||||
|`editURL`|`article.editURL`|当 `showEdit` 激活时，编辑链接的 URL。|
|
||||
|`editAppendPath`|`article.editAppendPath`|当 `showEdit` 激活时，是否将当前文章的路径附加到 `editURL` 设置的 URL。|
|
||||
|`groupByYear`|`list.groupByYear`|文章在列表页面上是否按年份分组。|
|
||||
|`keywords`|_未设置_|应包含在文章元数据中的任何关键字。|
|
||||
|`menu`|_未设置_|提供数值时，此文章的链接将出现在指定的菜单中。有效值为 `main` 或 `footer`。|
|
||||
|`robots`|_未设置_|指示爬虫机器人如何处理此文章的字符串。如果设置，它将输出到页面头部。参考[Google文档](https://developers.google.com/search/docs/advanced/robots/robots_meta_tag#directives)获取有效值。|
|
||||
|`sharingLinks`|`article.sharingLinks`|在文章末尾显示哪些分享链接。如果未提供或设置为 `false`，则不显示任何链接。|
|
||||
|`showAuthor`|`article.showAuthor`|是否在文章页脚显示作者框。|
|
||||
|`showBreadcrumbs`|`article.showBreadcrumbs` 或 `list.showBreadcrumbs`|是否在文章或列表页眉中显示面包屑。|
|
||||
|`showDate`|`article.showDate`|是否显示文章日期。日期使用 `date` 参数设置。|
|
||||
|`showDateUpdated`|`article.showDateUpdated`|是否显示文章的更新日期。日期使用 `lastmod` 参数设置。|
|
||||
|`showEdit`|`article.showEdit`|是否显示编辑文章内容的链接。|
|
||||
|`showHeadingAnchors`|`article.showHeadingAnchors`|是否在文章中的标题旁边显示标题锚链接。|
|
||||
|`showPagination`|`article.showPagination`|是否在文章页脚显示下一篇/上一篇文章的链接。|
|
||||
|`invertPagination`|`article.invertPagination`|是否翻转下一篇/上一篇文章链接的方向。|
|
||||
|`showReadingTime`|`article.showReadingTime`|是否显示文章的阅读时间。|
|
||||
|`showTaxonomies`|`article.showTaxonomies`|是否显示与此文章相关的分类法。|
|
||||
|`showTableOfContents`|`article.showTableOfContents`|是否在文章中显示目录。|
|
||||
|`showWordCount`|`article.showWordCount`|是否显示文章的字数统计。|
|
||||
|`showComments`|`article.showComments`|是否在文章页脚后包含[评论部分]({{< ref "partials#comments" >}})。|
|
||||
|`showSummary`|`list.showSummary`|是否在列表页上显示文章摘要。|
|
||||
|`summary`|使用 `summaryLength` 自动生成（参见[站点配置]({{< ref "configuration#site-configuration" >}})）|当启用 `showSummary` 时，用作此文章摘要的 Markdown 字符串。|
|
||||
|`xml`|`true`，除非被 `sitemap.excludedKinds` 排除|此文章是否包含在生成的 `/sitemap.xml` 文件中。|
|
||||
<!-- prettier-ignore-end -->
|
||||
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 14 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 44 KiB |
@@ -0,0 +1,246 @@
|
||||
---
|
||||
title: "はじめに"
|
||||
date: 2020-08-15
|
||||
draft: false
|
||||
description: "Congoを使い始める方法"
|
||||
summary: "このセクションでは、すでにCongoをインストールし、カラースキーム、メニュー、コンテンツ構造の選択など基本的な設定作業を行う準備ができていることを前提としています。"
|
||||
slug: "getting-started"
|
||||
tags: ["installation", "docs"]
|
||||
---
|
||||
|
||||
{{< alert >}}
|
||||
このセクションはあなたが既に[インストール]({{< ref "docs/installation" >}})を終えていることを前提としています。
|
||||
{{< /alert >}}
|
||||
|
||||
Congoに同梱されている設定ファイルには、テーマが認識できるすべての設定が含まれおり、デフォルトでは多くはコメントアウトされていますが、特定の機能を有効にしたり変更したりするには、コメントアウトを解除するだけです。
|
||||
|
||||
## 基本設定
|
||||
|
||||
コンテンツを作成する前に、新規インストール用に設定すべきことがいくつかあります。まず `config.toml` ファイルで、`baseURL` と `languageCode` パラメーターを設定し、 `languageCode` には、コンテンツの作成に使用するメインの言語を設定しましょう。
|
||||
|
||||
```toml
|
||||
# config/_default/config.toml
|
||||
|
||||
baseURL = "https://your_domain.com/"
|
||||
languageCode = "en"
|
||||
```
|
||||
|
||||
次のステップは言語設定です。Congoは多言語をサポートしていますが、今はメインの言語だけを設定してください。
|
||||
|
||||
`config/_default` の中にある `languages.en.toml` ファイルを探してください。メイン言語が英語の場合は、このファイルをそのまま使うことができます。そうでない場合は、ファイル名に正しい言語コードが含まれるようにファイル名を変更してください。例えばフランス語の場合は、 `languages.fr.toml` にファイル名を変更します。
|
||||
|
||||
{{< alert >}}
|
||||
言語設定ファイル名の言語コードは、 `config.toml` の `languageCode` 設定と一致している必要があります。
|
||||
{{< /alert >}}
|
||||
|
||||
```toml
|
||||
# config/_default/languages.en.toml
|
||||
|
||||
title = "My awesome website"
|
||||
|
||||
[params.author]
|
||||
name = "My name"
|
||||
image = "img/author.jpg"
|
||||
headline = "A generally awesome human"
|
||||
bio = "A little bit about me"
|
||||
links = [
|
||||
{ twitter = "https://twitter.com/username" }
|
||||
]
|
||||
```
|
||||
|
||||
`[params.author]` はウェブサイト上でどのように著者情報を表示するかを決定します。画像はサイトの `assets/` に置きましょう。リンクはリストの記述順に沿って表示されます。
|
||||
|
||||
各設定に関する詳細情報は、[設定]({{< ref "configuration" >}})セクションで説明されています。
|
||||
|
||||
## カラースキーム
|
||||
|
||||
Congoにはいくつかのカラースキームが同梱されています。配色を変更するには、`colorScheme` パラメーターを設定するだけです。有効なオプションは `congo` （デフォルト）、 `avocado` 、 `cherry` 、 `fire` 、 `ocean` 、 `sapphire` 、 `slate` です。
|
||||
|
||||
{{< alert >}}
|
||||
`colourScheme` の値は小文字で指定します。
|
||||
{{< /alert >}}
|
||||
|
||||
```toml
|
||||
# config/_default/params.toml
|
||||
|
||||
colorScheme = "congo"
|
||||
```
|
||||
|
||||
Congoは、テーマ全体で使用される3色のパレットを定義しています。それぞれのメインカラーには、[Tailwind](https://tailwindcss.com/docs/customizing-colors#color-palette-reference)に含まれる10色の濃淡が含まれています。
|
||||
|
||||
#### Congo (default)
|
||||
|
||||
{{< swatches "#71717a" "#8b5cf6" "#d946ef" >}}
|
||||
|
||||
#### Avocado
|
||||
|
||||
{{< swatches "#78716c" "#84cc16" "#10b981" >}}
|
||||
|
||||
#### Cherry
|
||||
|
||||
{{< swatches "#737373" "#f43f5e" "#22c55e" >}}
|
||||
|
||||
#### Fire
|
||||
|
||||
{{< swatches "#78716c" "#f97316" "#f43f5e" >}}
|
||||
|
||||
#### Ocean
|
||||
|
||||
{{< swatches "#64748b" "#3b82f6" "#06b6d4" >}}
|
||||
|
||||
#### Sapphire
|
||||
|
||||
{{< swatches "#64748b" "#6366f1" "#ec4899" >}}
|
||||
|
||||
#### Slate
|
||||
|
||||
{{< swatches "#6B7280" "#64748b" "#6B7280" >}}
|
||||
|
||||
独自の配色を作成することもできます。詳しくは [高度な設定]({{< ref "advanced-customisation#colour-schemes" >}})セクションを参照してください。
|
||||
|
||||
## コンテンツの整理
|
||||
|
||||
Congoは特定のコンテンツタイプを強制しません。そのため、自由にコンテンツを定義することができます。静的なサイトには*pages*、ブログには*posts*、ポートフォリオには*projects*がいいかもしれません。
|
||||
|
||||
### ディレクトリ構造
|
||||
|
||||
基本的なCongoプロジェクトの概要を説明します。すべてのコンテンツは `content` に置かれます:
|
||||
|
||||
```shell
|
||||
.
|
||||
├── assets
|
||||
│ └── img
|
||||
│ └── author.jpg
|
||||
├── config
|
||||
│ └── _default
|
||||
├── content
|
||||
│ ├── _index.md
|
||||
│ ├── about.md
|
||||
│ └── posts
|
||||
│ ├── _index.md
|
||||
│ ├── first-post.md
|
||||
│ └── another-post
|
||||
│ ├── aardvark.jpg
|
||||
│ └── index.md
|
||||
└── themes
|
||||
└── congo
|
||||
```
|
||||
|
||||
{{< alert >}}
|
||||
ここで注意しなければならないのは、コンテンツディレクトリの中で、通常の記事ページは `index.md` という名前になり、リストページは `_index.md` という名前になるということです。記事に付随するアセットはインデックスファイルと一緒にサブディレクトリに置く必要があります。
|
||||
{{< /alert >}}
|
||||
|
||||
このテーマはHugoのページバンドルを最大限に活用するように設計されているため、Hugoがどのようにコンテンツを整理することを想定しているかをしっかりと把握することが重要です。詳しくは[Hugo公式ドキュメント](https://gohugo.io/content-management/organization/)を読んでください。
|
||||
|
||||
### feature、cover、そしてthumb(nail)
|
||||
|
||||
Congoは、記事リストと個々の記事ページの上部に画像を表示できます。サポートされている画像には3つのタイプがあり、それぞれに使用例があります: `feature` 、 `cover` 、 `thumb` です。
|
||||
|
||||
以下の例では、 `first-post` の記事に `cover` と `thumb` を用意しています:
|
||||
|
||||
```shell
|
||||
.
|
||||
└── content
|
||||
└── posts
|
||||
├── _index.md
|
||||
└── first-post
|
||||
├── cover.jpg
|
||||
├── index.md
|
||||
└── thumb.jpg
|
||||
```
|
||||
|
||||
`thumb` 画像は記事のサムネイルとして記事リストで表示され、 `cover` 画像は個々の記事ページで記事内容の上部に表示されます。
|
||||
|
||||
|
||||
|
||||
{{< alert >}}
|
||||
パフォーマンスの観点から、 `thumb` 画像は自動的に4:3の比率にトリミング・リサイズされます。 `cover` 画像は内容に合わせて自動的にリサイズされますが、比率は問いません。
|
||||
{{< /alert >}}
|
||||
|
||||
The `feature` image is a special type, and when present, it will be used in place of _both_ the `thumb` and `cover` images. Feature images are also present in the article metadata, which is included when content is shared to third-party networks like Facebook and Twitter.
|
||||
`feature` 画像は特別で、存在する場合には `thumb` 画像と `cover` 画像の両方の代わりに使用されます。 `feature` 画像は記事のメタデータとして、FacebookやTwitterのようなサードパーティのネットワークにコンテンツが共有される場合にも含まれます。
|
||||
|
||||
Congoは記事画像をインテリジェントに検出し、自動的にあなたのサイトに追加します。フロントマターでそれらを指定する必要はなく、ページリソース内に適切な名前のファイルを配置するだけです。画像ファイル名のどこかに `feature` 、 `cover` 、 `thumb` という単語があれば、それがその目的で使用されます。
|
||||
|
||||
[例]({{< ref "samples" >}})には、これらの画像の例が多数掲載されています（また、[ソースコード](https://github.com/jpanther/congo/tree/dev/exampleSite/content/samples)を参照してファイル構造を確認することもできます）。
|
||||
|
||||
### Taxonomies
|
||||
|
||||
CongoはTaxonomiesに関しても柔軟です。 `tags` や `categories` を使ってコンテンツをグループ化したい人もいれば、 `topics` を使いたい人もいるでしょう。
|
||||
|
||||
Hugoはデフォルトで `posts` 、 `tags` 、 `categories` を使用するようになっています。しかし、これをカスタマイズしたい場合は、 `taxonomies.toml` 設定ファイルを作成することでカスタマイズできます:
|
||||
|
||||
```toml
|
||||
# config/_default/taxonomies.toml
|
||||
|
||||
topic = "topics"
|
||||
```
|
||||
|
||||
上記の例はデフォルトの _tags_ と _categories_ を _topics_ に置き換えます。詳細は、[Hugo Taxonomy docs](https://gohugo.io/content-management/taxonomies/)を参照してください。
|
||||
|
||||
When you create a new taxonomy, you will need to adjust the navigation links on the website to point to the correct sections, which is covered below.
|
||||
|
||||
## メニュー
|
||||
|
||||
Congoには2つのメニューがあり、サイトの内容やレイアウトに合わせてカスタマイズすることができます。 `main` メニューはサイトのヘッダーに表示され、 `footer` メニューはページの一番下、著作権表示のすぐ上に表示されます。
|
||||
|
||||
Both menus are configured in the `menus.en.toml` file. Similarly to the languages config file, if you wish to use another language, rename this file and replace `en` with the language code you wish to use. Menu links will be sorted from lowest to highest `weight`, and then alphabetically by `name`.
|
||||
どちらのメニューも `menus.en.toml` ファイルで設定すします。 `menus.en.toml` ファイルは言語設定ファイルと同様に、他の言語を使いたい場合はファイル名を変更して使いたい言語コードに置き換えてください。メニューのリンクは `weight` の低いものから高いものへとソートされ、次にアルファベット順に `name` でソートされます。
|
||||
|
||||
```toml
|
||||
# config/_default/menus.en.toml
|
||||
|
||||
[[main]]
|
||||
name = "Blog"
|
||||
pageRef = "posts"
|
||||
weight = 10
|
||||
|
||||
[[main]]
|
||||
name = "Topics"
|
||||
pageRef = "topics"
|
||||
weight = 20
|
||||
|
||||
[[main]]
|
||||
name = "GitHub"
|
||||
url = "https://github.com/jpanther/congo"
|
||||
weight = 30
|
||||
[main.params]
|
||||
icon = "github"
|
||||
showName = false
|
||||
target = "_blank"
|
||||
|
||||
[[main]]
|
||||
identifier = "search"
|
||||
weight = 99
|
||||
[main.params]
|
||||
action = "search"
|
||||
icon = "search"
|
||||
|
||||
[[footer]]
|
||||
name = "Privacy"
|
||||
pageRef = "privacy"
|
||||
```
|
||||
|
||||
### 基本のリンク
|
||||
|
||||
`name` パラメーターはメニューリンクで使用するテキストを指定します。また、オプションでリンクのHTMLタイトル属性となる `title` を指定することもできます。
|
||||
|
||||
`pageRef` パラメーターを使うと、HugoのコンテンツページやTaxonomyを簡単に参照することができます。Hugoのコンテンツアイテムを参照するだけで、自動的に正しいリンクが作成されるので、メニューを設定する最も簡単な方法です。外部URLへのリンクには `url` パラメーターを使用します。
|
||||
|
||||
リンク内に `params` を指定することで、さらなるカスタマイズが可能です。 `icon` を追加したり、 `showName` でリンクテキストを切り替えたり、URLに `target` を設定したりすることができます。上記の例では、GitHubリンクはアイコンのみで表示され、リンクは新しいウィンドウで開きます。
|
||||
|
||||
### アクションリンク
|
||||
|
||||
There is a special case for creating menu items for links that take theme actions. These are denoted using the `action` parameter, and a value of the action the link should perform. Action links allow for all the same custom parameters as other links and can be styled with an icon or text name.
|
||||
特別なケースとして、アクションを実行するリンク項目を作成する場合があります。これらは `action` パラメーターと実行するアクションの値を使って指定します。アクションリンクでは基本のリンクと同じカスタムパラメーターを使用することができ、アイコンやテキスト名でスタイルを設定することもできます。
|
||||
|
||||
有効なテーマ・アクションは2つあります:
|
||||
|
||||
- `appearance` は外観を切り替えるリンクを作成します
|
||||
- `search` はサイト内検索を行うリンクを作成します
|
||||
|
||||
どちらのメニューも完全にオプションであり、必要なければコメントアウトすることができます。デフォルトとして提供されているテンプレートも参考にしてください。
|
||||
|
||||
## 詳細な設定
|
||||
|
||||
上記の手順は最低限の設定です。これで `hugo server` を実行すると、空白のCongoウェブサイトが表示されます。詳細な設定については、[設定]({{< ref "configuration" >}})セクションを参照してください。
|
||||
@@ -0,0 +1,244 @@
|
||||
---
|
||||
title: "Getting Started"
|
||||
date: 2020-08-15
|
||||
draft: false
|
||||
description: "Learn how to get started using the Congo theme."
|
||||
summary: "This section assumes you have already installed the Congo theme and are ready to start with basic configuration tasks like selecting a colour scheme, menu and content structure."
|
||||
slug: "getting-started"
|
||||
tags: ["installation", "docs"]
|
||||
---
|
||||
|
||||
{{< alert >}}
|
||||
This section assumes you have already [installed the Congo theme]({{< ref "docs/installation" >}}).
|
||||
{{< /alert >}}
|
||||
|
||||
The config files that ship with Congo contain all of the possible settings that the theme recognises. By default, many of these are commented out but you can simply uncomment them to activate or change a specific feature.
|
||||
|
||||
## Basic configuration
|
||||
|
||||
Before creating any content, there are a few things you should set for a new installation. Starting in the `config.toml` file, set the `baseURL` and `languageCode` parameters. The `languageCode` should be set to the main language that you will be using to author your content.
|
||||
|
||||
```toml
|
||||
# config/_default/config.toml
|
||||
|
||||
baseURL = "https://your_domain.com/"
|
||||
languageCode = "en"
|
||||
```
|
||||
|
||||
The next step is to configure the language settings. Although Congo supports multilingual setups, for now, just configure the main language.
|
||||
|
||||
Locate the `languages.en.toml` file in the config folder. If your main language is English you can use this file as is. Otherwise, rename it so that it includes the correct language code in the filename. For example, for French, rename the file to `languages.fr.toml`.
|
||||
|
||||
{{< alert >}}
|
||||
The language code in the language config filename should match the `languageCode` setting in `config.toml`.
|
||||
{{< /alert >}}
|
||||
|
||||
```toml
|
||||
# config/_default/languages.en.toml
|
||||
|
||||
title = "My awesome website"
|
||||
|
||||
[params.author]
|
||||
name = "My name"
|
||||
image = "img/author.jpg"
|
||||
headline = "A generally awesome human"
|
||||
bio = "A little bit about me"
|
||||
links = [
|
||||
{ twitter = "https://twitter.com/username" }
|
||||
]
|
||||
```
|
||||
|
||||
The `[params.author]` configuration determines how the author information is displayed on the website. The image should be placed in the site's `assets/` folder. Links will be displayed in the order they are listed.
|
||||
|
||||
If you need extra detail, further information about each of these configuration options, is covered in the [Configuration]({{< ref "configuration" >}}) section.
|
||||
|
||||
## Colour schemes
|
||||
|
||||
Congo ships with a number of colour schemes out of the box. To change the scheme, simply set the `colorScheme` theme parameter. Valid options are `congo` (default), `avocado`, `cherry`, `fire`, `ocean`, `sapphire` and `slate`.
|
||||
|
||||
{{< alert >}}
|
||||
The `colourScheme` value should be provided in lowercase.
|
||||
{{< /alert >}}
|
||||
|
||||
```toml
|
||||
# config/_default/params.toml
|
||||
|
||||
colorScheme = "congo"
|
||||
```
|
||||
|
||||
Congo defines a three-colour palette that is used throughout the theme. Each main colour contains ten shades which are based upon the colours that are included in [Tailwind](https://tailwindcss.com/docs/customizing-colors#color-palette-reference).
|
||||
|
||||
#### Congo (default)
|
||||
|
||||
{{< swatches "#71717a" "#8b5cf6" "#d946ef" >}}
|
||||
|
||||
#### Avocado
|
||||
|
||||
{{< swatches "#78716c" "#84cc16" "#10b981" >}}
|
||||
|
||||
#### Cherry
|
||||
|
||||
{{< swatches "#737373" "#f43f5e" "#22c55e" >}}
|
||||
|
||||
#### Fire
|
||||
|
||||
{{< swatches "#78716c" "#f97316" "#f43f5e" >}}
|
||||
|
||||
#### Ocean
|
||||
|
||||
{{< swatches "#64748b" "#3b82f6" "#06b6d4" >}}
|
||||
|
||||
#### Sapphire
|
||||
|
||||
{{< swatches "#64748b" "#6366f1" "#ec4899" >}}
|
||||
|
||||
#### Slate
|
||||
|
||||
{{< swatches "#6B7280" "#64748b" "#6B7280" >}}
|
||||
|
||||
Although these are the default schemes, you can also create your own. Refer to the [Advanced Customisation]({{< ref "advanced-customisation#colour-schemes" >}}) section for details.
|
||||
|
||||
## Organising content
|
||||
|
||||
By default, Congo doesn't force you to use a particular content type. In doing so you are free to define your content as you wish. You might prefer _pages_ for a static site, _posts_ for a blog, or _projects_ for a portfolio.
|
||||
|
||||
### Directory structure
|
||||
|
||||
Here's a quick overview of a basic Congo project. All content is placed within the `content` folder:
|
||||
|
||||
```shell
|
||||
.
|
||||
├── assets
|
||||
│ └── img
|
||||
│ └── author.jpg
|
||||
├── config
|
||||
│ └── _default
|
||||
├── content
|
||||
│ ├── _index.md
|
||||
│ ├── about.md
|
||||
│ └── posts
|
||||
│ ├── _index.md
|
||||
│ ├── first-post.md
|
||||
│ └── another-post
|
||||
│ ├── aardvark.jpg
|
||||
│ └── index.md
|
||||
└── themes
|
||||
└── congo
|
||||
```
|
||||
|
||||
{{< alert >}}
|
||||
The key thing to note here is that within the content directory, normal article pages are named `index.md` while list pages are named `_index.md`. Any assets that go along with the article should be placed in a sub-directory alongside the index file.
|
||||
{{< /alert >}}
|
||||
|
||||
It's important to have a firm grasp of how Hugo expects content to be organised as the theme is designed to take full advantage of Hugo page bundles. Be sure to read the [official Hugo docs](https://gohugo.io/content-management/organization/) for more information.
|
||||
|
||||
### Feature, cover and thumbnail images
|
||||
|
||||
The Congo theme supports displaying images on article listings and at the top of individual article pages. There are three types of images supported, each with their own use case: `feature`, `cover` and `thumb`.
|
||||
|
||||
In the example below, a cover and thumb image have been provided for the `first-post` article:
|
||||
|
||||
```shell
|
||||
.
|
||||
└── content
|
||||
└── posts
|
||||
├── _index.md
|
||||
└── first-post
|
||||
├── cover.jpg
|
||||
├── index.md
|
||||
└── thumb.jpg
|
||||
```
|
||||
|
||||
The `thumb` image is used as the article thumbnail and will be displayed in article lists, and the `cover` image will be displayed at the top of the article content on individual article pages.
|
||||
|
||||
|
||||
|
||||
{{< alert >}}
|
||||
In order to provide maximum performance, thumbnail images are automatically cropped and resized to a 4:3 ratio. Cover images will be automatically resized to fit their content, but any ratio is permitted.
|
||||
{{< /alert >}}
|
||||
|
||||
The `feature` image is a special type, and when present, it will be used in place of _both_ the `thumb` and `cover` images. Feature images are also present in the article metadata, which is included when content is shared to third-party networks like Facebook and Twitter.
|
||||
|
||||
The theme will intelligently detect article images and automatically add them to your site. You don't have to refer to them in the front matter and simply need to place an appropriately named file within the page resources. If the term `feature`, `cover` or `thumb` is found anywhere in the image filename, then it will be used for that purpose.
|
||||
|
||||
The [Samples section]({{< ref "samples" >}}) provides a number of examples of these images (and you can view the [source code](https://github.com/jpanther/congo/tree/dev/exampleSite/content/samples) to see the file structure).
|
||||
|
||||
### Taxonomies
|
||||
|
||||
Congo is also flexible when it comes to taxonomies. Some people prefer to use _tags_ and _categories_ to group their content, others prefer to use _topics_.
|
||||
|
||||
Hugo defaults to using posts, tags and categories out of the box and this will work fine if that's what you want. If you wish to customise this, however, you can do so by creating a `taxonomies.toml` configuration file:
|
||||
|
||||
```toml
|
||||
# config/_default/taxonomies.toml
|
||||
|
||||
topic = "topics"
|
||||
```
|
||||
|
||||
This will replace the default _tags_ and _categories_ with _topics_. Refer to the [Hugo Taxonomy docs](https://gohugo.io/content-management/taxonomies/) for more information on naming taxonomies.
|
||||
|
||||
When you create a new taxonomy, you will need to adjust the navigation links on the website to point to the correct sections, which is covered below.
|
||||
|
||||
## Menus
|
||||
|
||||
Congo has two menus that can be customised to suit the content and layout of your site. The `main` menu appears in the site header and the `footer` menu appears at the bottom of the page just above the copyright notice.
|
||||
|
||||
Both menus are configured in the `menus.en.toml` file. Similarly to the languages config file, if you wish to use another language, rename this file and replace `en` with the language code you wish to use. Menu links will be sorted from lowest to highest `weight`, and then alphabetically by `name`.
|
||||
|
||||
```toml
|
||||
# config/_default/menus.en.toml
|
||||
|
||||
[[main]]
|
||||
name = "Blog"
|
||||
pageRef = "posts"
|
||||
weight = 10
|
||||
|
||||
[[main]]
|
||||
name = "Topics"
|
||||
pageRef = "topics"
|
||||
weight = 20
|
||||
|
||||
[[main]]
|
||||
name = "GitHub"
|
||||
url = "https://github.com/jpanther/congo"
|
||||
weight = 30
|
||||
[main.params]
|
||||
icon = "github"
|
||||
showName = false
|
||||
target = "_blank"
|
||||
|
||||
[[main]]
|
||||
identifier = "search"
|
||||
weight = 99
|
||||
[main.params]
|
||||
action = "search"
|
||||
icon = "search"
|
||||
|
||||
[[footer]]
|
||||
name = "Privacy"
|
||||
pageRef = "privacy"
|
||||
```
|
||||
|
||||
### Basic links
|
||||
|
||||
The `name` parameter specifies the text that is used in the menu link. You can also optionally provide a `title` which fills the HTML title attribute for the link.
|
||||
|
||||
The `pageRef` parameter allows you to easily reference Hugo content pages and taxonomies. It is the quickest way to configure the menu as you can simply refer to any Hugo content item and it will automatically build the correct link. To link to external URLs, the `url` parameter can be used.
|
||||
|
||||
Further customisation can be achieved through the use of special theme parameters. Providing `params` within a link allows the addition of an `icon`, the ability to toggle the link text with `showName` and to optionally set a `target` for the URL. In the example above, the GitHub link will only display as an icon and will open the link in a new window.
|
||||
|
||||
### Action links
|
||||
|
||||
There is a special case for creating menu items for links that take theme actions. These are denoted using the `action` parameter, and a value of the action the link should perform. Action links allow for all the same custom parameters as other links and can be styled with an icon or text name.
|
||||
|
||||
There are three valid theme actions:
|
||||
|
||||
- `appearance` will create a link to the appearance switcher
|
||||
- `locale` will create a drop down picker to access translated content
|
||||
- `search` will create a link to the site search
|
||||
|
||||
Both menus are completely optional and can be commented out if not required. Use the template provided in the default file as a guide.
|
||||
|
||||
## Detailed configuration
|
||||
|
||||
The steps above are the bare minimum configuration. If you now run `hugo server` you will be presented with a blank Congo website. Detailed configuration is covered in the [Configuration]({{< ref "configuration" >}}) section.
|
||||
@@ -0,0 +1,244 @@
|
||||
---
|
||||
title: "快速开始"
|
||||
date: 2020-08-15
|
||||
draft: false
|
||||
description: "Congo的启动方法"
|
||||
summary: "这一部分假设你已经安装了Congo主题，并准备开始进行基本配置任务，如选择颜色方案、菜单和内容结构。"
|
||||
slug: "getting-started"
|
||||
tags: ["installation", "docs"]
|
||||
---
|
||||
|
||||
{{< alert >}}
|
||||
本节假定您已经[安装了Congo主题]({{< ref "docs/installation" >}})。
|
||||
{{< /alert >}}
|
||||
|
||||
Congo提供的配置文件包含主题定制的所有可能设置。默认情况下，其中许多设置项都被注释掉，但您可以简单地取消注释以激活或更改特定功能。
|
||||
|
||||
## 基本配置
|
||||
|
||||
在创建任何内容之前，有一些新安装需要设置的事项。首先在`config.toml`文件中，设置`baseURL`和`languageCode`参数。`languageCode`应设置为您将用于撰写内容的主要语言。
|
||||
|
||||
```toml
|
||||
# config/_default/config.toml
|
||||
|
||||
baseURL = "https://your_domain.com/"
|
||||
languageCode = "en"
|
||||
```
|
||||
|
||||
下一步是配置语言设置。虽然Congo支持多语言设置，但目前，只需配置主要语言即可。
|
||||
|
||||
找到config文件夹中的`languages.en.toml`文件。如果您的主要语言是英语，可以直接使用此文件。否则，将其重命名，以便文件名中包含正确的语言代码。例如，对于法语，将文件重命名为`languages.fr.toml`。
|
||||
|
||||
{{< alert >}}
|
||||
语言配置文件名中的语言代码应与`config.toml`中的`languageCode`设置相匹配。
|
||||
{{< /alert >}}
|
||||
|
||||
```toml
|
||||
# config/_default/languages.en.toml
|
||||
|
||||
title = "My awesome website"
|
||||
|
||||
[author]
|
||||
name = "My name"
|
||||
image = "img/author.jpg"
|
||||
headline = "A generally awesome human"
|
||||
bio = "A little bit about me"
|
||||
links = [
|
||||
{ twitter = "https://twitter.com/username" }
|
||||
]
|
||||
```
|
||||
|
||||
`[author]`配置确定在网站上显示作者信息的方式。图像应放置在站点的`assets/`文件夹中。链接将按照它们列出的顺序显示。
|
||||
|
||||
如果需要更多细节，每个配置选项的详细信息都在[配置]({{< ref "configuration" >}})部分中有介绍。
|
||||
|
||||
## 颜色方案
|
||||
|
||||
Congo默认情况下提供了一些颜色方案。要更改方案，只需设置`colorScheme`主题参数。有效选项为`congo`（默认）、`avocado`、`cherry`、`fire`、`ocean`、`sapphire`和`slate`。
|
||||
|
||||
{{< alert >}}
|
||||
`colorScheme`值应以小写形式提供。
|
||||
{{< /alert >}}
|
||||
|
||||
```toml
|
||||
# config/_default/params.toml
|
||||
|
||||
colorScheme = "congo"
|
||||
```
|
||||
|
||||
Congo定义了一个在整个主题中使用的三色调色板。每个主色包含十种基于包含在[Tailwind](https://tailwindcss.com/docs/customizing-colors#color-palette-reference)中的颜色的阴影。
|
||||
|
||||
#### Congo（默认）
|
||||
|
||||
{{< swatches "#71717a" "#8b5cf6" "#d946ef" >}}
|
||||
|
||||
#### Avocado
|
||||
|
||||
{{< swatches "#78716c" "#84cc16" "#10b981" >}}
|
||||
|
||||
#### Cherry
|
||||
|
||||
{{< swatches "#737373" "#f43f5e" "#22c55e" >}}
|
||||
|
||||
#### Fire
|
||||
|
||||
{{< swatches "#78716c" "#f97316" "#f43f5e" >}}
|
||||
|
||||
#### Ocean
|
||||
|
||||
{{< swatches "#64748b" "#3b82f6" "#06b6d4" >}}
|
||||
|
||||
#### Sapphire
|
||||
|
||||
{{< swatches "#64748b" "#6366f1" "#ec4899" >}}
|
||||
|
||||
#### Slate
|
||||
|
||||
{{< swatches "#6B7280" "#64748b" "#6B7280" >}}
|
||||
|
||||
尽管这些是默认的方案，但您还可以创建自己的方案。有关详细信息，请参阅[高级自定义]({{< ref "advanced-customisation#colour-schemes" >}})部分。
|
||||
|
||||
### 组织内容
|
||||
|
||||
Congo不会强制您使用特定的内容类型，默认情况下，您可以自由定义您的内容。您可以选择使用 _pages_ 来创建静态站点，使用 _posts_ 来撰写博客，或使用 _projects_ 来展示项目。这种自由度使您能够根据您的需求和偏好来组织和呈现内容。
|
||||
|
||||
### 目录结构
|
||||
|
||||
以下是基本Congo项目的快速概览。所有内容都放置在`content`文件夹中：
|
||||
|
||||
```shell
|
||||
.
|
||||
├── assets
|
||||
│ └── img
|
||||
│ └── author.jpg
|
||||
├── config
|
||||
│ └── _default
|
||||
├── content
|
||||
│ ├── _index.md
|
||||
│ ├── about.md
|
||||
│ └── posts
|
||||
│ ├── _index.md
|
||||
│ ├── first-post.md
|
||||
│ └── another-post
|
||||
│ ├── aardvark.jpg
|
||||
│ └── index.md
|
||||
└── themes
|
||||
└── congo
|
||||
```
|
||||
|
||||
{{< alert >}}
|
||||
这里需要注意的关键一点是，在content目录中，普通文章页面的命名为`index.md`，而列表页面的命名为`_index.md`。任何与文章相关的静态文件都应放置在与索引文件相邻的子目录中。
|
||||
{{< /alert >}}
|
||||
|
||||
对于Congo主题的设计，充分利用了Hugo页面束的优势，了解Hugo希望内容如何被组织是很重要的。务必阅读[Hugo官方文档](https://gohugo.io/content-management/organization/)以获取更多信息。
|
||||
|
||||
### 特色、封面和缩略图图片
|
||||
|
||||
Congo主题支持在文章列表和单独的文章页面顶部显示图像。有三种类型的图像，每种都有其特定的用途：`feature`（特色，这个不知道怎么翻译，可能是“主图” ？）、`cover`（封面）和`thumb`（缩略图）。
|
||||
|
||||
在下面的示例中，为`first-post`文章提供了封面和缩略图图像：
|
||||
|
||||
```shell
|
||||
.
|
||||
└── content
|
||||
└── posts
|
||||
├── _index.md
|
||||
└── first-post
|
||||
├── cover.jpg
|
||||
├── index.md
|
||||
└── thumb.jpg
|
||||
```
|
||||
|
||||
`thumb`图像用作文章缩略图，将显示在文章列表中，而`cover`图像将显示在单个文章页面的内容顶部。
|
||||
|
||||
|
||||
|
||||
{{< alert >}}
|
||||
为了提供最大性能，缩略图图像将自动裁剪并调整大小为4:3的比例。封面图像将自动调整大小以适应其内容，但允许任何比例。
|
||||
{{< /alert >}}
|
||||
|
||||
`feature`图像是一种特殊类型，当存在时，它将用于替代`thumb`和`cover`图像。特色图像也出现在文章元数据中，在将内容共享到Facebook和Twitter等第三方网络时包含在其中。
|
||||
|
||||
主题将智能检测文章图像并自动将其添加到您的站点。您不必在正文中引用它们，只需将以适当命名的文件放在页面资源中即可。如果图像文件名中的任何地方都包含术语`feature`、`cover`或`thumb`，那么它将用于该用途。
|
||||
|
||||
[示例部分]({{< ref "samples" >}})提供了这些图像的许多示例（您可以查看[源代码](https://github.com/jpanther/congo/tree/dev/exampleSite/content/samples)以查看文件结构）。
|
||||
|
||||
### 分类法
|
||||
|
||||
Congo 在分类方面也非常灵活。有些人喜欢使用标签（tags）和分类（categories）来对内容进行分组，而其他人可能更倾向于使用主题（topics）。
|
||||
|
||||
Hugo默认使用文章、标签和分类，如果这符合您的需求，那么这将运行良好。但是，如果您希望自定义此设置，可以通过创建`taxonomies.toml`配置文件来实现：
|
||||
|
||||
```toml
|
||||
# config/_default/taxonomies.toml
|
||||
|
||||
topic = "topics"
|
||||
```
|
||||
|
||||
这将使用主题替换默认的标签和分类。有关在命名分类法时的更多信息，请参阅[Hugo分类法文档](https://gohugo.io/content-management/taxonomies/)。
|
||||
|
||||
创建新分类法时，您将需要调整网站上的导航链接，以指向正确的部分，下面有相关说明。
|
||||
|
||||
## 菜单
|
||||
|
||||
Congo有两个菜单，可以根据您站点的内容和布局进行自定义。`main`菜单显示在站点页眉中，而`footer`菜单显示在页面底部，正好在版权声明上方。
|
||||
|
||||
这两个菜单都在`menus.en.toml`文件中配置。与语言配置文件类似，如果您希望使用其他语言，请将此文件重命名并用所需的语言代码替换`en`。菜单链接将按`weight`从低到高排序，然后按`name`字母顺序排序。
|
||||
|
||||
```toml
|
||||
# config/_default/menus.en.toml
|
||||
|
||||
[[main]]
|
||||
name = "博客"
|
||||
pageRef = "posts"
|
||||
weight = 10
|
||||
|
||||
[[main]]
|
||||
name = "主题"
|
||||
pageRef = "topics"
|
||||
weight = 20
|
||||
|
||||
[[main]]
|
||||
name = "GitHub"
|
||||
url = "https://github.com/jpanther/congo"
|
||||
weight = 30
|
||||
[main.params]
|
||||
icon = "github"
|
||||
showName = false
|
||||
target = "_blank"
|
||||
|
||||
[[main]]
|
||||
identifier = "search"
|
||||
weight = 99
|
||||
[main.params]
|
||||
action = "search"
|
||||
icon = "search"
|
||||
|
||||
[[footer]]
|
||||
name = "隐私"
|
||||
pageRef = "privacy"
|
||||
```
|
||||
|
||||
### 基本链接
|
||||
|
||||
`name` 参数指定了菜单链接中使用的文本。您还可以选择提供 `title`，用于填充链接的 HTML title 属性。
|
||||
|
||||
`pageRef` 参数允许您轻松引用 Hugo 内容页面和分类法。这是配置菜单的最快方法，因为您只需引用任何 Hugo 内容项，它将自动构建正确的链接。要链接到外部 URL，可以使用 `url` 参数。
|
||||
|
||||
通过使用特殊的主题参数，可以进一步自定义。在链接中提供 `params` 允许添加 `icon`，通过 `showName` 切换链接文本的能力，并可选择设置 URL 的 `target`。在上面的示例中，GitHub 链接将只显示为图标，并在新窗口中打开链接。
|
||||
|
||||
### 操作链接
|
||||
|
||||
有一个特殊情况，用于创建执行主题操作的菜单项。这些链接项通过 `action` 参数进行标识，该参数指定链接应执行的操作。操作链接允许使用与其他链接（基本链接）相同的自定义参数，并且可以用图标或文本名称进行样式设置。
|
||||
|
||||
Congo内置有三个有效的主题操作：
|
||||
|
||||
- `appearance` 将创建一个指向外观切换器（深色主题还是浅色主题）的链接
|
||||
- `locale` 将创建一个下拉选择器，以切换语言访问已翻译的内容
|
||||
- `search` 将创建指向站内搜索的链接
|
||||
|
||||
这两个菜单都是完全可选的，如果不需要，可以注释掉。使用默认文件中提供的模板作为配置指南。
|
||||
|
||||
## 更详细配置
|
||||
|
||||
上述步骤是最基本的配置。如果现在运行 `hugo server`，您将看到一个空白的 Congo 网站。更详细配置在 [基本配置]({{< ref "configuration" >}}) 部分进行介绍。
|
||||
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 21 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 241 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 103 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 78 KiB |
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: "ホームページレイアウト"
|
||||
date: 2020-08-13
|
||||
draft: false
|
||||
description: "Congoにおけるホームページレイアウトの設定について"
|
||||
summary: "Congoは、組み込みテンプレートと独自のテンプレートを提供する機能によって、柔軟なホームページレイアウトを提供します。"
|
||||
slug: "homepage-layout"
|
||||
tags: ["homepage", "layouts", "docs"]
|
||||
---
|
||||
|
||||
Congoは柔軟なホームページレイアウトを提供します。2つのメインテンプレートから選択でき、追加設定でデザインを調整できます。また、独自のテンプレートを用意して、ホームページの内容を完全にコントロールすることもできます。
|
||||
|
||||
ホームページのレイアウトは `params.toml` 設定ファイルの `homepage.layout` 設定によって制御されます。さらに、すべてのレイアウトには[最近の記事](#最近の記事)を表示するオプションがあります。
|
||||
|
||||
## ページレイアウト
|
||||
|
||||
デフォルトのレイアウトはページレイアウトです。これはシンプルにMarkdownコンテンツを表示します。静的なウェブサイトには最適で、多くの柔軟性を提供します。
|
||||
|
||||
|
||||
|
||||
ページレイアウトを有効にするには、 `params.toml` 設定ファイルで `homepage.layout = "page"` を設定します。
|
||||
|
||||
## プロフィールレイアウト
|
||||
|
||||
プロフィールレイアウトは、個人のウェブサイトやブログに最適です。画像とソーシャル・プロフィールへのリンクを提供することで、著者の詳細を前面に押し出します。
|
||||
|
||||
|
||||
|
||||
著者情報は `languages` 設定ファイルで提供されます。パラメーターの詳細については、[はじめに]({{< ref "getting-started" >}})と[言語と国際化]({{< ref "configuration#言語と国際化" >}})セクションを参照してください。
|
||||
|
||||
さらに、ホームページのコンテンツで提供されるすべてのMarkdownコンテンツは、著者プロフィールの下に配置されます。これにより、ショートコードを使用した著者の略歴やその他のカスタムコンテンツを表示するための柔軟性が増します。
|
||||
|
||||
プロフィールレイアウトを有効にするには、 `params.toml` 設定ファイルで `homepage.layout = "profile"` を設定します。
|
||||
|
||||
## カスタムレイアウト
|
||||
|
||||
組み込みのホームページレイアウトがあなたのニーズに十分でない場合は、独自のカスタムレイアウトを提供するオプションがあります。これにより、ページの内容を完全にコントロールすることができ、白紙の状態から作成することができます。
|
||||
|
||||
カスタムレイアウトを有効にするには、 `params.toml` 設定ファイルで `homepage.layout = "custom"` を設定します。
|
||||
|
||||
設定値が設定された状態で、新しい `custom.html` ファイルを作成し、 `layouts/partials/home/custom.html` に配置してください。これで、 `custom.html` ファイルにあるものは何でも、サイトのホームページのコンテンツエリアに配置されるようになります。レイアウトの定義には、HTML、Tailwind、Hugoのテンプレート関数など、お好きなものをお使いください。
|
||||
|
||||
カスタムレイアウトに[最近の記事](#最近の記事)を含めるには、 `recent-articles.html` パーシャルを使います。
|
||||
|
||||
例として、このサイトの[ホームページ]({{< ref "/" >}})では、カスタムレイアウトを使ってページとプロフィールのレイアウトを切り替えられるようにしています。[GitHub repo](https://github.com/jpanther/congo/blob/dev/exampleSite/layouts/partials/home/custom.html)を訪問して、どのように動作するか見てみましょう。
|
||||
|
||||
## 最近の記事
|
||||
|
||||
すべてのホームページレイアウトには、メインページコンテンツの下に最近の記事を表示するオプションがあります。これを有効にするには、 `params.toml` 設定ファイルの `homepage.showRecent` 設定を `true` にするだけです。
|
||||
|
||||
|
||||
|
||||
このセクションにリストされる記事は、 `mainSections` 設定から派生したもので、あなたのウェブサイトで使用しているコンテンツタイプに対応します。例えば、 _posts_ と _projects_ のコンテンツセクションがある場合、この設定を `["posts", "projects"]` に設定することで、これら2つのセクションにあるすべての記事が最近の記事リストに出力されます。Congoはこの設定が配列であることを想定しているので、すべてのコンテンツに1つのセクションしか使用しない場合は、この設定を適宜変更してください: `["blog"]`
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: "Homepage Layout"
|
||||
date: 2020-08-13
|
||||
draft: false
|
||||
description: "Configuring the homepage layout in the Congo theme."
|
||||
summary: "Congo provides a fully flexible homepage layout with built-in templates and the ability to provide your own."
|
||||
slug: "homepage-layout"
|
||||
tags: ["homepage", "layouts", "docs"]
|
||||
---
|
||||
|
||||
Congo provides a fully flexible homepage layout. There are two main templates to choose from with additional settings to adjust the design. Alternatively, you can also provide your own template and have complete control over the homepage content.
|
||||
|
||||
The layout of the homepage is controlled by the `homepage.layout` setting in the `params.toml` configuration file. Additionally, all layouts have the option to include a listing of [recent articles](#recent-articles).
|
||||
|
||||
## Page layout
|
||||
|
||||
The default layout is the page layout. It's simply a normal content page that displays your Markdown content. It's great for static websites and provides a lot of flexibility.
|
||||
|
||||
|
||||
|
||||
To enable the page layout, set `homepage.layout = "page"` in the `params.toml` configuration file.
|
||||
|
||||
## Profile layout
|
||||
|
||||
The profile layout is great for personal websites and blogs. It puts the author's details front and centre by providing an image and links to social profiles.
|
||||
|
||||
|
||||
|
||||
The author information is provided in the languages configuration file. Refer to the [Getting Started]({{< ref "getting-started" >}}) and [Language Configuration]({{< ref "configuration##language-and-i18n" >}}) sections for parameter details.
|
||||
|
||||
Additionally, any Markdown content that is provided in the homepage content will be placed below the author profile. This allows extra flexibility for displaying a bio or other custom content using shortcodes.
|
||||
|
||||
To enable the profile layout, set `homepage.layout = "profile"` in the `params.toml` configuration file.
|
||||
|
||||
## Custom layout
|
||||
|
||||
If the built-in homepage layouts aren't sufficient for your needs, you have the option to provide your own custom layout. This allows you to have total control over the page content and essentially gives you a blank slate to work with.
|
||||
|
||||
To enable the custom layout, set `homepage.layout = "custom"` in the `params.toml` configuration file.
|
||||
|
||||
With the configuration value set, create a new `custom.html` file and place it in `layouts/partials/home/custom.html`. Now whatever is in the `custom.html` file will be placed in the content area of the site homepage. You may use whatever HTML, Tailwind, or Hugo templating functions you wish to define your layout.
|
||||
|
||||
To include [recent articles](#recent-articles) on the custom layout, use the `recent-articles.html` partial.
|
||||
|
||||
As an example, the [homepage]({{< ref "/" >}}) on this site uses the custom layout to allow toggling between the profile and page layouts. Visit the [GitHub repo](https://github.com/jpanther/congo/blob/dev/exampleSite/layouts/partials/home/custom.html) to see how it works.
|
||||
|
||||
## Recent articles
|
||||
|
||||
All homepage layouts have the option of displaying recent articles below the main page content. To enable this, simply set the `homepage.showRecent` setting to `true` in the `params.toml` configuration file.
|
||||
|
||||
|
||||
|
||||
The articles listed in this section are derived from the `mainSections` setting which allows for whatever content types you are using on your website. For instance, if you had content sections for _posts_ and _projects_ you could set this setting to `["posts", "projects"]` and all the articles in these two sections would be used to populate the recent list. The theme expects this setting to be an array so if you only use one section for all your content, you should set this accordingly: `["blog"]`.
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: "主页布局"
|
||||
date: 2020-08-13
|
||||
draft: false
|
||||
description: "在 Congo 主题中配置首页布局。"
|
||||
summary: "Congo 提供了一个完全灵活的首页布局，内置了模板并支持自定义。"
|
||||
slug: "homepage-layout"
|
||||
tags: ["homepage", "layouts", "docs"]
|
||||
---
|
||||
|
||||
Congo 提供了完全灵活的首页布局。有两个主要的模板可供选择，并提供额外的设置以调整设计。此外，您还可以提供自己的模板，完全掌控首页内容。
|
||||
|
||||
首页的布局由`params.toml`配置文件中的 `homepage.layout` 设置控制。另外，所有布局都可以选择包含[最近的文章](#recent-articles)列表。
|
||||
|
||||
## Page布局
|
||||
|
||||
默认布局是page布局。它只是一个显示您的 Markdown 内容的普通内容页面。非常适用于静态网站，并提供了很大的灵活性。
|
||||
|
||||
|
||||
|
||||
要启用页面布局，请在 `params.toml` 配置文件中设置 `homepage.layout = "page"`。
|
||||
|
||||
## Profile布局
|
||||
|
||||
profile布局非常适用于个人网站和博客。它通过提供图像和社交媒体链接，将作者的详细信息置于中心位置。
|
||||
|
||||
|
||||
|
||||
作者信息存储在语言配置文件中。有关参数详细信息，请参阅 [入门指南]({{< ref "getting-started" >}}) 和 [语言配置]({{< ref "configuration##language-and-i18n" >}}) 部分。
|
||||
|
||||
此外，提供在主页内容中的任何 Markdown 内容将显示在作者资料下方。这允许额外的灵活性，以使用 Shortcodes 显示生物或其他自定义内容。
|
||||
|
||||
要启用profile布局，请在 `params.toml` 配置文件中设置 `homepage.layout = "profile"`。
|
||||
|
||||
## custom布局
|
||||
|
||||
如果内置的首页布局不满足您的需求，您可以选择提供自己的自定义布局。这允许您完全掌控页面内容，基本上为您提供了一个空白的画布。
|
||||
|
||||
要启用自定义布局，请在 `params.toml` 配置文件中设置 `homepage.layout = "custom"`。
|
||||
|
||||
配置值设置后，创建一个新的 `custom.html` 文件并将其放置在 `layouts/partials/home/custom.html`。现在，`custom.html` 文件中的任何内容都将放置在站点首页的内容区域。您可以使用任何 HTML、Tailwind 或 Hugo 模板函数来定义布局。
|
||||
|
||||
要在自定义布局中包含[最近的文章](#recent-articles)，请使用 `recent-articles.html` 部分。
|
||||
|
||||
例如，这个站点的[首页]({{< ref "/" >}})使用自定义布局，允许在profile和page布局之间切换。访问 [GitHub 仓库](https://github.com/jpanther/congo/blob/dev/exampleSite/layouts/partials/home/custom.html) 查看它是如何工作的。
|
||||
|
||||
## 最近的文章
|
||||
|
||||
所有首页布局都可以选择在主页面内容下方显示最近的文章。要启用此功能，只需在 `params.toml` 配置文件中将 `homepage.showRecent` 设置为 `true`。
|
||||
|
||||
|
||||
|
||||
此部分中列出的文章来自 `mainSections` 设置，该设置允许使用您网站上使用的所有内容类型。例如，如果您有用于 _posts_ 和 _projects_ 的内容部分，可以将此设置设置为 `["posts", "projects"]`，所有这两个部分中的文章都将用于填充最近的列表。主题期望此设置为数组，因此如果您只使用一个部分来存储所有内容，您应相应地设置为 `["blog"]`。
|
||||
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 7.7 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 172 KiB |
BIN
Binary file not shown.
|
After Width: | Height: | Size: 341 KiB |
@@ -0,0 +1,146 @@
|
||||
---
|
||||
title: "ホスティングとデプロイ"
|
||||
date: 2020-08-07
|
||||
draft: false
|
||||
description: "Congoサイトのデプロイについて"
|
||||
summary: "Congoは、ほとんどすべてのデプロイシナリオに柔軟に対応できるように設計されています。プロジェクトを一般的なホスティングプラットフォームにデプロイする方法については、こちらをご覧ください。"
|
||||
slug: "hosting-deployment"
|
||||
tags: ["hosting", "deployment", "docs", "github", "netlify", "render"]
|
||||
---
|
||||
|
||||
Congoで構築したHugoウェブサイトを展開する方法はたくさんあります。このテーマは、ほとんどすべてのデプロイシナリオに柔軟に対応できるように設計されています。
|
||||
|
||||
Congoはテーマ全体で相対URLを使って構築されています。これにより、サイトをサブディレクトリやGitHub Pagesのようなホストに簡単に配置することができます。通常、 `config.toml` ファイルで `baseURL` パラメーターが設定されていれば、特別な設定は必要ありません。
|
||||
|
||||
Hugo公式ドキュメントの[Hosting and Deployment](https://gohugo.io/hosting-and-deployment/)は、あなたのサイトをデプロイする方法を学ぶのに最適な場所です。以下のセクションには、特定のプラットフォームで役立つ、特定のテーマ設定の詳細が含まれています。
|
||||
|
||||
**デプロイ先を選んでください:**
|
||||
|
||||
- [GitHub Pages](#github-pages)
|
||||
- [Netlify](#netlify)
|
||||
- [Render](#render)
|
||||
- [Cloudflare Pages](#cloudflare-pages)
|
||||
- [共有ホスティング、VPS、または自身のWebサーバー](#共有ホスティングvpsまたは自身のwebサーバー)
|
||||
|
||||
---
|
||||
|
||||
## GitHub Pages
|
||||
|
||||
GitHubでは、Actionsを使って[GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages)上でホスティングすることができます。この機能を有効にするには、リポジトリでPagesを有効にし、新しいActionsワークフローを作成してサイトをビルド、デプロイします。
|
||||
|
||||
ファイルはYAML形式で、GitHubリポジトリの `.github/workflows/` ディレクトリに置き、拡張子を `.yml` とします。
|
||||
|
||||
{{< alert >}}
|
||||
**重要:** `branches` とデプロイステップの `if` パラメーターにプロジェクトで使用しているブランチ名を正しく設定してください。
|
||||
{{< /alert >}}
|
||||
|
||||
```yaml
|
||||
# .github/workflows/gh-pages.yml
|
||||
|
||||
name: GitHub Pages
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
|
||||
jobs:
|
||||
build-deploy:
|
||||
runs-on: ubuntu-latest
|
||||
concurrency:
|
||||
group: ${{ github.workflow }}-${{ github.ref }}
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v3
|
||||
with:
|
||||
submodules: true
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Setup Hugo
|
||||
uses: peaceiris/actions-hugo@v2
|
||||
with:
|
||||
hugo-version: "latest"
|
||||
|
||||
- name: Build
|
||||
run: hugo --minify
|
||||
|
||||
- name: Deploy
|
||||
uses: peaceiris/actions-gh-pages@v3
|
||||
if: ${{ github.ref == 'refs/heads/main' }}
|
||||
with:
|
||||
github_token: ${{ secrets.GITHUB_TOKEN }}
|
||||
publish_branch: gh-pages
|
||||
publish_dir: ./public
|
||||
```
|
||||
|
||||
設定ファイルをGitHubにプッシュすると、アクションが自動的に実行されるはずです。初回は失敗するかもしれないので、GitHubリポジトリの **Settings > Pages** にアクセスして、ソースが正しいか確認してください。 `gh-pages` ブランチを使うように設定されているべきです。
|
||||
|
||||
{{< screenshot src="github-pages-source.jpg" alt="Screen capture of GitHub Pages source" >}}
|
||||
|
||||
設定が完了したら、アクションを再実行し、サイトを正しくビルドしてデプロイします。すべてが正常にデプロイされたことを確認するためにアクションログを参照することができます。
|
||||
|
||||
## Netlify
|
||||
|
||||
[Netlify](https://www.netlify.com)にデプロイするには、Netlify側に新しいデプロイサイトを作成し、ソースコードとリンクします。Netlify UIでは、ビルド設定は空白のまま、使用するドメインだけを設定する必要があります。
|
||||
|
||||
{{< screenshot src="netlify-build-settings.jpg" alt="Screen capture of Netlify build settings" >}}
|
||||
|
||||
次に、サイト・リポジトリのルートに `netlify.toml` ファイルを作成します:
|
||||
|
||||
```toml
|
||||
# netlify.toml
|
||||
|
||||
[build]
|
||||
command = "hugo mod get -u && hugo --gc --minify -b $URL"
|
||||
publish = "public"
|
||||
|
||||
[build.environment]
|
||||
HUGO_VERSION = "0.118.2"
|
||||
NODE_ENV = "production"
|
||||
GO_VERSION = "1.20"
|
||||
TZ = "UTC" # Set to preferred timezone
|
||||
|
||||
[context.production.environment]
|
||||
HUGO_ENV = "production"
|
||||
```
|
||||
|
||||
上の例は、CongoをHugoモジュールとしてデプロイすることを想定しています。別の方法でテーマをインストールした場合は、ビルドコマンドを `hugo --gc --minify -b $URL` に変更してください。
|
||||
|
||||
設定ファイルをリポジトリにプッシュすると、Netlifyは自動的にサイトをデプロイします。Netlify UIでデプロイのログを確認し、エラーがないかチェックすることができます。
|
||||
|
||||
## Render
|
||||
|
||||
[Render](https://render.com)へのデプロイは非常に簡単で、すべての設定はRender UIを介して行います。
|
||||
|
||||
新しい**静的サイト**を作成し、プロジェクトのコード・リポジトリにリンクします。そして、ビルドコマンドを `hugo --gc --minify` に、公開ディレクトリを `public` に設定するだけです。
|
||||
|
||||
{{< screenshot src="render-settings.jpg" alt="Screen capture of Render settings" >}}
|
||||
|
||||
あなたが変更をリポジトリにプッシュするたびに、自動的にビルドとデプロイを行います。
|
||||
|
||||
## Cloudflare Pages
|
||||
|
||||
CloudflareはHugoサイトをホストできる[Pages](https://pages.cloudflare.com/)サービスを提供しています。Gitリポジトリからサイトを構築し、CloudflareのCDNでホスティングします。[Hugoデプロイメントガイド](https://developers.cloudflare.com/pages/framework-guides/deploy-a-hugo-site)に従って始めてください。
|
||||
|
||||
The Rocket Loader™ feature offered by Cloudflare tries to speed up rendering of web pages with JavaScript, but it breaks the appearance switcher in the theme. It can also cause an annoying light/dark screen flash when browsing your site due to scripts loading in the wrong order.
|
||||
|
||||
Cloudflareが提供するRocket Loader™は、JavaScriptを使用したウェブページのレンダリングを高速化するものですが、テーマの外観スイッチャーを壊してしまいます。また、スクリプトのロード順序が正しくないため、サイトを閲覧する際に煩わしい画面の明暗が点滅することがあります。
|
||||
|
||||
これらの問題は下記を無効にすることで解決できます:
|
||||
|
||||
- [Cloudflare dashboard](https://dash.cloudflare.com)にアクセスする
|
||||
- あなたのドメイン名をクリックする
|
||||
- _Speed_ セクションの中にある _Optimization_ をクリックする
|
||||
- _Rocket Loader™_ までスクロールし、これを無効にする
|
||||
|
||||
Congoで構築されたサイトは、この機能を無効にしても十分に読み込みが速いです。
|
||||
|
||||
## 共有ホスティング、VPS、または自身のWebサーバー
|
||||
|
||||
従来のウェブホスティングを使用する場合や自分のサーバーにデプロイする場合は、Hugoサイトを構築してファイルをホストに転送するだけです。
|
||||
|
||||
`config.toml` の `baseURL` パラメーターに、あなたのウェブサイトのルートへの完全なURLが設定されていることを確認してください。
|
||||
|
||||
それから `hugo` コマンドを使ってサイトを構築し、出力ディレクトリの内容をウェブサーバのルートにコピーすれば準備完了です。デフォルトでは、出力ディレクトリは `public` という名前になっています。
|
||||
|
||||
_ホスティングプロバイダーが必要な場合は、[Vultr](https://www.vultr.com/?ref=8957394-8H)または[DigitalOcean](https://m.do.co/c/36841235e565)をチェックしてください。これらのアフィリエイトリンクを使用してサインアップすると、最大100ドルの無料クレジットがもらえます。_
|
||||
@@ -0,0 +1,148 @@
|
||||
---
|
||||
title: "Hosting & Deployment"
|
||||
date: 2020-08-07
|
||||
draft: false
|
||||
description: "Learn how to deploy a Congo site."
|
||||
summary: "Congo is designed to be flexible in almost any deployment scenario. Learn more about how to deploy your project to some common hosting platforms."
|
||||
slug: "hosting-deployment"
|
||||
tags: ["hosting", "deployment", "docs", "github", "netlify", "render"]
|
||||
---
|
||||
|
||||
There are many ways to deploy your Hugo website built with Congo. The theme is designed to be flexible in almost any deployment scenario.
|
||||
|
||||
Congo is built using relative URLs throughout the theme. This enables sites to easily be deployed to sub-folders and hosts like GitHub Pages. There's usually no special configuration required for this to work as long as the `baseURL` parameter has been configured in the `config.toml` file.
|
||||
|
||||
The official Hugo [Hosting and Deployment](https://gohugo.io/hosting-and-deployment/) docs are the best place to learn how to deploy your site. The sections below contain some specific theme configuration details that can help you deploy smoothly with certain providers.
|
||||
|
||||
**Choose your provider:**
|
||||
|
||||
- [GitHub Pages](#github-pages)
|
||||
- [Netlify](#netlify)
|
||||
- [Render](#render)
|
||||
- [Cloudflare Pages](#cloudflare-pages)
|
||||
- [Shared hosting, VPS or private web server](#shared-hosting-vps-or-private-web-server)
|
||||
|
||||
---
|
||||
|
||||
## GitHub Pages
|
||||
|
||||
GitHub allows hosting on [GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages) using Actions. To enable this functionality, enable Pages on your repo and create a new Actions workflow to build and deploy your site.
|
||||
|
||||
The file needs to be in YAML format, placed within the `.github/workflows/` directory of your GitHub repository and named with a `.yml` extension.
|
||||
|
||||
{{< alert >}}
|
||||
**Important:** Ensure you set the correct branch name under `branches` and in the deploy step `if` parameter to the source branch used in your project.
|
||||
{{< /alert >}}
|
||||
|
||||
```yaml
|
||||
# .github/workflows/gh-pages.yml
|
||||
|
||||
name: GitHub Pages
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
|
||||
jobs:
|
||||
build-deploy:
|
||||
runs-on: ubuntu-latest
|
||||
concurrency:
|
||||
group: ${{ github.workflow }}-${{ github.ref }}
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v3
|
||||
with:
|
||||
submodules: true
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Setup Hugo
|
||||
uses: peaceiris/actions-hugo@v2
|
||||
with:
|
||||
hugo-version: "latest"
|
||||
extended: true
|
||||
|
||||
- name: Build
|
||||
run: hugo --minify
|
||||
|
||||
- name: Deploy
|
||||
uses: peaceiris/actions-gh-pages@v3
|
||||
if: ${{ github.ref == 'refs/heads/main' }}
|
||||
with:
|
||||
github_token: ${{ secrets.GITHUB_TOKEN }}
|
||||
publish_branch: gh-pages
|
||||
publish_dir: ./public
|
||||
```
|
||||
|
||||
Push the config file to GitHub and the action should automatically run. It may fail the first time and you'll need to visit the **Settings > Pages** section of your GitHub repo to check the source is correct. It should be set to use the `gh-pages` branch.
|
||||
|
||||
{{< screenshot src="github-pages-source.jpg" alt="Screen capture of GitHub Pages source settings" >}}
|
||||
|
||||
You should also visit the **Settings > Actions > General** section and check that the workflow permissions allow actions to make changes to your repo.
|
||||
|
||||
{{< screenshot src="github-workflow-permissions.jpg" alt="Screen capture of GitHub Workflow Permissions settings" >}}
|
||||
|
||||
Once the settings are configured, re-run the action and the site should build and deploy correctly. You can consult the actions log to check everything deployed successfully.
|
||||
|
||||
## Netlify
|
||||
|
||||
To deploy to [Netlify](https://www.netlify.com), create a new continuous deployment site and link it to your source code. The build settings can be left blank in the Netlify UI. You will only need to configure the domain you'll be using.
|
||||
|
||||
{{< screenshot src="netlify-build-settings.jpg" alt="Screen capture of Netlify build settings" >}}
|
||||
|
||||
Then in the root of your site repository, create a `netlify.toml` file:
|
||||
|
||||
```toml
|
||||
# netlify.toml
|
||||
|
||||
[build]
|
||||
command = "hugo mod get -u && hugo --gc --minify -b $URL"
|
||||
publish = "public"
|
||||
|
||||
[build.environment]
|
||||
HUGO_VERSION = "0.119.0"
|
||||
NODE_ENV = "production"
|
||||
TZ = "UTC" # Set to preferred timezone
|
||||
|
||||
[context.production.environment]
|
||||
HUGO_ENV = "production"
|
||||
```
|
||||
|
||||
This configuration assumes you are deploying Congo as a Hugo module. If you have installed the theme using another method, change the build command to simply `hugo --gc --minify -b $URL`.
|
||||
|
||||
When you push the config file to your repo, Netlify should automatically deploy your site. You can check the deploy logs in the Netlify UI to check for any errors.
|
||||
|
||||
## Render
|
||||
|
||||
Deploying to [Render](https://render.com) is very straightforward and all configuration is via the Render UI.
|
||||
|
||||
Create a new **Static Site** and link it to your project's code repository. Then simply configure the build command to be `hugo --gc --minify` and publish directory to be `public`.
|
||||
|
||||
{{< screenshot src="render-settings.jpg" alt="Screen capture of Render settings" >}}
|
||||
|
||||
The site will automatically build and deploy whenever you push a change to your repo.
|
||||
|
||||
## Cloudflare Pages
|
||||
|
||||
Cloudflare offers the [Pages](https://pages.cloudflare.com/) service that can host Hugo blogs. It builds the site from a git repository and then hosts it on Cloudflare's CDN. Follow their [Hugo deployment guide](https://developers.cloudflare.com/pages/framework-guides/deploy-a-hugo-site) to get started.
|
||||
|
||||
The Rocket Loader™ feature offered by Cloudflare tries to speed up rendering of web pages with JavaScript, but it breaks the appearance switcher in the theme. It can also cause an annoying light/dark screen flash when browsing your site due to scripts loading in the wrong order.
|
||||
|
||||
This problem can be fixed by disabling it:
|
||||
|
||||
- Go to the [Cloudflare dashboard](https://dash.cloudflare.com)
|
||||
- Click on your domain name in the list
|
||||
- Click _Optimization_ in the _Speed_ section
|
||||
- Scroll down to _Rocket Loader™_ and disable it
|
||||
|
||||
Hugo sites built with Congo still load very quickly, even with this feature disabled.
|
||||
|
||||
## Shared hosting, VPS or private web server
|
||||
|
||||
Using traditional web hosting, or deploying to your own web server, is as simple as building your Hugo site and transferring the files to your host.
|
||||
|
||||
Make sure that the `baseURL` parameter in `config.toml` is set to the full URL to the root of your website (including any sub domains or sub-folders).
|
||||
|
||||
Then build your site using `hugo` and copy the contents of the output directory to the root of your web server and you will be ready to go. By default, the output directory is named `public`.
|
||||
|
||||
_If you need a hosting provider, check out [Vultr](https://www.vultr.com/?ref=8957394-8H) or [DigitalOcean](https://m.do.co/c/36841235e565). Signing up using these affiliate links will give you up to $100 in free credit so you can try the service._
|
||||
@@ -0,0 +1,148 @@
|
||||
---
|
||||
title: "部署"
|
||||
date: 2020-08-07
|
||||
draft: false
|
||||
description: "学习如何部署 Congo 网站。"
|
||||
summary: "Congo 被设计为在几乎任何部署场景中都具有灵活性。了解如何将项目部署到一些常见的主机平台。"
|
||||
slug: "hosting-deployment"
|
||||
tags: ["hosting", "deployment", "docs", "github", "netlify", "render"]
|
||||
---
|
||||
|
||||
有许多方法可以部署使用 Congo 构建的 Hugo 网站。该主题被设计为在几乎任何部署场景中都具有灵活性。
|
||||
|
||||
Congo 在整个主题中使用相对 URL。这使得站点可以轻松部署到子文件夹和像 GitHub Pages 这样的主机。通常情况下，只要在 config.toml 文件中配置了 baseURL 参数，就不需要特殊的配置。
|
||||
|
||||
要学习如何部署您的站点，Hugo 官方的主机与部署文档是最佳选择。下面的部分包含一些特定的主题配置细节，可以帮助您在某些提供商那里顺利部署。
|
||||
|
||||
**选择您的提供商：**
|
||||
|
||||
- [GitHub Pages](#github-pages)
|
||||
- [Netlify](#netlify)
|
||||
- [Render](#render)
|
||||
- [Cloudflare Pages](#cloudflare-pages)
|
||||
- [共享主机、VPS 或私有 Web 服务器](#shared-hosting-vps-or-private-web-server)
|
||||
|
||||
---
|
||||
|
||||
## GitHub Pages
|
||||
|
||||
GitHub 允许使用 [GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages) 在 Actions 中托管网站。要启用此功能，请在您的存储库上启用 Pages，并创建一个新的 Actions 工作流来构建和部署您的站点。
|
||||
|
||||
该文件需要采用 YAML 格式，放置在您的 GitHub 存储库的 `.github/workflows/` 目录中，并以 `.yml` 扩展名命名。
|
||||
|
||||
{{< alert >}}
|
||||
**重要提示：**确保在 `branches` 下设置正确的分支名称，并在部署步骤的 `if` 参数中设置用于项目的源分支。
|
||||
{{< /alert >}}
|
||||
|
||||
```yaml
|
||||
# .github/workflows/gh-pages.yml
|
||||
|
||||
name: GitHub Pages
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
|
||||
jobs:
|
||||
build-deploy:
|
||||
runs-on: ubuntu-latest
|
||||
concurrency:
|
||||
group: ${{ github.workflow }}-${{ github.ref }}
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v3
|
||||
with:
|
||||
submodules: true
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Setup Hugo
|
||||
uses: peaceiris/actions-hugo@v2
|
||||
with:
|
||||
hugo-version: "latest"
|
||||
|
||||
- name: Build
|
||||
run: hugo --minify
|
||||
|
||||
- name: Deploy
|
||||
uses: peaceiris/actions-gh-pages@v3
|
||||
if: ${{ github.ref == 'refs/heads/main' }}
|
||||
with:
|
||||
github_token: ${{ secrets.GITHUB_TOKEN }}
|
||||
publish_branch: gh-pages
|
||||
publish_dir: ./public
|
||||
```
|
||||
|
||||
将配置文件推送到 GitHub，操作应会自动运行。第一次可能会失败，您需要访问 GitHub 存储库的 **Settings > Pages** 部分以检查源是否正确。它应该设置为使用 `gh-pages` 分支。
|
||||
|
||||
{{< screenshot src="github-pages-source.jpg" alt="GitHub Pages source settings 屏幕截图" >}}
|
||||
|
||||
您还应该访问 **Settings > Actions > General** 部分，检查工作流权限是否允许操作对您的存储库进行更改。
|
||||
|
||||
{{< screenshot src="github-workflow-permissions.jpg" alt="GitHub Workflow Permissions 设置屏幕截图" >}}
|
||||
|
||||
配置设置后，重新运行操作，站点应该能够正确构建和部署。您可以查看操作日志以确保一切都成功部署。
|
||||
|
||||
## Netlify
|
||||
|
||||
要部署到 [Netlify](https://www.netlify.com)，创建一个新的持续部署站点并将其链接到您的源代码。在 Netlify UI 中，可以将构建设置留空。您只需要配置将要使用的域。
|
||||
|
||||
{{< screenshot src="netlify-build-settings.jpg" alt="Netlify 构建设置屏幕截图" >}}
|
||||
|
||||
然后在您站点存储库的根目录中，创建一个 `netlify.toml` 文件：
|
||||
|
||||
```toml
|
||||
# netlify.toml
|
||||
|
||||
[build]
|
||||
command = "hugo mod get -u && hugo --gc --minify -b $URL"
|
||||
publish = "public"
|
||||
|
||||
[build.environment]
|
||||
HUGO_VERSION = "0.118.2"
|
||||
NODE_ENV = "production"
|
||||
GO_VERSION = "1.20"
|
||||
TZ = "UTC" # Set to preferred timezone
|
||||
|
||||
[context.production.environment]
|
||||
HUGO_ENV = "production"
|
||||
```
|
||||
|
||||
此配置假设您正在将 Congo 部署为 Hugo 模块。如果您使用其他方法安装了主题，请将构建命令更改为简单的 `hugo --gc --minify -b $URL`。
|
||||
|
||||
当您将配置文件推送到存储库时，Netlify 应会自动部署您的站点。您可以在 Netlify UI 中检查部署日志以查看是否有任何错误。
|
||||
|
||||
## Render
|
||||
|
||||
部署到 [Render](https://render.com) 非常简单，所有配置都通过 Render UI 进行。
|
||||
|
||||
创建一个新的 **Static Site** 并将其链接到项目的代码存储库。然后简单地配置构建命令为 `hugo --gc --minify`，发布目录为 `public`。
|
||||
|
||||
{{< screenshot src="render-settings.jpg" alt="Render 设置屏幕截图" >}}
|
||||
|
||||
只要您对存储库进行更改，站点将自动构建和部署。
|
||||
|
||||
## Cloudflare Pages
|
||||
|
||||
Cloudflare 提供 [Pages](https://pages.cloudflare.com/) 服务，可以托管 Hugo 博客。它从 git 存储库构建站点，然后在 Cloudflare 的 CDN 上托管。请按照他们的 [Hugo 部署指南](https://developers.cloudflare.com/pages/framework-guides/deploy-a-hugo-site) 开始使用。
|
||||
|
||||
Cloudflare 提供的 Rocket Loader™ 功能试图加速带有 JavaScript 的网页渲染，但它会破坏主题中的外观切换器。它还可能导致浏览站点时因脚本加载顺序错误而出现令人讨厌的浅色/深色屏幕闪烁。
|
||||
|
||||
可以通过禁用此功能来解决这个问题：
|
||||
|
||||
- 转到 [Cloudflare 仪表板](https://dash.cloudflare.com)
|
||||
- 在列表中点击您的域名
|
||||
- 在 _Speed_ 部分中点击 _Optimization_
|
||||
- 滚动到 _Rocket Loader™_ 并禁用它
|
||||
|
||||
使用 Congo 构建的 Hugo 站点即使禁用此功能仍然加载非常快。
|
||||
|
||||
## 共享托管、VPS 或私有 Web 服务器
|
||||
|
||||
使用传统的 Web 托管，或部署到自己的 Web 服务器，只需构建 Hugo 站点并将文件传输到主机即可。
|
||||
|
||||
确保 `config.toml` 中的 `baseURL` 参数设置为您网站根目录的完整 URL（包括任何子域或子文件夹）。
|
||||
|
||||
然后使用 `hugo` 构建您的站点，将输出目录的内容复制到 Web 服务器的根目录，您就准备好了。默认情况下，输出目录的名称为 `public`。
|
||||
|
||||
_如果您需要托管提供商，请查看 [Vultr](https://www.vultr.com/?ref=8957394-8H) 或 [DigitalOcean](https://m.do.co/c/36841235e565)。使用这些推广链接注册将为您提供最多 100 美元的免费信用，以便您可以尝试该服务。_
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 72 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 94 KiB |
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 6.4 KiB |
@@ -0,0 +1,178 @@
|
||||
---
|
||||
title: "インストール"
|
||||
date: 2020-08-16
|
||||
draft: false
|
||||
description: "Congoをインストール"
|
||||
summary: "全く何もない状態からHugoとCongoを使い始める方法を紹介します。初めての方はここから始めるのが最適です。"
|
||||
slug: "installation"
|
||||
tags: ["installation", "docs"]
|
||||
---
|
||||
|
||||
Hugoの標準的な[Quick Start](https://gohugo.io/getting-started/quick-start/)に従うだけで、すぐに使い始めることができます。
|
||||
|
||||
詳しいインストール方法は以下をご覧ください。[更新のインストール](#更新のインストール)についても解説しています。
|
||||
|
||||
## インストール
|
||||
|
||||
この手順を読めば、HugoとCongoをまったく何もない状態から使い始めることができます。このガイドで述べられている依存関係のほとんどは、あなたのプラットフォームで選択したパッケージマネージャを使ってインストールできます。
|
||||
|
||||
### Hugoのインストール
|
||||
|
||||
Hugoを使ったことがない場合は、[インストール](https://gohugo.io/getting-started/installing)する必要があります。すでにインストールされているかは、 `hugo version` コマンドで確認できます。
|
||||
|
||||
{{< alert >}}
|
||||
CongoはHugoの最新機能の一部を利用しているため、 **Hugoバージョン0.87.0** 以降を使用していることを確認してください。
|
||||
{{< /alert >}}
|
||||
|
||||
[Hugo docs](https://gohugo.io/getting-started/installing)に、あなたのプラットフォーム用の詳しいインストール手順があります。
|
||||
|
||||
### 新しいサイトを作成
|
||||
|
||||
コマンド `hugo new site mywebsite` を実行して、 `mywebsite` というディレクトリに新しいHugoサイトを作成します。
|
||||
|
||||
プロジェクト・ディレクトリは好きな名前をつけることができますが、以下では説明の便宜上 `mywebsite` という名前を使います。それ以外の名前を使う場合は、適宜置き換えてください。
|
||||
|
||||
### Congoのダウンロード
|
||||
|
||||
CongoをHugoのウェブサイトにインストールするには、いくつかの方法があります。インストールとメンテナンスが最も簡単なものから最も難しいものまで、次のとおりです:
|
||||
|
||||
- [Hugo module](#install-using-hugo) (recommended)
|
||||
- [Git submodule](#install-using-git)
|
||||
- [Manual file copy](#install-manually)
|
||||
|
||||
わからない場合は、 _Hugo module_ の方法を選んでください。
|
||||
|
||||
#### Install using Hugo
|
||||
|
||||
この方法はテーマを最新の状態に保つのに最も早く、簡単です。Hugoはモジュールの初期化と管理に **Go** を使うので、先に進む前に `go` がインストールされていることを確認する必要があります。
|
||||
|
||||
1. [Download](https://golang.org/dl/)をクリックし、Goをインストールしてください。すでにインストールされているかは、 `go version` コマンドで確認できます。
|
||||
|
||||
{{< alert >}}
|
||||
Hugoがモジュールを正しく動作させるために、 **Goバージョン1.12** 以降を使用していることを確認してください。
|
||||
{{< /alert >}}
|
||||
|
||||
2. Hugoプロジェクトのディレクトリ (上記で作成したもの)から、ウェブサイトのモジュールを初期化します:
|
||||
|
||||
```shell
|
||||
# GitHubでプロジェクトを管理している場合
|
||||
hugo mod init github.com/<username>/<repo-name>
|
||||
|
||||
# ローカルでプロジェクトを管理している場合
|
||||
hugo mod init my-project
|
||||
```
|
||||
|
||||
3. Congoを設定に追加するには、 `config/_default/module.toml` ファイルを新規作成し、以下を追加します:
|
||||
|
||||
```toml
|
||||
[[imports]]
|
||||
path = "github.com/jpanther/congo/v2"
|
||||
```
|
||||
|
||||
4. `hugo server` を使用してサーバーを起動すると、テーマが自動的にダウンロードされます。
|
||||
5. [テーマ設定ファイルのセットアップ](#テーマ設定ファイルのセットアップ)に進みます。
|
||||
|
||||
#### Install using Git
|
||||
|
||||
この方法では、ローカルマシンに **Git** がインストールされていることを確認する必要があります。
|
||||
|
||||
Hugoプロジェクトのディレクトリ（上で作成したもの）に移動し、新しく `git` リポジトリを初期化してCongoをサブモジュールとして追加します。
|
||||
|
||||
```bash
|
||||
cd mywebsite
|
||||
git init
|
||||
git submodule add -b stable https://github.com/jpanther/congo.git themes/congo
|
||||
```
|
||||
|
||||
[テーマ設定ファイルのセットアップ](#テーマ設定ファイルのセットアップ)に進みます。
|
||||
|
||||
#### Install manually
|
||||
|
||||
1. Congoのソースコードの最新リリースをダウンロードする。
|
||||
|
||||
{{< button href="https://github.com/jpanther/congo/releases/latest" target="_blank" >}}Download from Github{{< /button >}}
|
||||
|
||||
2. アーカイブを解凍し、ディレクトリ名を `congo` に変更して、Hugoプロジェクト内の `themes/` ディレクトリに移動します。
|
||||
3. [テーマ設定ファイルのセットアップ](#テーマ設定ファイルのセットアップ)に進みます。
|
||||
|
||||
### テーマ設定ファイルのセットアップ
|
||||
|
||||
ウェブサイトのルートディレクトリで、Hugoによって生成された `config.toml` ファイルを削除します。テーマの `*.toml` 設定ファイルを `config/_default/` ディレクトリにコピーします。これでCongoの設定がすべて正しくなり、必要に応じてCongoを簡単にカスタマイズできるようになります。
|
||||
|
||||
{{< alert >}}
|
||||
**注記:** プロジェクト内にすでに `module.toml` ファイルが存在する場合は上書きしないでください！
|
||||
{{< /alert >}}
|
||||
|
||||
テーマのインストール方法によって、テーマの設定ファイルは異なる場所にあります。:
|
||||
|
||||
- **Hugo Modules:** Hugoのキャッシュディレクトリ、またはGitHubから[コピーをダウンロード](https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/jpanther/congo/tree/stable/config/_default)してください。
|
||||
- **Git submodule or Manual install:** `themes/congo/config/_default`
|
||||
|
||||
ファイルをコピーしたら、設定ディレクトリは以下のようになっているはずです:
|
||||
|
||||
```shell
|
||||
config/_default/
|
||||
├─ config.toml
|
||||
├─ markup.toml
|
||||
├─ menus.toml
|
||||
├─ module.toml # if you installed using Hugo Modules
|
||||
└─ params.toml
|
||||
```
|
||||
|
||||
{{< alert >}}
|
||||
**重要:** Hugoモジュールを使ってCongoをインストールしなかった場合は、 `config.toml` ファイルの先頭に `theme = "congo"` という行を追加する必要があります。
|
||||
{{< /alert >}}
|
||||
|
||||
### Next steps
|
||||
|
||||
これで基本的なCongoのインストールは完了です。テーマの設定についての詳細は、[はじめに]({{< ref "getting-started" >}})セクションに進んでください。
|
||||
|
||||
---
|
||||
|
||||
## 更新のインストール
|
||||
|
||||
時折、テーマに修正を適用し、新しい機能を追加した[新しいリリース](https://github.com/jpanther/congo/releases)が投稿されます。これらの変更を利用するには、ウェブサイトのテーマファイルを更新する必要があります。
|
||||
|
||||
この方法は、テーマを最初にインストールしたときに選択したインストール方法によって異なります。各方法の手順は以下にあります。
|
||||
|
||||
- [Hugo module](#update-using-hugo)
|
||||
- [Git submodule](#update-using-git)
|
||||
- [Manual file copy](#update-manually)
|
||||
|
||||
### Update using Hugo
|
||||
|
||||
Hugoはモジュールのアップデートをとても簡単にしてくれます。プロジェクトディレクトリに移動して、以下のコマンドを実行するだけです:
|
||||
|
||||
```shell
|
||||
hugo mod get -u
|
||||
```
|
||||
|
||||
Hugoはプロジェクトに必要なモジュールを自動的にアップデートします。これは `module.toml` と `go.mod` ファイルを検査することで行われます。アップデートに問題がある場合は、これらのファイルが正しく設定されているか確認してください。
|
||||
|
||||
その後、サイトを再構築し、すべてが期待通りに動作することを確認してください。
|
||||
|
||||
### Update using git
|
||||
|
||||
Gitサブモジュールは `git` コマンドを使って更新できます。次のコマンドを実行するだけで、テーマの最新バージョンがローカルリポジトリにダウンロードされます:
|
||||
|
||||
```shell
|
||||
git submodule update --remote --merge
|
||||
```
|
||||
|
||||
サブモジュールのアップデートが完了したら、サイトを再構築し、すべてが期待通りに動作することを確認してください。
|
||||
|
||||
### Update manually
|
||||
|
||||
Congoを手動で更新するには、テーマの最新コピーをダウンロードして、プロジェクト内の古いバージョンを置き換える必要があります。
|
||||
|
||||
{{< alert >}}
|
||||
テーマファイルに対して行ったローカルでのカスタマイズは、この処理中に失われますのでご注意ください。
|
||||
{{< /alert >}}
|
||||
|
||||
1. Congoのソースコードの最新リリースをダウンロードする。
|
||||
|
||||
{{< button href="https://github.com/jpanther/congo/releases/latest" target="_blank" >}}Download from Github{{< /button >}}
|
||||
|
||||
2. アーカイブを解凍し、ディレクトリ名を `congo` に変更して、Hugoプロジェクトのルートディレクトリ内の `themes/` ディレクトリに移動します。すべてのテーマファイルを置き換えるには、既存のディレクトリを上書きする必要があります。
|
||||
|
||||
3. サイトを再構築し、すべてが期待通りに動作することを確認してください。
|
||||
@@ -0,0 +1,182 @@
|
||||
---
|
||||
title: "Installation"
|
||||
date: 2020-08-16
|
||||
draft: false
|
||||
description: "How to install the Congo theme."
|
||||
summary: "Learn how to get up and running using Hugo and Congo from a completely blank state. It's the best place to start if you're a new user."
|
||||
slug: "installation"
|
||||
tags: ["installation", "docs"]
|
||||
---
|
||||
|
||||
Simply follow the standard Hugo [Quick Start](https://gohugo.io/getting-started/quick-start/) procedure to get up and running quickly.
|
||||
|
||||
Detailed installation instructions can be found below. Instructions for [updating the theme](#installing-updates) are also available.
|
||||
|
||||
## Installation
|
||||
|
||||
These instructions will get you up and running using Hugo and Congo from a completely blank state. Most of the dependencies mentioned in this guide can be installed using the package manager of choice for your platform.
|
||||
|
||||
### Install Hugo
|
||||
|
||||
If you haven't used Hugo before, you will need to [install it onto your local machine](https://gohugo.io/getting-started/installing). You can check if it's already installed by running the command `hugo version`.
|
||||
|
||||
{{< alert >}}
|
||||
Make sure you are using **Hugo extended version 0.87.0** or later as the theme takes advantage of some of the latest Hugo features.
|
||||
{{< /alert >}}
|
||||
|
||||
You can find detailed installation instructions for your platform in the [Hugo docs](https://gohugo.io/getting-started/installing).
|
||||
|
||||
### Create a new site
|
||||
|
||||
Run the command `hugo new site mywebsite` to create a new Hugo site in a directory named `mywebsite`.
|
||||
|
||||
Note that you can name the project directory whatever you choose, but the instructions below will assume it's named `mywebsite`. If you use a different name, be sure to substitute it accordingly.
|
||||
|
||||
### Download the Congo theme
|
||||
|
||||
There several different ways to install the Congo theme into your Hugo website. From easiest to most difficult to install and maintain, they are:
|
||||
|
||||
- [Hugo module](#install-using-hugo) (recommended)
|
||||
- [Git submodule](#install-using-git)
|
||||
- [Manual file copy](#install-manually)
|
||||
|
||||
If you're unsure, choose the Hugo module method.
|
||||
|
||||
#### Install using Hugo
|
||||
|
||||
This method is the quickest and easiest for keeping the theme up-to-date. Hugo uses **Go** to initialise and manage modules so you need to ensure you have `go` installed before proceeding.
|
||||
|
||||
1. [Download](https://golang.org/dl/) and install Go. You can check if it's already installed by using the command `go version`.
|
||||
|
||||
{{< alert >}}
|
||||
Make sure you are using **Go version 1.12** or later as Hugo requires this for modules to work correctly.
|
||||
{{< /alert >}}
|
||||
|
||||
2. From your Hugo project directory (that you created above), initialise modules for your website:
|
||||
|
||||
```shell
|
||||
# If you're managing your project on GitHub
|
||||
hugo mod init github.com/<username>/<repo-name>
|
||||
|
||||
# If you're managing your project locally
|
||||
hugo mod init my-project
|
||||
```
|
||||
|
||||
3. Add the theme to your configuration by creating a new file `config/_default/module.toml` and adding the following:
|
||||
|
||||
```toml
|
||||
[[imports]]
|
||||
path = "github.com/jpanther/congo/v2"
|
||||
```
|
||||
|
||||
4. Start your server using `hugo server` and the theme will be downloaded automatically.
|
||||
5. Continue to [set up the theme configuration files](#set-up-theme-configuration-files).
|
||||
|
||||
#### Install using git
|
||||
|
||||
For this method you'll need to ensure you have **Git** installed on your local machine.
|
||||
|
||||
Change into the directory for your Hugo website (that you created above), initialise a new `git` repository and add Congo as a submodule.
|
||||
|
||||
```bash
|
||||
cd mywebsite
|
||||
git init
|
||||
git submodule add -b stable https://github.com/jpanther/congo.git themes/congo
|
||||
```
|
||||
|
||||
Then continue to [set up the theme configuration files](#set-up-theme-configuration-files).
|
||||
|
||||
#### Install manually
|
||||
|
||||
1. Download the latest release of the theme source code.
|
||||
|
||||
{{< button href="https://github.com/jpanther/congo/releases/latest" target="_blank" >}}Download from Github{{< /button >}}
|
||||
|
||||
2. Extract the archive, rename the folder to `congo` and move it to the `themes/` directory inside your Hugo project's root folder.
|
||||
3. Continue to [set up the theme configuration files](#set-up-theme-configuration-files).
|
||||
|
||||
### Set up theme configuration files
|
||||
|
||||
In the root folder of your website, delete the `config.toml` file that was generated by Hugo. Copy the `*.toml` config files from the theme into your `config/_default/` folder. This will ensure you have all the correct theme settings and will enable you to easily customise the theme to your needs.
|
||||
|
||||
{{< alert >}}
|
||||
**Note:** You should not overwrite the `module.toml` file if one already exists in your project!
|
||||
{{< /alert >}}
|
||||
|
||||
Depending on how you installed the theme you will find the theme config files in different places:
|
||||
|
||||
- **Hugo Modules:** In the Hugo cache directory, or [download a copy](https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/jpanther/congo/tree/stable/config/_default) from GitHub
|
||||
- **Git submodule or Manual install:** `themes/congo/config/_default`
|
||||
|
||||
Once you've copied the files, your config folder should look like this:
|
||||
|
||||
```shell
|
||||
config/_default/
|
||||
├─ config.toml
|
||||
├─ markup.toml
|
||||
├─ menus.toml
|
||||
├─ module.toml # if you installed using Hugo Modules
|
||||
└─ params.toml
|
||||
```
|
||||
|
||||
{{< alert >}}
|
||||
**Important:** If you didn't use Hugo Modules to install Congo, you must add the line `theme = "congo"` to the top of your `config.toml` file.
|
||||
{{< /alert >}}
|
||||
|
||||
### Next steps
|
||||
|
||||
The basic Congo installation is now complete. Continue to the [Getting Started]({{< ref "getting-started" >}}) section to learn more about configuring the theme.
|
||||
|
||||
---
|
||||
|
||||
## Installing updates
|
||||
|
||||
From time to time there will be [new releases](https://github.com/jpanther/congo/releases) posted that apply fixes and add new functionality to the theme. In order to take advantage of these changes, you will need to update the theme files on your website.
|
||||
|
||||
How you go about this will depend on the installation method you chose when the theme was originally installed. Instructions for each method can be found below.
|
||||
|
||||
- [Hugo module](#update-using-hugo)
|
||||
- [Git submodule](#update-using-git)
|
||||
- [Manual file copy](#update-manually)
|
||||
|
||||
### Update using Hugo
|
||||
|
||||
Hugo makes updating modules super easy. Simply change into your project directory and execute the following command:
|
||||
|
||||
```shell
|
||||
hugo mod get -u
|
||||
```
|
||||
|
||||
Hugo will automatically update any modules that are required for your project. It does this by inspecting your `module.toml` and `go.mod` files. If you have any issues with the update, check to ensure these files are still configured correctly.
|
||||
|
||||
Then simply rebuild your site and check everything works as expected.
|
||||
|
||||
{{< alert >}}
|
||||
When updating modules, sometimes Hugo will cache an older version of the theme. If this happens, clear your local cache by using the `hugo mod clean` command and then rebuild your site.
|
||||
{{< /alert >}}
|
||||
|
||||
### Update using git
|
||||
|
||||
Git submodules can be updated using the `git` command. Simply execute the following command and the latest version of the theme will be downloaded into your local repository:
|
||||
|
||||
```shell
|
||||
git submodule update --remote --merge
|
||||
```
|
||||
|
||||
Once the submodule has been updated, rebuild your site and check everything works as expected.
|
||||
|
||||
### Update manually
|
||||
|
||||
Updating Congo manually requires you to download the latest copy of the theme and replace the old version in your project.
|
||||
|
||||
{{< alert >}}
|
||||
Note that any local customisations you have made to the theme files will be lost during this process.
|
||||
{{< /alert >}}
|
||||
|
||||
1. Download the latest release of the theme source code.
|
||||
|
||||
{{< button href="https://github.com/jpanther/congo/releases/latest" target="_blank" >}}Download from Github{{< /button >}}
|
||||
|
||||
2. Extract the archive, rename the folder to `congo` and move it to the `themes/` directory inside your Hugo project's root folder. You will need to overwrite the existing directory to replace all the theme files.
|
||||
|
||||
3. Rebuild your site and check everything works as expected.
|
||||
@@ -0,0 +1,173 @@
|
||||
---
|
||||
title: "安装"
|
||||
date: 2020-08-16
|
||||
draft: false
|
||||
description: "如何安装Congo主题"
|
||||
summary: "学习如何从0开始使用Hugo和Congo。如果您是新用户，这是开始的最佳位置。"
|
||||
slug: "installation"
|
||||
tags: ["installation", "docs"]
|
||||
---
|
||||
|
||||
只需按照标准的Hugo [快速入门](https://gohugo.io/getting-started/quick-start/)流程，即可快速启动和运行。
|
||||
|
||||
下面提供了详细的安装说明。还有关于[更新主题](#installing-updates)的说明。
|
||||
|
||||
## 安装
|
||||
|
||||
以下说明将帮助您从0使用Hugo和Congo启动和运行。此指南中提到的大多数依赖项可以使用您平台上选择的包管理器进行安装。
|
||||
|
||||
### 安装Hugo
|
||||
|
||||
如果您以前没有使用过Hugo，您需要[将其安装到本地计算机上](https://gohugo.io/getting-started/installing)。您可以通过运行命令 `hugo version` 来检查是否已经安装。
|
||||
|
||||
{{< alert >}}
|
||||
确保您使用的是 **Hugo版本0.87.0** 或更高版本，因为该主题利用了一些最新的Hugo功能。
|
||||
{{< /alert >}}
|
||||
|
||||
您可以在[Hugo文档](https://gohugo.io/getting-started/installing)中找到有关您平台的详细安装说明。
|
||||
|
||||
### 创建新站点
|
||||
|
||||
运行命令 `hugo new site mywebsite` 在名为 `mywebsite` 的目录中创建一个新的Hugo站点。
|
||||
|
||||
请注意，您可以将项目目录命名为任何您选择的名称，但下面的说明将假定其名称为 `mywebsite`。如果使用其他名称，请确保相应地进行替换。
|
||||
|
||||
### 下载Congo主题
|
||||
|
||||
有几种不同的方法可以将Congo主题安装到您的Hugo网站中。从最简单到最难安装和维护的方式，它们分别是：
|
||||
|
||||
- [Hugo模块](#使用hugo安装)（推荐）
|
||||
- [Git子模块](#使用git安装)
|
||||
- [手动文件复制](#手动安装)
|
||||
|
||||
如果不确定，请选择Hugo模块方法。
|
||||
|
||||
#### 使用Hugo安装
|
||||
|
||||
这种方法是保持主题最新的最快最简单的方法。Hugo使用 **Go** 来初始化和管理模块，因此在继续之前，您需要确保已安装 `go`。
|
||||
|
||||
1. [下载](https://golang.org/dl/)并安装Go。您可以通过使用命令 `go version` 来检查是否已安装。
|
||||
|
||||
{{< alert >}}
|
||||
确保您使用的是 **Go版本1.12** 或更高版本，因为Hugo需要这个版本以使模块正常工作。
|
||||
{{< /alert >}}
|
||||
|
||||
2. 从Hugo项目目录（您上面创建的目录）中，为您的网站初始化模块：
|
||||
|
||||
```shell
|
||||
# 如果您在GitHub上管理项目
|
||||
hugo mod init github.com/<username>/<repo-name>
|
||||
|
||||
# 如果您在本地管理项目
|
||||
hugo mod init my-project
|
||||
```
|
||||
|
||||
3. 通过创建一个新文件 `config/_default/module.toml` 并添加以下内容，将主题添加到配置中：
|
||||
|
||||
```toml
|
||||
[[imports]]
|
||||
path = "github.com/jpanther/congo/v2"
|
||||
```
|
||||
|
||||
4. 使用 `hugo server` 启动您的服务器，主题将自动下载。
|
||||
5. 继续 [设置主题配置文件](#设置主题配置文件)。
|
||||
|
||||
#### 使用Git安装
|
||||
|
||||
对于这种方法，您需要确保在本地计算机上安装了 **Git**。
|
||||
|
||||
切换到您的Hugo网站目录（上面创建的目录），初始化一个新的 `git` 存储库并将刚果添加为子模块。
|
||||
|
||||
```bash
|
||||
cd mywebsite
|
||||
git init
|
||||
git submodule add -b stable https://github.com/jpanther/congo.git themes/congo
|
||||
```
|
||||
|
||||
然后继续 [设置主题配置文件](#设置主题配置文件)。
|
||||
|
||||
### 设置主题配置文件
|
||||
|
||||
在您的网站根目录中，删除由Hugo生成的 `config.toml` 文件。将主题中的 `*.toml` 配置文件复制到您的 `config/_default/` 文件夹中。这将确保您具有所有正确的主题设置，并使您能够轻松地根据需要自定义主题。
|
||||
|
||||
{{< alert >}}
|
||||
**注意：** 如果您的项目中已存在 `module.toml` 文件，则不应覆盖它！
|
||||
{{< /alert >}}
|
||||
|
||||
根据您安装主题的方式，您将在不同的位置找到主题配置文件：
|
||||
|
||||
- **Hugo模块：** 在Hugo缓存目录中，或者从GitHub[下载一份副本](https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/jpanther/congo/tree/stable/config/_default)
|
||||
- **Git子模块或手动安装：** `themes/congo/config/_default`
|
||||
|
||||
复制文件后，您的配置文件夹应如下所示：
|
||||
|
||||
```shell
|
||||
config/_default/
|
||||
├─ config.toml
|
||||
├─ markup.toml
|
||||
├─ menus.toml
|
||||
├─ module.toml # 如果使用Hugo模块安装
|
||||
└─ params.toml
|
||||
```
|
||||
|
||||
{{< alert >}}
|
||||
**重要：** 如果您不是使用Hugo模块的方法安装Congo，则必须在您的 `config.toml` 文件顶部添加 `theme = "congo"` 这一行。
|
||||
{{< /alert >}}
|
||||
|
||||
### 下一步
|
||||
|
||||
基本的刚果安装现在已经完成。继续查看 [入门](#入门) 部分，了解有关配置主题的更多信息。
|
||||
|
||||
---
|
||||
|
||||
## 安装更新
|
||||
|
||||
我们不时会发布[新的版本](https://github.com/jpanther/congo/releases)，其中包含对主题的修复和新功能。为了利用这些更改，您需要更新网站上的主题文件。
|
||||
|
||||
您执行此操作的方式将取决于主题最初安装时选择的安装方法。下面是每种方法的说明。
|
||||
|
||||
- [Hugo模块](#使用Hugo更新)
|
||||
- [Git子模块](#使用Git更新)
|
||||
- [手动文件复制](#手动更新)
|
||||
|
||||
### 使用Hugo更新
|
||||
|
||||
Hugo使更新模块变得非常容易。只需切换到项目目录并执行以下命令：
|
||||
|
||||
```shell
|
||||
hugo mod get -u
|
||||
```
|
||||
|
||||
Hugo将自动更新项目所需的任何模块。它通过检查您的 `module.toml` 和 `go.mod` 文件来完成。如果更新时出现任何问题，请检查这些文件是否仍然正确配置。
|
||||
|
||||
然后只需重新构建您的站点，并检查一切是否按预期工作。
|
||||
|
||||
{{< alert >}}
|
||||
在更新模块时，有时Hugo会缓存主题的较旧版本。如果发生这种情况，请使用 `hugo mod clean` 命令清除本地缓存，然后重新构建您的站点。
|
||||
{{< /alert >}}
|
||||
|
||||
### 使用Git更新
|
||||
|
||||
可以使用 `git` 命令更新Git子模块。只需执行以下命令，最新版本的主题将被下载到本地存储库中：
|
||||
|
||||
```shell
|
||||
git submodule update --remote --merge
|
||||
```
|
||||
|
||||
一旦子模块已更新，重新构建您的站点并检查一切是否按预期工作。
|
||||
|
||||
### 手动更新
|
||||
|
||||
手动更新刚果需要您下载主题的最新副本，并替换项目中的旧版本。
|
||||
|
||||
{{< alert >}}
|
||||
请注意，在此过程中，您对主题文件的任何本地自定义将丢失。
|
||||
{{< /alert >}}
|
||||
|
||||
1. 下载主题源代码的最新发布版本。
|
||||
|
||||
{{< button href="https://github.com/jpanther/congo/releases/latest" target="_blank" >}}从Github下载{{< /button >}}
|
||||
|
||||
2. 解压缩存档，将文件夹重命名为 `congo`，并将其移动到Hugo项目根文件夹内的 `themes/` 目录。您需要覆盖现有目录以替换所有主题文件。
|
||||
|
||||
3. 重新构建您的站点
|
||||
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 5.2 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 48 KiB |
@@ -0,0 +1,99 @@
|
||||
---
|
||||
title: "パーシャル"
|
||||
date: 2020-08-10
|
||||
draft: false
|
||||
description: "Congoで利用できるすべてのパーシャルについて"
|
||||
summary: "パーシャルは、アナリティクス、コメント、ファビコン、カスタムスクリプトなどの特別な機能をテーマに追加するために使用されます。"
|
||||
slug: "partials"
|
||||
tags: ["partials", "analytics", "privacy", "comments", "favicons", "icon", "docs"]
|
||||
---
|
||||
|
||||
## アナリティクス
|
||||
|
||||
CongoはFathom AnalyticsとGoogle Analyticsをビルトインでサポートしています。Fathomはユーザーのプライバシーを尊重するGoogle Analyticsの有料代替サービスです。ご興味のある方は、このアフィリエイトリンクから[10ドルのクレジット](https://usefathom.com/ref/RLAJSV)を受け取ってください。
|
||||
|
||||
### Fathom Analytics
|
||||
|
||||
Fathom Analyticsのサポートを有効にするには、 `config/_default/params.toml` ファイルにFathomサイトコードを記述するだけです。Fathomのカスタムドメイン機能を使用し、ドメインからスクリプトを提供したい場合は、 `domain` 設定値を追加で指定することもできます。 `domain` の値を指定しない場合、スクリプトはFathom DNSから直接読み込まれます。
|
||||
|
||||
```toml
|
||||
# config/_default/params.toml
|
||||
|
||||
[fathomAnalytics]
|
||||
site = "ABC12345"
|
||||
domain = "llama.yoursite.com"
|
||||
```
|
||||
|
||||
### Google Analytics
|
||||
|
||||
Google Analyticsのサポートは内部のHugoパーシャルを通して提供されます。 `config/_default/config.toml` ファイルに `googleAnalytics` キーを指定するだけで、スクリプトが自動的に追加されます。
|
||||
|
||||
提供された設定値に基づいて、バージョン3（analytics.js）とバージョン4（gtag.js）の両方がサポートされています:
|
||||
|
||||
```toml
|
||||
# config/_default/config.toml
|
||||
|
||||
# version 3
|
||||
googleAnalytics = "UA-PROPERTY_ID"
|
||||
# version 4
|
||||
googleAnalytics = "G-MEASUREMENT_ID"
|
||||
```
|
||||
|
||||
### Custom analytics providers
|
||||
|
||||
別のアナリティクスプロバイダーを使いたい場合は、アナリティクスパーシャルをオーバーライドして独自のスクリプトを提供することもできます。 `layouts/partials/analytics.html` ファイルをプロジェクトに作成するだけで、ウェブサイトの `<head>` に自動的にインクルードされます。
|
||||
|
||||
## コメント
|
||||
|
||||
記事にコメント機能を追加するために、Congoは各記事ページのベースに含まれるコメントパーシャルのサポートを含んでいます。 `layouts/partials/comments.html` を提供するだけで、選択したコメントを表示するために必要なコードが含まれます。
|
||||
|
||||
組み込みのHugo Disqusテンプレートを使用するか、独自のカスタムコードを提供することができます。詳しくは[Hugo docs](https://gohugo.io/content-management/comments/)を参照してください。
|
||||
|
||||
コメントを表示する場所をより細かく制御するために `showComments` パラメーターを使用します。この値は `params.toml` の[テーマパラメーター]({{< ref "configuration#テーマパラメーター" >}})として設定するか、[フロントマター]({{< ref "front-matter" >}})に含めることで記事ごとに設定するか、選ぶことができます。このパラメーターはデフォルトで `false` に設定されているので、コメントを表示させるにはこれらの場所のいずれかで `true` に設定する必要があります。
|
||||
|
||||
## ファビコン
|
||||
|
||||
Congoはデフォルトで空白のファビコンセットを提供しますが、それを上書きするために独自のアセットを設定することができます。新しいファビコンを入手する最も簡単な方法は、[favicon.io](https://favicon.io)のようなサードパーティプロバイダーを使って生成することです。
|
||||
|
||||
アイコンアセットは、ウェブサイトの `static/` に直接配置し、以下のリストに従って名前を付けてください。[favicon.io](https://favicon.io)を使用する場合、これらは自動的に生成されるファイル名になりますが、必要に応じて独自のアセットを提供することもできます。
|
||||
|
||||
```shell
|
||||
static/
|
||||
├─ android-chrome-192x192.png
|
||||
├─ android-chrome-512x512.png
|
||||
├─ apple-touch-icon.png
|
||||
├─ favicon-16x16.png
|
||||
├─ favicon-32x32.png
|
||||
├─ favicon.ico
|
||||
└─ site.webmanifest
|
||||
```
|
||||
|
||||
また、デフォルトのファビコンの動作を完全にオーバーライドすることもできます。 `layouts/partials/favicons.html` ファイルをプロジェクトに提供するだけで、デフォルトのアセットの代わりに `<head>` に注入されます。
|
||||
|
||||
## アイコン
|
||||
|
||||
[ショートコード - アイコン]({{< ref "shortcodes#アイコン" >}})と同様に、Congoの `icon.html` パーシャルを使うことで、独自のテンプレートやパーシャルにアイコンを含めることができます。このパーシャルにはアイコンの名前を指定します。
|
||||
|
||||
**例:**
|
||||
|
||||
```go
|
||||
{{ partial "icon.html" "github" }}
|
||||
```
|
||||
|
||||
アイコンはHugo Pipesを使って配置されるため、非常に柔軟性があります。Congoには、ソーシャル、リンク、その他の目的のために多くのビルトインアイコンが含まれています。サポートされているアイコンの完全なリストは、[サンプル - アイコン]({{< ref "samples/icons" >}}) ページをチェックしてください。
|
||||
|
||||
カスタムアイコンはプロジェクトの `assets/icons/` ディレクトリに独自のアイコンアセットを提供することで追加できます。アイコンは拡張子 `.svg` を除いたSVGファイル名でパーシャルから参照できます。
|
||||
|
||||
## Extensions
|
||||
|
||||
Congoは基本機能の拡張を可能にする多くのパーシャルを提供しています。
|
||||
|
||||
### 記事リンク
|
||||
|
||||
記事リンクの後に追加のコードを挿入したい場合は、 `layouts/partials/extend-article-link.html` ファイルを作成してください。これは、特定の記事のメタデータをハイライトするために使用できる[`バッジ`]({{< ref "shortcodes#バッジ" >}})ショートコードと組み合わせると特に強力です。
|
||||
|
||||
### HeadとFooter
|
||||
|
||||
テンプレートの `<head>` と `<footer>` に直接追加コードを挿入することができます。これらはテーマの一部ではないスクリプトやその他のロジックを提供するのに便利です。
|
||||
|
||||
`layouts/partials/extend-head.html` または `layouts/partials/extend-footer.html` を作成するだけで、これらは自動的にあなたのウェブサイトに挿入されます。どちらのパーシャルも `<head>` と `<footer>` の最後の項目として挿入されるので、テーマのデフォルトを上書きするために使用することができます。
|
||||
@@ -0,0 +1,117 @@
|
||||
---
|
||||
title: "Partials"
|
||||
date: 2020-08-10
|
||||
draft: false
|
||||
description: "All the partials available in Congo."
|
||||
summary: "Partials are used to add special functionality to the theme including analytics, comments, favicons, custom scripts and more."
|
||||
slug: "partials"
|
||||
tags: ["partials", "analytics", "privacy", "comments", "favicons", "icon", "docs"]
|
||||
---
|
||||
|
||||
## Analytics
|
||||
|
||||
Congo provides support for various analytics providers out of the box, as well as the ability to include custom code for any provider of your choice. If you don't currently have an analytics provider, check out Fathom Analytics.
|
||||
|
||||
### Fathom Analytics
|
||||
|
||||
Fathom Analytics is a privacy-first service that is a great alternative to Google Analytics. It allows you to get all the visitor information you need, without spying on them. As a Congo user, you can use this affiliate link to [receive $10 credit](https://usefathom.com/ref/RLAJSV) and try the service.
|
||||
|
||||
[](https://usefathom.com/ref/RLAJSV)
|
||||
|
||||
To enable Fathom Analytics support, simply provide your Fathom site code in the `config/_default/params.toml` file. The script will load in your site directly from the Fathom Analytics CDN.
|
||||
|
||||
```toml
|
||||
# config/_default/params.toml
|
||||
|
||||
[fathomAnalytics]
|
||||
site = "ABC12345"
|
||||
```
|
||||
|
||||
### Plausible Analytics
|
||||
|
||||
To enable Plausible analytics support, simply provide the domain of the website you want to track in the `config/_default/params.toml` file. If you are using a self-hosted Plausible, or wish to use a [proxied analytics](https://plausible.io/docs/proxy/introduction) script and event API router, you can also provide additional `event` and `script` configuration values. If you do not provide these two values, the script will load directly with Plausible's default managed service. Refer to [Using a proxy for analytics](https://plausible.io/docs/proxy/introduction) for more details.
|
||||
|
||||
```toml
|
||||
# config/_default/params.toml
|
||||
|
||||
[plausibleAnalytics]
|
||||
domain = "blog.yoursite.com"
|
||||
event = "https://plausible.yoursite.com/api/event"
|
||||
script = "https://plausible.yoursite.com/js/script.js"
|
||||
```
|
||||
|
||||
### Google Analytics
|
||||
|
||||
Google Analytics support is provided through the internal Hugo partial. Simply provide the `googleAnalytics` key in the `config/_default/config.toml` file and the script will be added automatically.
|
||||
|
||||
Both version 3 (analytics.js) and version 4 (gtag.js) are supported, based on the configuration value provided:
|
||||
|
||||
```toml
|
||||
# config/_default/config.toml
|
||||
|
||||
# version 3
|
||||
googleAnalytics = "UA-PROPERTY_ID"
|
||||
# version 4
|
||||
googleAnalytics = "G-MEASUREMENT_ID"
|
||||
```
|
||||
|
||||
### Custom analytics providers
|
||||
|
||||
If you wish to use a different analytics provider on your website you can also override the analytics partial and provide your own script. Simply create the file `layouts/partials/analytics.html` in your project and it will automatically include it in the `<head>` of the website.
|
||||
|
||||
## Comments
|
||||
|
||||
To add comments to your articles, Congo includes support for a comments partial that is included at the base of each article page. Simply provide a `layouts/partials/comments.html` which contains the code required to display your chosen comments.
|
||||
|
||||
You can use either the built-in Hugo Disqus template, or provide your own custom code. Refer to the [Hugo docs](https://gohugo.io/content-management/comments/) for further information.
|
||||
|
||||
Once the partial has been provided, finer control over where comments are displayed is then managed using the `showComments` parameter. This value can be set at the theme level in the `params.toml` [config file]({{< ref "configuration#theme-parameters" >}}), or on a per-article basis by including it in the [front matter]({{< ref "front-matter" >}}). The parameter defaults to `false` so it must be set to `true` in one of these locations in order for comments to be displayed.
|
||||
|
||||
## Favicons
|
||||
|
||||
Congo provides a default set of blank favicons to get started but you can provide your own assets to override them. The easiest way to obtain new favicon assets is to generate them using a third-party provider like [favicon.io](https://favicon.io).
|
||||
|
||||
Icon assets should be placed directly in the `static/` folder of your website and named as per the listing below. If you use [favicon.io](https://favicon.io), these will be the filenames that are automatically generated for you, but you can provide your own assets if you wish.
|
||||
|
||||
```shell
|
||||
static/
|
||||
├─ android-chrome-192x192.png
|
||||
├─ android-chrome-512x512.png
|
||||
├─ apple-touch-icon.png
|
||||
├─ favicon-16x16.png
|
||||
├─ favicon-32x32.png
|
||||
├─ favicon.ico
|
||||
└─ site.webmanifest
|
||||
```
|
||||
|
||||
Alternatively, you can also completely override the default favicon behaviour and provide your own favicon HTML tags and assets. Simply provide a `layouts/partials/favicons.html` file in your project and this will be injected into the site `<head>` in place of the default assets.
|
||||
|
||||
## Icon
|
||||
|
||||
Similar to the [icon shortcode]({{< ref "shortcodes#icon" >}}), you can include icons in your own templates and partials by using Congo's `icon.html` partial. The partial takes one parameter which is the name of the icon to be included.
|
||||
|
||||
**Example:**
|
||||
|
||||
```go
|
||||
{{ partial "icon.html" "github" }}
|
||||
```
|
||||
|
||||
Icons are populated using Hugo pipelines which makes them very flexible. Congo includes a number of built-in icons for social, links and other purposes. Check the [icon samples]({{< ref "samples/icons" >}}) page for a full list of supported icons.
|
||||
|
||||
Custom icons can be added by providing your own icon assets in the `assets/icons/` directory of your project. The icon can then be referenced in the partial by using the SVG filename without the `.svg` extension.
|
||||
|
||||
Icons can also be used in article content by calling the [icon shortcode]({{< ref "shortcodes#icon" >}}).
|
||||
|
||||
## Extensions
|
||||
|
||||
Congo also provides for a number of extension partials that allow for expanding upon base functionality.
|
||||
|
||||
### Article link
|
||||
|
||||
If you wish to insert additional code after article links, create a `layouts/partials/extend-article-link.html` file. This is especially powerful when combined with the [`badge`]({{< ref "shortcodes#badge" >}}) shortcode which can be used to highlight metadata for certain articles.
|
||||
|
||||
### Head and Footer
|
||||
|
||||
The theme allows for inserting additional code directly into the `<head>` and `<footer>` sections of the template. These can be useful for providing scripts or other logic that isn't part of the theme.
|
||||
|
||||
Simply create either `layouts/partials/extend-head.html` or `layouts/partials/extend-footer.html` and these will automatically be included in your website build. Both partials are injected as the last items in `<head>` and `<footer>` so they can be used to override theme defaults.
|
||||
@@ -0,0 +1,114 @@
|
||||
---
|
||||
title: "Partials"
|
||||
date: 2020-08-10
|
||||
draft: false
|
||||
description: "Congo 主题中的所有partial。"
|
||||
summary: "partials用于向主题添加特殊功能，包括分析、评论、网站图标、自定义脚本等等。"
|
||||
slug: "partials"
|
||||
tags: ["partials", "analytics", "privacy", "comments", "favicons", "icon", "docs"]
|
||||
---
|
||||
|
||||
## Analytics
|
||||
|
||||
Congo内置支持Fathom Analytics和Google Analytics。Fathom是Google Analytics的付费替代方案，尊重用户隐私。如果您感兴趣，可以使用此[推广链接](https://usefathom.com/ref/RLAJSV)获得$10的信用并尝试该服务。
|
||||
|
||||
### Fathom Analytics
|
||||
|
||||
要启用Fathom Analytics支持，只需在 `config/_default/params.toml` 文件中提供您的Fathom站点代码。如果您还使用Fathom的自定义域功能，并希望从您的域提供其脚本，还可以提供`domain`配置值。如果不提供`domain`值，则脚本将直接从Fathom DNS加载。
|
||||
|
||||
```toml
|
||||
# config/_default/params.toml
|
||||
|
||||
[fathomAnalytics]
|
||||
site = "ABC12345"
|
||||
domain = "llama.yoursite.com"
|
||||
```
|
||||
|
||||
### Plausible Analytics
|
||||
|
||||
要启用 Plausible 分析支持，只需在 `config/_default/params.toml` 文件中提供您要跟踪的网站域。如果您使用的是自托管的 Plausible，或者希望使用 [代理分析](https://plausible.io/docs/proxy/introduction) 脚本和事件 API 路由，您还可以提供额外的 `event` 和 `script` 配置值。如果不提供这两个值，脚本将直接加载 Plausible 的默认托管服务。有关更多详细信息，请参阅 [使用代理进行分析](https://plausible.io/docs/proxy/introduction)。
|
||||
|
||||
```toml
|
||||
# config/_default/params.toml
|
||||
|
||||
[plausibleAnalytics]
|
||||
domain = "blog.yoursite.com"
|
||||
event = "https://plausible.yoursite.com/api/event"
|
||||
script = "https://plausible.yoursite.com/js/script.js"
|
||||
```
|
||||
|
||||
### Google Analytics
|
||||
|
||||
要启用 Google Analytics 支持，只需在 `config/_default/config.toml` 文件中提供 `googleAnalytics` 键，脚本将自动添加。
|
||||
|
||||
根据提供的配置值，支持版本 3 (analytics.js) 和版本 4 (gtag.js)：
|
||||
|
||||
```toml
|
||||
# config/_default/config.toml
|
||||
|
||||
# version 3
|
||||
googleAnalytics = "UA-PROPERTY_ID"
|
||||
# version 4
|
||||
googleAnalytics = "G-MEASUREMENT_ID"
|
||||
```
|
||||
|
||||
### 自定义分析提供商
|
||||
|
||||
如果您希望在您的网站上使用不同的分析提供商，您还可以覆盖分析 partial 并提供自己的脚本。只需在项目中创建文件 `layouts/partials/analytics.html`，它将自动包含在网站的 `<head>` 中。
|
||||
|
||||
## 评论
|
||||
|
||||
要在文章中添加评论，Congo 包括对评论 partial 的支持，该 partial 包含在每篇文章页面的底部。只需提供一个包含显示您选择的评论所需代码的 `layouts/partials/comments.html`。
|
||||
|
||||
您可以使用内置的 Hugo Disqus 模板，也可以提供自己的自定义代码。有关详细信息，请参阅 [Hugo 文档](https://gohugo.io/content-management/comments/)。
|
||||
|
||||
一旦提供了 partial，就可以使用 `showComments` 参数来更精细地控制评论的显示位置。该值可以在 `params.toml` [配置文件]({{< ref "configuration#theme-parameters" >}})中在主题级别设置，也可以通过在 [front matter]({{< ref "front-matter" >}}) 中将其包含在每篇文章中。该参数默认为 `false`，因此必须在这些位置之一将其设置为 `true`，以便显示评论。
|
||||
|
||||
## 网站图标
|
||||
|
||||
Congo 提供了一组默认的空白网站图标，以便开始使用，但您可以提供自己的资产来覆盖它们。获取新网站图标资产的最简单方法是使用第三方提供商（例如 [favicon.io](https://favicon.io)）生成它们。
|
||||
|
||||
图标资产应直接放置在您网站的 `static/` 文件夹中，并按下面的清单命名。如果您使用 [favicon.io](https://favicon.io)，这些将是为您自动生成的文件名，但如果愿意，您也可以提供自己的资产。
|
||||
|
||||
```shell
|
||||
static/
|
||||
├─ android-chrome-192x192.png
|
||||
├─ android-chrome-512x512.png
|
||||
├─ apple-touch-icon.png
|
||||
├─ favicon-16x16.png
|
||||
├─ favicon-32x32.png
|
||||
├─ favicon.ico
|
||||
└─ site.webmanifest
|
||||
```
|
||||
|
||||
或者，您还可以完全覆盖默认的网站图标行为，并提供自己的网站图标 HTML 标签和资产。只需在您的项目中提供一个 `layouts/partials/favicons.html` 文件，它将被注入到站点的 `<head>` 中，取代默认的资产。
|
||||
|
||||
## 图标
|
||||
|
||||
与 [图标 shortcode]({{< ref "shortcodes#icon" >}}) 类似，您可以通过使用 Congo 的 `icon.html` 部分在自己的模板和部分中包含图标。该部分接受一个参数，即要包含的图标的名称。
|
||||
|
||||
**例:**
|
||||
|
||||
```go
|
||||
{{ partial "icon.html" "github" }}
|
||||
```
|
||||
|
||||
图标是使用 Hugo 管道生成的，这使它们非常灵活。Congo 包含了许多内置的图标，用于社交、链接和其他用途。查看 [图标示例]({{< ref "samples/icons" >}}) 页面，以获取支持的所有图标的完整列表。
|
||||
|
||||
您可以通过在项目的 `assets/icons/` 目录中提供自己的图标资产来添加自定义图标。然后，可以通过在没有 `.svg` 扩展名的情况下使用 SVG 文件名在部分中引用该图标。
|
||||
|
||||
图标还可以通过调用 [图标 shortcode]({{< ref "shortcodes#icon" >}}) 在文章内容中使用。
|
||||
|
||||
## 扩展
|
||||
|
||||
Congo 还提供了许多扩展部分，允许扩展基本功能。
|
||||
|
||||
### 文章链接
|
||||
|
||||
如果希望在文章链接后插入其他代码，请创建一个 `layouts/partials/extend-article-link.html` 文件。当与 [`badge`]({{< ref "shortcodes#badge" >}}) shortcode 结合使用时，这特别强大，可以用于突出显示某些文章的元数据。
|
||||
|
||||
### 头部和页脚
|
||||
|
||||
该主题允许直接将额外的代码插入到模板的 `<head>` 和 `<footer>` 部分。这对于提供不是主题一部分的脚本或其他逻辑非常有用。
|
||||
|
||||
只需创建 `layouts/partials/extend-head.html` 或 `layouts/partials/extend-footer.html`，它们将自动包含在您的网站构建中。这两个部分都被注入为 `<head>` 和 `<footer>` 中的最后一项，因此它们可以用于覆盖主题默认值。
|
||||
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 8.6 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.2 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 40 KiB |
@@ -0,0 +1,236 @@
|
||||
---
|
||||
title: "ショートコード"
|
||||
date: 2020-08-11
|
||||
draft: false
|
||||
description: "Congoで利用できるすべてのショートコードについて"
|
||||
summary: Congoには、画像、図表、ボタンなどのリッチコンテンツを記事に追加するショートコードが含まれています。
|
||||
slug: "shortcodes"
|
||||
tags: ["shortcodes", "mermaid", "icon", "lead", "docs"]
|
||||
---
|
||||
|
||||
すべての[デフォルトのHugoショートコード](https://gohugo.io/content-management/shortcodes/)に加えて、Congoは追加機能のためにいくつか追加しています。
|
||||
|
||||
## アラート
|
||||
|
||||
`alert` は、その内容をスタイル化されたメッセージボックスとして記事内に出力します。読者に見逃してほしくない重要な情報に注意を促すのに便利です。
|
||||
|
||||
入力はMarkdownで書かれているので、好きなようにフォーマットできます。
|
||||
|
||||
デフォルトでは、警告の三角形アイコンで表示されます。アイコンを変更するには、アイコン名をショートコードに含めます。アイコンの使い方については、[アイコン](#アイコン)をご覧ください。
|
||||
|
||||
**例:**
|
||||
|
||||
```md
|
||||
{{</* alert */>}}
|
||||
**警告！** この行為は破壊的です！
|
||||
{{</* /alert */>}}
|
||||
|
||||
{{</* alert "twitter" */>}}
|
||||
Twitterで私を[フォロー](https://twitter.com/jpanther)することをお忘れなく！
|
||||
{{</* /alert */>}}
|
||||
```
|
||||
|
||||
{{< alert >}}
|
||||
**警告！** この行為は破壊的です！
|
||||
{{< /alert >}}
|
||||
|
||||
{{< alert "twitter" >}}
|
||||
Twitterで私を[フォロー](https://twitter.com/jpanther)することをお忘れなく！
|
||||
{{< /alert >}}
|
||||
|
||||
## バッジ
|
||||
|
||||
`badge` は、メタデータを表示するのに便利なスタイル付きバッジコンポーネントを出力します。
|
||||
|
||||
**例:**
|
||||
|
||||
```md
|
||||
{{</* badge */>}}
|
||||
新着記事！
|
||||
{{</* /badge */>}}
|
||||
```
|
||||
|
||||
{{< badge >}}
|
||||
新着記事！
|
||||
{{< /badge >}}
|
||||
|
||||
## ボタン
|
||||
|
||||
`button` は主要なアクションを強調するために使用できるスタイル付きボタンコンポーネントを出力します。オプションで3つのパラメーターを持ちます:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|Parameter|Description|
|
||||
|---|---|
|
||||
|`href`|ボタンがリンクするURL。|
|
||||
|`target`|リンクのターゲット。|
|
||||
|`download`|ブラウザがURLに移動するのではなく、リソースをダウンロードするかどうか。このパラメーターの値はダウンロードされるファイルの名前になります。|
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
**例:**
|
||||
|
||||
```md
|
||||
{{</* button href="#button" target="_self" */>}}
|
||||
Click!
|
||||
{{</* /button */>}}
|
||||
```
|
||||
|
||||
{{< button href="#button" target="_self" >}}
|
||||
Click!
|
||||
{{< /button >}}
|
||||
|
||||
## チャート
|
||||
|
||||
`chart` は、Chart.jsライブラリを使用して、単純な構造化データを使用して記事にチャートを埋め込みます。多くの[異なるチャートスタイル](https://www.chartjs.org/docs/latest/samples/)をサポートしており、全てはショートコード内から設定することができます。ショートコードのタグの間にチャートのパラメーターを指定するだけで、あとはChart.jsがやってくれます。
|
||||
|
||||
構文とサポートされるチャート・タイプの詳細については、[Chart.js公式ドキュメント](https://www.chartjs.org/docs/latest/general/)を参照してください。
|
||||
|
||||
**例:**
|
||||
|
||||
```js
|
||||
{{</* chart */>}}
|
||||
type: 'bar',
|
||||
data: {
|
||||
labels: ['Tomato', 'Blueberry', 'Banana', 'Lime', 'Orange'],
|
||||
datasets: [{
|
||||
label: '# of votes',
|
||||
data: [12, 19, 3, 5, 3],
|
||||
}]
|
||||
}
|
||||
{{</* /chart */>}}
|
||||
```
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{{< chart >}}
|
||||
type: 'bar',
|
||||
data: {
|
||||
labels: ['Tomato', 'Blueberry', 'Banana', 'Lime', 'Orange'],
|
||||
datasets: [{
|
||||
label: '# of votes',
|
||||
data: [12, 19, 3, 5, 3],
|
||||
}]
|
||||
}
|
||||
{{< /chart >}}
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
[サンプル - チャート]({{< ref "charts" >}})で、他のサンプルを見るこができます。
|
||||
|
||||
## 図
|
||||
|
||||
Congoには、コンテンツに画像を追加するための `figure` ショートコードが含まれています。このショートコードは、Hugoの基本機能を置き換えることで、さらなるパフォーマンス上の利点を提供します。
|
||||
|
||||
提供された画像がページリソースである場合、Hugo Pipesを使用して最適化され、さまざまなデバイスの解像度に適した画像が提供されるように拡大縮小されます。静的アセットや外部画像へのURLが提供された場合は、Hugoによる画像処理は行われず、そのまま含まれます。
|
||||
|
||||
`figure` は6つのパラメーターを受け入れます:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|Parameter|Description|
|
||||
|---|---|
|
||||
|`src`| **必須** 画像のローカルパス/ファイル名またはURL。パスとファイル名を指定すると、テーマは次の順番で画像を探します: まず、ページにバンドルされている[ページリソース](https://gohugo.io/content-management/page-resources/)、次に `assets/` ディレクトリ、最後に `static/` ディレクトリ。|
|
||||
|`alt`|画像の[代替テキスト説明](https://moz.com/learn/seo/alt-text)。|
|
||||
|`caption`|画像の下に表示される画像キャプションのMarkdown文字列。|
|
||||
|`class`|画像に適用する追加のCSSクラス。|
|
||||
|`href`|画像のリンク先URL。|
|
||||
|`default`|デフォルトのHugo `figure` の動作に戻す際には `default=true` を指定し、通常の[Hugo ショートコード構文](https://gohugo.io/content-management/shortcodes/#figure)を参照してください。|
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
Congoは、標準的なMarkdown構文を使用した場合の画像についても自動変換をサポートしています。以下のフォーマットを使用するだけで処理します:
|
||||
|
||||
```md
|
||||
|
||||
```
|
||||
|
||||
**例:**
|
||||
|
||||
```md
|
||||
{{</* figure
|
||||
src="abstract.jpg"
|
||||
alt="抽象的な紫色のアートワーク"
|
||||
caption="Photo by [Jr Korpa](https://unsplash.com/@jrkorpa) on [Unsplash](https://unsplash.com/)"
|
||||
*/>}}
|
||||
|
||||
<!-- OR -->
|
||||
|
||||
|
||||
```
|
||||
|
||||
{{< figure src="abstract.jpg" alt="抽象的な紫色のアートワーク" caption="Photo by [Jr Korpa](https://unsplash.com/@jrkorpa) on [Unsplash](https://unsplash.com/)" >}}
|
||||
|
||||
## アイコン
|
||||
|
||||
`icon` はアイコンの名前を唯一のパラメーターとして受け取り、SVGアイコンを出力します。アイコンは現在のテキストサイズに合わせて自動的に拡大縮小されます。
|
||||
|
||||
**例:**
|
||||
|
||||
```md
|
||||
{{</* icon "github" */>}}
|
||||
```
|
||||
|
||||
**出力:** {{< icon "github" >}}
|
||||
|
||||
アイコンはHugo Pipesを使って配置されるため、非常に柔軟性があります。Congoには、ソーシャル、リンク、その他の目的のために多くのビルトインアイコンが含まれています。サポートされているアイコンの完全なリストは、[サンプル - アイコン]({{< ref "samples/icons" >}})ページをチェックしてください。
|
||||
|
||||
カスタムアイコンは、プロジェクトの `assets/icons/` ディレクトリに独自のアイコンアセットを提供することで追加できます。アイコンは拡張子 `.svg` を除いたSVGファイル名でショートコードから参照できます。
|
||||
|
||||
アイコンは[パーシャル - アイコン]({{< ref "partials#アイコン" >}})を呼び出すことでパーシャルでも使用できます。
|
||||
|
||||
## Katex
|
||||
|
||||
`katex` を使うと、KaTeXパッケージを使って記事の内容に数式を追加することができます。利用可能な構文については[supported TeX functions](https://katex.org/docs/supported.html)のオンラインリファレンスを参照してください。
|
||||
|
||||
記事中に数式を含めるには、コンテンツ内の任意の場所にショートコードを配置するだけです。記事ごとに一度記述するだけで、KaTeXが自動的にそのページのマークアップをレンダリングします。インライン表記とブロック表記の両方がサポートされています。
|
||||
|
||||
インライン記法は、式を区切り記号 `\\(` と `\\)` で囲むことで生成できます。ブロック記法の場合は `$$` です。
|
||||
|
||||
**例:**
|
||||
|
||||
```md
|
||||
{{</* katex */>}}
|
||||
\\(f(a,b,c) = (a^2+b^2+c^2)^3\\)
|
||||
```
|
||||
|
||||
{{< katex >}}
|
||||
\\(f(a,b,c) = (a^2+b^2+c^2)^3\\)
|
||||
|
||||
[数学的表記のサンプル]({{< ref "mathematical-notation" >}})でより多くの例をチェックしてください。
|
||||
|
||||
## リード
|
||||
|
||||
`lead` は記事の冒頭を強調するために使われます。導入部のスタイルや、重要な情報を呼び出すために使用することができます。Markdownのコンテンツを `lead` で囲むだけです。
|
||||
|
||||
**例:**
|
||||
|
||||
```md
|
||||
{{</* lead */>}}
|
||||
人生があなたにレモンを与えるなら、それでレモネードを作りなさい。
|
||||
{{</* /lead */>}}
|
||||
```
|
||||
|
||||
{{< lead >}}
|
||||
人生があなたにレモンを与えるなら、それでレモネードを作りなさい。
|
||||
{{< /lead >}}
|
||||
|
||||
## Mermaid
|
||||
|
||||
`mermaid` を使えば、テキストを使って詳細なダイアグラムやビジュアライゼーションを描くことができます。Mermaidを使用しており、様々なダイアグラム、チャート、その他の出力形式をサポートしています。
|
||||
|
||||
`mermaid` 内にMermaid構文を記述するだけで、あとはプラグインにおまかせです。
|
||||
|
||||
構文とサポートされている図の種類の詳細については、[Mermaid公式ドキュメント](https://mermaid-js.github.io/)を参照してください。
|
||||
|
||||
**例:**
|
||||
|
||||
```md
|
||||
{{</* mermaid */>}}
|
||||
graph LR;
|
||||
A[レモン]-->B[レモネード];
|
||||
B-->C[利益]
|
||||
{{</* /mermaid */>}}
|
||||
```
|
||||
|
||||
{{< mermaid >}}
|
||||
graph LR;
|
||||
A[レモン]-->B[レモネード];
|
||||
B-->C[利益]
|
||||
{{< /mermaid >}}
|
||||
|
||||
[ダイアグラムとフローチャートのサンプル]({{< ref "diagrams-flowcharts" >}})で、他の例を見ることができます。
|
||||
@@ -0,0 +1,236 @@
|
||||
---
|
||||
title: "Shortcodes"
|
||||
date: 2020-08-11
|
||||
draft: false
|
||||
description: "All the shortcodes available in Congo."
|
||||
summary: Congo includes several shortcodes for adding rich content to articles including images, charts, diagrams, buttons and more.
|
||||
slug: "shortcodes"
|
||||
tags: ["shortcodes", "mermaid", "icon", "lead", "docs"]
|
||||
---
|
||||
|
||||
In addition to all the [default Hugo shortcodes](https://gohugo.io/content-management/shortcodes/), Congo adds a few extras for additional functionality.
|
||||
|
||||
## Alert
|
||||
|
||||
`alert` outputs its contents as a stylised message box within your article. It's useful for drawing attention to important information that you don't want the reader to miss.
|
||||
|
||||
The input is written in Markdown so you can format it however you please.
|
||||
|
||||
By default, the alert is presented with an exclaimation triangle icon. To change the icon, include the icon name in the shortcode. Check out the [icon shortcode](#icon) for more details on using icons.
|
||||
|
||||
**Example:**
|
||||
|
||||
```md
|
||||
{{</* alert */>}}
|
||||
**Warning!** This action is destructive!
|
||||
{{</* /alert */>}}
|
||||
|
||||
{{</* alert "twitter" */>}}
|
||||
Don't forget to [follow me](https://twitter.com/jpanther) on Twitter.
|
||||
{{</* /alert */>}}
|
||||
```
|
||||
|
||||
{{< alert >}}
|
||||
**Warning!** This action is destructive!
|
||||
{{< /alert >}}
|
||||
|
||||
{{< alert "twitter" >}}
|
||||
Don't forget to [follow me](https://twitter.com/jpanther) on Twitter.
|
||||
{{< /alert >}}
|
||||
|
||||
## Badge
|
||||
|
||||
`badge` outputs a styled badge component which is useful for displaying metadata.
|
||||
|
||||
**Example:**
|
||||
|
||||
```md
|
||||
{{</* badge */>}}
|
||||
New article!
|
||||
{{</* /badge */>}}
|
||||
```
|
||||
|
||||
{{< badge >}}
|
||||
New article!
|
||||
{{< /badge >}}
|
||||
|
||||
## Button
|
||||
|
||||
`button` outputs a styled button component which can be used to highlight a primary action. It has three optional parameters:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|Parameter|Description|
|
||||
|---|---|
|
||||
|`href`|The URL that the button should link to.|
|
||||
|`target`|The target of the link.|
|
||||
|`download`|Whether browser should download the resource rather than navigate to the URL. The value of this parameter will be the name of the downloaded file.|
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
**Example:**
|
||||
|
||||
```md
|
||||
{{</* button href="#button" target="_self" */>}}
|
||||
Call to action
|
||||
{{</* /button */>}}
|
||||
```
|
||||
|
||||
{{< button href="#button" target="_self" >}}
|
||||
Call to action
|
||||
{{< /button >}}
|
||||
|
||||
## Chart
|
||||
|
||||
`chart` uses the Chart.js library to embed charts into articles using simple structured data. It supports a number of [different chart styles](https://www.chartjs.org/docs/latest/samples/) and everything can be configured from within the shortcode. Simply provide the chart parameters between the shortcode tags and Chart.js will do the rest.
|
||||
|
||||
Refer to the [official Chart.js docs](https://www.chartjs.org/docs/latest/general/) for details on syntax and supported chart types.
|
||||
|
||||
**Example:**
|
||||
|
||||
```js
|
||||
{{</* chart */>}}
|
||||
type: 'bar',
|
||||
data: {
|
||||
labels: ['Tomato', 'Blueberry', 'Banana', 'Lime', 'Orange'],
|
||||
datasets: [{
|
||||
label: '# of votes',
|
||||
data: [12, 19, 3, 5, 3],
|
||||
}]
|
||||
}
|
||||
{{</* /chart */>}}
|
||||
```
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{{< chart >}}
|
||||
type: 'bar',
|
||||
data: {
|
||||
labels: ['Tomato', 'Blueberry', 'Banana', 'Lime', 'Orange'],
|
||||
datasets: [{
|
||||
label: '# of votes',
|
||||
data: [12, 19, 3, 5, 3],
|
||||
}]
|
||||
}
|
||||
{{< /chart >}}
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
You can see some additional Chart.js examples on the [charts samples]({{< ref "charts" >}}) page.
|
||||
|
||||
## Figure
|
||||
|
||||
Congo includes a `figure` shortcode for adding images to content. The shortcode replaces the base Hugo functionality in order to provide additional performance benefits.
|
||||
|
||||
When a provided image is a page resource, it will be optimised using Hugo Pipes and scaled in order to provide images appropriate to different device resolutions. If a static asset or URL to an external image is provided, it will be included as-is without any image processing by Hugo.
|
||||
|
||||
The `figure` shortcode accepts six parameters:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|Parameter|Description|
|
||||
|---|---|
|
||||
|`src`| **Required.** The local path/filename or URL of the image. When providing a path and filename, the theme will attempt to locate the image using the following lookup order: Firstly, as a [page resource](https://gohugo.io/content-management/page-resources/) bundled with the page; then an asset in the `assets/` directory; then finally, a static image in the `static/` directory.|
|
||||
|`alt`|[Alternative text description](https://moz.com/learn/seo/alt-text) for the image.|
|
||||
|`caption`|Markdown for the image caption, which will be displayed below the image.|
|
||||
|`class`|Additional CSS classes to apply to the image.|
|
||||
|`href`|URL that the image should be linked to.|
|
||||
|`default`|Special parameter to revert to default Hugo `figure` behaviour. Simply provide `default=true` and then use normal [Hugo shortcode syntax](https://gohugo.io/content-management/shortcodes/#figure).|
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
Congo also supports automatic conversion of images included using standard Markdown syntax. Simply use the following format and the theme will handle the rest:
|
||||
|
||||
```md
|
||||
|
||||
```
|
||||
|
||||
**Example:**
|
||||
|
||||
```md
|
||||
{{</* figure
|
||||
src="abstract.jpg"
|
||||
alt="Abstract purple artwork"
|
||||
caption="Photo by [Jr Korpa](https://unsplash.com/@jrkorpa) on [Unsplash](https://unsplash.com/)"
|
||||
*/>}}
|
||||
|
||||
<!-- OR -->
|
||||
|
||||
|
||||
```
|
||||
|
||||
{{< figure src="abstract.jpg" alt="Abstract purple artwork" caption="Photo by [Jr Korpa](https://unsplash.com/@jrkorpa) on [Unsplash](https://unsplash.com/)" >}}
|
||||
|
||||
## Icon
|
||||
|
||||
`icon` outputs an SVG icon and takes the icon name as its only parameter. The icon is scaled to match the current text size.
|
||||
|
||||
**Example:**
|
||||
|
||||
```md
|
||||
{{</* icon "github" */>}}
|
||||
```
|
||||
|
||||
**Output:** {{< icon "github" >}}
|
||||
|
||||
Icons are populated using Hugo pipelines which makes them very flexible. Congo includes a number of built-in icons for social, links and other purposes. Check the [icon samples]({{< ref "samples/icons" >}}) page for a full list of supported icons.
|
||||
|
||||
Custom icons can be added by providing your own icon assets in the `assets/icons/` directory of your project. The icon can then be referenced in the shortcode by using the SVG filename without the `.svg` extension.
|
||||
|
||||
Icons can also be used in partials by calling the [icon partial]({{< ref "partials#icon" >}}).
|
||||
|
||||
## Katex
|
||||
|
||||
The `katex` shortcode can be used to add mathematical expressions to article content using the KaTeX package. Refer to the online reference of [supported TeX functions](https://katex.org/docs/supported.html) for the available syntax.
|
||||
|
||||
To include mathematical expressions in an article, simply place the shortcode anywhere with the content. It only needs to be included once per article and KaTeX will automatically render any markup on that page. Both inline and block notation are supported.
|
||||
|
||||
Inline notation can be generated by wrapping the expression in `\\(` and `\\)` delimiters. Alternatively, block notation can be generated using `$$` delimiters.
|
||||
|
||||
**Example:**
|
||||
|
||||
```md
|
||||
{{</* katex */>}}
|
||||
\\(f(a,b,c) = (a^2+b^2+c^2)^3\\)
|
||||
```
|
||||
|
||||
{{< katex >}}
|
||||
\\(f(a,b,c) = (a^2+b^2+c^2)^3\\)
|
||||
|
||||
Check out the [mathematical notation samples]({{< ref "mathematical-notation" >}}) page for more examples.
|
||||
|
||||
## Lead
|
||||
|
||||
`lead` is used to bring emphasis to the start of an article. It can be used to style an introduction, or to call out an important piece of information. Simply wrap any Markdown content in the `lead` shortcode.
|
||||
|
||||
**Example:**
|
||||
|
||||
```md
|
||||
{{</* lead */>}}
|
||||
When life gives you lemons, make lemonade.
|
||||
{{</* /lead */>}}
|
||||
```
|
||||
|
||||
{{< lead >}}
|
||||
When life gives you lemons, make lemonade.
|
||||
{{< /lead >}}
|
||||
|
||||
## Mermaid
|
||||
|
||||
`mermaid` allows you to draw detailed diagrams and visualisations using text. It uses Mermaid under the hood and supports a wide variety of diagrams, charts and other output formats.
|
||||
|
||||
Simply write your Mermaid syntax within the `mermaid` shortcode and let the plugin do the rest.
|
||||
|
||||
Refer to the [official Mermaid docs](https://mermaid-js.github.io/) for details on syntax and supported diagram types.
|
||||
|
||||
**Example:**
|
||||
|
||||
```md
|
||||
{{</* mermaid */>}}
|
||||
graph LR;
|
||||
A[Lemons]-->B[Lemonade];
|
||||
B-->C[Profit]
|
||||
{{</* /mermaid */>}}
|
||||
```
|
||||
|
||||
{{< mermaid >}}
|
||||
graph LR;
|
||||
A[Lemons]-->B[Lemonade];
|
||||
B-->C[Profit]
|
||||
{{< /mermaid >}}
|
||||
|
||||
You can see some additional Mermaid examples on the [diagrams and flowcharts samples]({{< ref "diagrams-flowcharts" >}}) page.
|
||||
@@ -0,0 +1,236 @@
|
||||
---
|
||||
title: "短代码"
|
||||
date: 2020-08-11
|
||||
draft: false
|
||||
description: "Congo提供的所有短代码"
|
||||
summary: Congo提供了多个短代码，可用于向文章添加丰富的内容，包括图像、图表、图表、按钮等。
|
||||
slug: "shortcodes"
|
||||
tags: ["shortcodes", "mermaid", "icon", "lead", "docs"]
|
||||
---
|
||||
|
||||
除了[默认的 Hugo 短代码](https://gohugo.io/content-management/shortcodes/)外，Congo 还额外添加了一些功能。
|
||||
|
||||
## Alert
|
||||
|
||||
`alert`以样式化的消息框形式输出其内容在文章中。它对于引起读者注意的重要信息很有用。
|
||||
|
||||
输入是用Markdown编写的，因此您可以按照自己的喜好进行格式化。
|
||||
|
||||
默认情况下，警报将以感叹号三角形图标的形式呈现。要更改图标，请在短代码中包含图标名称。有关使用图标的更多详细信息，请查看[图标短代码](#icon)。
|
||||
|
||||
**示例:**
|
||||
|
||||
```md
|
||||
{{</* alert */>}}
|
||||
**警告！** 这个操作是破坏性的！
|
||||
{{</* /alert */>}}
|
||||
|
||||
{{</* alert "twitter" */>}}
|
||||
别忘了在Twitter上[关注我](https://twitter.com/jpanther)。
|
||||
{{</* /alert */>}}
|
||||
```
|
||||
|
||||
{{< alert >}}
|
||||
**警告！** 这个操作是破坏性的！
|
||||
{{< /alert >}}
|
||||
|
||||
{{< alert "twitter" >}}
|
||||
别忘了在Twitter上[关注我](https://twitter.com/jpanther)。
|
||||
{{< /alert >}}
|
||||
|
||||
## Badge
|
||||
|
||||
`badge`输出一个带有样式的徽章组件，用于显示元数据。
|
||||
|
||||
**示例:**
|
||||
|
||||
```md
|
||||
{{</* badge */>}}
|
||||
新文章！
|
||||
{{</* /badge */>}}
|
||||
```
|
||||
|
||||
{{< badge >}}
|
||||
新文章！
|
||||
{{< /badge >}}
|
||||
|
||||
## Button
|
||||
|
||||
`button` 输出一个样式化的按钮组件，用于突出显示主要操作。它有三个可选参数：
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|参数|描述|
|
||||
|---|---|
|
||||
|`href`|按钮应链接到的 URL。|
|
||||
|`target`|链接的目标。|
|
||||
|`download`|浏览器是否应下载资源而不是导航到 URL。此参数的值将是下载文件的名称。|
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
**示例:**
|
||||
|
||||
```md
|
||||
{{</* button href="#button" target="_self" */>}}
|
||||
Call to action
|
||||
{{</* /button */>}}
|
||||
```
|
||||
|
||||
{{< button href="#button" target="_self" >}}
|
||||
Call to action
|
||||
{{< /button >}}
|
||||
|
||||
## Chart
|
||||
|
||||
`chart` 使用 Chart.js 库通过简单的结构化数据嵌入图表到文章中。它支持多种[不同的图表样式](https://www.chartjs.org/docs/latest/samples/)，并且一切都可以通过短代码内部进行配置。只需在短代码标签之间提供图表参数，Chart.js 将完成其余工作。
|
||||
|
||||
有关语法和支持的图表类型的详细信息，请参阅[官方 Chart.js 文档](https://www.chartjs.org/docs/latest/general/)。
|
||||
|
||||
**示例:**
|
||||
|
||||
```js
|
||||
{{</* chart */>}}
|
||||
type: 'bar',
|
||||
data: {
|
||||
labels: ['Tomato', 'Blueberry', 'Banana', 'Lime', 'Orange'],
|
||||
datasets: [{
|
||||
label: '# of votes',
|
||||
data: [12, 19, 3, 5, 3],
|
||||
}]
|
||||
}
|
||||
{{</* /chart */>}}
|
||||
```
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{{< chart >}}
|
||||
type: 'bar',
|
||||
data: {
|
||||
labels: ['Tomato', 'Blueberry', 'Banana', 'Lime', 'Orange'],
|
||||
datasets: [{
|
||||
label: '# of votes',
|
||||
data: [12, 19, 3, 5, 3],
|
||||
}]
|
||||
}
|
||||
{{< /chart >}}
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
你可以在 [图表示例]({{< ref "charts" >}}) 页面看到一些额外的 Chart.js 示例。
|
||||
|
||||
## Figure
|
||||
|
||||
Congo 包含一个 `figure` 短代码，用于向内容添加图片。该短代码替代了基本的 Hugo 功能，以提供额外的性能优势。
|
||||
|
||||
当提供的图像是页面资源时，它将使用 Hugo Pipes 进行优化，并进行缩放，以提供适用于不同设备分辨率的图像。如果提供的是静态资源或指向外部图像的 URL，则将其原样包含，Hugo 不会对其进行任何图像处理。
|
||||
|
||||
`figure` 短代码接受六个参数：
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|参数|描述|
|
||||
|---|---|
|
||||
|`src`| **必需。** 图像的本地路径/文件名或 URL。当提供路径和文件名时，主题将尝试使用以下查找顺序定位图像：首先，作为[页面资源](https://gohugo.io/content-management/page-resources/)与页面捆绑；然后是 `assets/` 目录中的资源；最后是 `static/` 目录中的静态图像。|
|
||||
|`alt`|图像的[替代文本描述](https://moz.com/learn/seo/alt-text)。|
|
||||
|`caption`|图像说明的 Markdown，将显示在图像下方。|
|
||||
|`class`|应用于图像的额外 CSS 类。|
|
||||
|`href`|图像应链接到的 URL。|
|
||||
|`default`|特殊参数，用于恢复默认的 Hugo `figure` 行为。只需提供 `default=true`，然后使用正常的[Hugo 短代码语法](https://gohugo.io/content-management/shortcodes/#figure)。|
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
Congo 还支持使用标准 Markdown 语法包含的图像的自动转换。只需使用以下格式，主题将处理其余部分：
|
||||
|
||||
```md
|
||||
|
||||
```
|
||||
|
||||
**示例:**
|
||||
|
||||
```md
|
||||
{{</* figure
|
||||
src="abstract.jpg"
|
||||
alt="抽象紫色艺术品"
|
||||
caption="照片由[Jr Korpa](https://unsplash.com/@jrkorpa)拍摄，来自[Unsplash](https://unsplash.com/)"
|
||||
*/>}}
|
||||
|
||||
<!-- 或 -->
|
||||
|
||||
|
||||
```
|
||||
|
||||
{{< figure src="abstract.jpg" alt="抽象紫色艺术品" caption="照片由[Jr Korpa](https://unsplash.com/@jrkorpa)拍摄，来自[Unsplash](https://unsplash.com/)" >}}
|
||||
|
||||
## Icon
|
||||
|
||||
`icon` 输出一个 SVG 图标，并将图标名称作为其唯一参数。图标的大小会根据当前文本大小进行缩放。
|
||||
|
||||
**示例:**
|
||||
|
||||
```md
|
||||
{{</* icon "github" */>}}
|
||||
```
|
||||
|
||||
**输出:** {{< icon "github" >}}
|
||||
|
||||
图标是使用 Hugo 管道填充的，这使它们非常灵活。Congo 包含许多用于社交、链接和其他用途的内置图标。请查看 [图标示例]({{< ref "samples/icons" >}}) 页面以获取支持的图标的完整列表。
|
||||
|
||||
通过在项目的 `assets/icons/` 目录中提供自己的图标资产，可以添加自定义图标。然后，可以通过在短代码中使用不带 `.svg` 扩展名的 SVG 文件名来引用图标。
|
||||
|
||||
图标还可以通过调用 [图标部分]({{< ref "partials#icon" >}}) 在局部中使用。
|
||||
|
||||
## Katex
|
||||
|
||||
`katex` 短代码可用于使用 KaTeX 包向文章内容添加数学表达式。有关可用语法，请参阅[支持的 TeX 函数](https://katex.org/docs/supported.html)的在线参考。
|
||||
|
||||
要在文章中包含数学表达式，只需在内容中的任何位置放置短代码。它只需要在每篇文章中包含一次，KaTeX 将自动呈现页面上的任何标记。支持行内和块表示法。
|
||||
|
||||
可以通过将表达式包装在 `\\(` 和 `\\)` 定界符中来生成行内表示法。或者，可以使用 `$$` 定界符生成块表示法。
|
||||
|
||||
**示例:**
|
||||
|
||||
```md
|
||||
{{</* katex */>}}
|
||||
\\(f(a,b,c) = (a^2+b^2+c^2)^3\\)
|
||||
```
|
||||
|
||||
{{< katex >}}
|
||||
\\(f(a,b,c) = (a^2+b^2+c^2)^3\\)
|
||||
|
||||
查看 [数学符号示例]({{< ref "mathematical-notation" >}}) 页面以获取更多示例。
|
||||
|
||||
## Lead
|
||||
|
||||
`lead` 用于突出显示文章开头的内容。它可用于设计引言，或者强调重要信息。只需将任何 Markdown 内容包装在 `lead` 短代码中即可。
|
||||
|
||||
**示例:**
|
||||
|
||||
```md
|
||||
{{</* lead */>}}
|
||||
当生活给你柠檬时，做柠檬水。
|
||||
{{</* /lead */>}}
|
||||
```
|
||||
|
||||
{{< lead >}}
|
||||
当生活给你柠檬时，做柠檬水。
|
||||
{{< /lead >}}
|
||||
|
||||
## Mermaid
|
||||
|
||||
`mermaid` 允许您使用文本绘制详细的图表和可视化效果。它在幕后使用 Mermaid，并支持各种图表、图表和其他输出格式。
|
||||
|
||||
只需在 `mermaid` 短代码中编写您的 Mermaid 语法，然后让插件处理剩下的工作。
|
||||
|
||||
有关语法和支持的图表类型的详细信息，请参阅 [官方 Mermaid 文档](https://mermaid-js.github.io/)。
|
||||
|
||||
**示例:**
|
||||
|
||||
```md
|
||||
{{</* mermaid */>}}
|
||||
graph LR;
|
||||
A[Lemons]-->B[Lemonade];
|
||||
B-->C[Profit]
|
||||
{{</* /mermaid */>}}
|
||||
```
|
||||
|
||||
{{< mermaid >}}
|
||||
graph LR;
|
||||
A[Lemons]-->B[Lemonade];
|
||||
B-->C[Profit]
|
||||
{{< /mermaid >}}
|
||||
|
||||
您可以在 [图表和流程图示例]({{< ref "diagrams-flowcharts" >}}) 页面上看到一些额外的 Mermaid 示例。
|
||||
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 23 KiB |
@@ -0,0 +1,97 @@
|
||||
---
|
||||
title: "What's New in 2.0 ✨"
|
||||
date: 2022-01-19
|
||||
draft: false
|
||||
description: "Congo 2.0の新機能について"
|
||||
summary: "Version 2.0では、Congoを新たな高みへと導き、その軽量さを維持しながらも、テーマをさらに強力なものにしています。"
|
||||
tags: ["new", "docs"]
|
||||
---
|
||||
|
||||
{{< lead >}}
|
||||
Congo 2.0には、大量の新機能と最適化が詰め込まれています。
|
||||
{{< /lead >}}
|
||||
|
||||
Congoの当初の目的は、シンプルで軽量なテーマを開発することでした。Version 2では、これをさらに一歩進め、軽量でありながら、よりパワフルなテーマとなっています。
|
||||
|
||||
新機能については以下をご覧ください。アップグレードの準備ができましたら、[アップグレードガイド]({{< ref "upgrade" >}})をご覧ください。
|
||||
|
||||
## Tailwind CSS 3.0
|
||||
|
||||
Tailwind CSSはCongoの中核であり、この新しいリリースには最新の[Tailwind CSS version 3](https://tailwindcss.com/blog/tailwindcss-v3)が含まれています。Tailwind CSS 3.0では、パフォーマンスが最適化され、新しいCSS機能がサポートされています。
|
||||
|
||||
{{< youtube "TmWIrBPE6Bc" >}}
|
||||
|
||||
この新バージョンを実装することで、テーマからTailwindプラグインの依存関係をいくつか削除し、全体的なフットプリントを軽量に保つことができるようになりました。
|
||||
|
||||
## 多言語対応
|
||||
|
||||
要望の多かった多言語対応を行いました！複数の言語でコンテンツを公開する場合、サイトはすべての翻訳が利用可能な状態で構築されます。
|
||||
|
||||
<div class="text-2xl text-center" style="font-size: 2.8rem">:gb: :de: :fr: :es: :cn: :jp: :brazil: :tr: :bangladesh:</div>
|
||||
|
||||
コミュニティの貢献によって、Congoはすでに[23言語](https://github.com/jpanther/congo/tree/dev/i18n)以上に翻訳されています。新しい翻訳も[Pull Request](https://github.com/jpanther/congo/pulls)からいつでも歓迎しています！
|
||||
|
||||
## Right to Left言語のサポート
|
||||
|
||||
新しいTailwindの利点の一つは、RTL言語サポートを追加する機能です。有効にすると、サイト全体のコンテンツが右から左にリフローされます。テーマ内のすべての要素は、RTL言語でも見栄えが良くなるように再構築されています。
|
||||
|
||||
RTLは言語ごとに制御されるため、プロジェクト内でRTLとLTRの両方のコンテンツを混ぜてマッチさせることができ、テーマはそれに応じて対応します。
|
||||
|
||||
## 画像の自動リサイズ
|
||||
|
||||
Congo 2.0の大きな変更点は、画像の自動リサイズ機能の追加です。Hugo Pipesのパワーを使って、Markdownコンテンツ内の画像が自動的に異なる出力サイズに拡大縮小されるようになりました。これらの画像はHTMLの `srcset` 属性を使って表示され、サイト訪問者に最適化されたファイルサイズを提供することができます。
|
||||
|
||||
|
||||
|
||||
```html
|
||||
<!-- Markdown:  -->
|
||||
<img
|
||||
srcset="
|
||||
/image_320x0_resize_q75_box.jpg 320w,
|
||||
/image_635x0_resize_q75_box.jpg 635w,
|
||||
/image_1024x0_resize_q75_box.jpg 1024w,
|
||||
/image_1270x0_resize_q75_box.jpg 2x"
|
||||
src="/image_635x0_resize_q75_box.jpg"
|
||||
alt="My image"
|
||||
/>
|
||||
```
|
||||
|
||||
あなたは何も変更する必要がありません！標準的なMarkdown画像構文を挿入するだけで、あとはテーマにお任せください。もう少しコントロールしたい場合は、 `figure` ショートコードを完全に書き換えて、同じリサイズの利点を提供します。
|
||||
|
||||
## パフォーマンスの改善
|
||||
|
||||
今回のアップデートでは、全体的にパフォーマンスが向上している。今回のリリースの主な目的はLighthouseのスコアを向上させることで、Congoは4つの指標すべてで100点満点を獲得しました。
|
||||
|
||||
{{< screenshot src="lighthouse.jpg" >}}
|
||||
|
||||
個々の変更点が多すぎて、ここでは紹介しきれませんが、さらに詳しく知りたい場合は、[Lighthouseのレポート](lighthouse.html)をご覧ください。実際のパフォーマンスは、サーバーの構成によって異なります。
|
||||
|
||||
## サイト内検索
|
||||
|
||||
[Fuse.js](https://fusejs.io)を利用したサイト内検索で、訪問者が素早く簡単にコンテンツを見つけることができます。すべての検索はクライアントサイドで実行されるため、サーバー上で設定する必要がなく、クエリは超高速で実行されます。サイト設定でこの機能を有効にするだけで準備は完了です。また、フルキーボードナビゲーションにも対応しています！
|
||||
|
||||
## 記事ページ内の目次
|
||||
|
||||
要望の多かった記事ページ内の目次をサポートしました。このページで実際にご覧いただけます。コンテンツは完全にレスポンシブで、異なる画面解像度で利用可能なスペースを活用するように調整されます。
|
||||
|
||||
グローバルまたは記事単位で利用可能な目次は、Hugoの標準設定値を使用して完全にカスタマイズすることができます。
|
||||
|
||||
## アクセシビリティの改善
|
||||
|
||||
より多くの項目にARIA記述を追加し、特定のテキスト要素のコントラストを調整してアクセシビリティを改善しました。
|
||||
|
||||
Congo 2.0では、クイックナビゲーションを可能にする「コンテンツへスキップ」と「トップへスクロール」リンクも導入されています。また、マウスに手を伸ばすことなく検索などの項目を有効にするためのキーボードショートカットもあります。
|
||||
|
||||
新しい画像サイズ変更機能は、 `alt` と `title` 要素の完全なコントロールを提供し、すべての訪問者にアクセシブルな体験を提供します。
|
||||
|
||||
## その他もろもろ
|
||||
|
||||
他にも数え切れないほどの細かな変更があります。記事やリストページでTaxonomyを表示できるようになったり、新しい `headline` の著者パラメーターを使ってホームページをカスタマイズできるようになったり。また、SEOのパフォーマンスをさらに最適化するJSON-LDも改善されています。さらに、一貫したデザイン言語を保証するために、テーマ全体がさらに洗練されました。
|
||||
|
||||
:rocket: 詳細は[full changelog](https://github.com/jpanther/congo/blob/dev/CHANGELOG.md)をご覧ください。
|
||||
|
||||
## Next steps
|
||||
|
||||
準備ができたら[Version 1.xからのアップグレードガイド]({{< ref "upgrade" >}})をお読みください。Congoを初めてお使いになる方は[インストール]({{< ref "docs/installation" >}})に進んでください。
|
||||
|
||||
---
|
||||
@@ -0,0 +1,97 @@
|
||||
---
|
||||
title: "What's New in 2.0 ✨"
|
||||
date: 2022-01-19
|
||||
draft: false
|
||||
description: "Discover what's new in Congo version 2.0."
|
||||
summary: "Version 2 takes Congo to new heights, making the theme even more powerful while still maintaining its lightweight footprint."
|
||||
tags: ["new", "docs"]
|
||||
---
|
||||
|
||||
{{< lead >}}
|
||||
Congo 2.0 is packed with tons of new features and optimisations.
|
||||
{{< /lead >}}
|
||||
|
||||
The original aim of Congo was to develop a theme that was simple and lightweight. Version 2 takes this one step further and makes the theme even more powerful while still maintaining its lightweight footprint.
|
||||
|
||||
Continue reading below to discover what's new. When you're ready to upgrade, check out the [guide to upgrading]({{< ref "upgrade" >}}).
|
||||
|
||||
## Tailwind CSS 3.0
|
||||
|
||||
Tailwind CSS is at the heart of Congo and this new release contains the very latest [Tailwind CSS version 3](https://tailwindcss.com/blog/tailwindcss-v3). It brings with it performance optimisations and support for some great new CSS features.
|
||||
|
||||
{{< youtube "TmWIrBPE6Bc" >}}
|
||||
|
||||
Implementing this new version has also removed some Tailwind plugin dependencies from the theme, allowing the overall footprint to remain lightweight.
|
||||
|
||||
## Multilingual support
|
||||
|
||||
A highly requested feature, Congo is now multilingual! If you publish your content in multiple languages, the site will be built with all the translations available.
|
||||
|
||||
<div class="text-2xl text-center" style="font-size: 2.8rem">:gb: :de: :fr: :es: :cn: :brazil: :tr: :bangladesh:</div>
|
||||
|
||||
Thanks to submissions from the community, Congo has already been translated into [23 languages](https://github.com/jpanther/congo/tree/dev/i18n) with more to be added over time. By the way, [pull requests](https://github.com/jpanther/congo/pulls) for new languages are always welcome!
|
||||
|
||||
## RTL language support
|
||||
|
||||
One of the benefits of the new Tailwind and Multilingual features is the ability to add RTL language support. When enabled, the entire site will reflow content from right-to-left. Every element in the theme has been restyled to ensure it looks great in this mode which aids authors who wish to generate content in RTL languages.
|
||||
|
||||
RTL is controlled on a per-language basis so you can mix and match both RTL and LTR content in your projects and the theme will respond accordingly.
|
||||
|
||||
## Automatic image resizing
|
||||
|
||||
A big change in Congo 2.0 is the addition of automatic image resizing. Using the power of Hugo Pipes, images in Markdown content are now automatically scaled to different output sizes. These are then presented using HTML `srcset` attributes enabling optimised file sizes to be served to your site visitors.
|
||||
|
||||
|
||||
|
||||
```html
|
||||
<!-- Markdown:  -->
|
||||
<img
|
||||
srcset="
|
||||
/image_320x0_resize_q75_box.jpg 320w,
|
||||
/image_635x0_resize_q75_box.jpg 635w,
|
||||
/image_1024x0_resize_q75_box.jpg 1024w,
|
||||
/image_1270x0_resize_q75_box.jpg 2x"
|
||||
src="/image_635x0_resize_q75_box.jpg"
|
||||
alt="My image"
|
||||
/>
|
||||
```
|
||||
|
||||
Best of all there's nothing you need to change! Simply insert standard Markdown image syntax and let the theme do the rest. If you want a little more control, the `figure` shortcode has been completely rewritten to provide the same resizing benefits.
|
||||
|
||||
## Performance improvements
|
||||
|
||||
This update packs performance improvements throughout. A key objective for this release was to improve Lighthouse scores and Congo now scores a perfect 100 on all four metrics.
|
||||
|
||||
{{< screenshot src="lighthouse.jpg" >}}
|
||||
|
||||
There's too many individual changes to highlight them here but the results speak for themselves. If you want to dig deeper, you can [view the Lighthouse report](lighthouse.html). Real world performance will vary based upon server configuration.
|
||||
|
||||
## Site search
|
||||
|
||||
Powered by [Fuse.js](https://fusejs.io), site search allows visitors to quickly and easily find your content. All searches are performed client-side meaning there's nothing to configure on the server and queries are performed super fast. Simply enable the feature in your site configuration and you're all set. Oh, and it also supports full keyboard navigation!
|
||||
|
||||
## Tables of contents
|
||||
|
||||
A highly requested feature, Congo now supports tables of contents on article pages. You can see it in action on this page. The contents are fully responsive and will adjust to take advantage of the space available at different screen resolutions.
|
||||
|
||||
Available on a global or per article basis, the table of contents can be fully customised using standard Hugo configuration values, allowing you to adjust the behaviour to suit your project.
|
||||
|
||||
## Accessibility improvements
|
||||
|
||||
From adding ARIA descriptions to more items or simply adjusting the contrast of certain text elements, this release is the most accessible yet.
|
||||
|
||||
Version 2 also introduces "skip to content" and "scroll to top" links that enable quick navigation. There's also keyboard shortcuts for enabling items like search without reaching for the mouse.
|
||||
|
||||
The new image resizing features also provide full control over `alt` and `title` elements enabling an accessible experience for all visitors.
|
||||
|
||||
## A whole lot more
|
||||
|
||||
There's countless other minor changes to explore. From being able to display taxonomies on articles and list pages, to using the new `headline` author parameter to customise your homepage. There's also improved JSON-LD strucured data which further optimises SEO performance. Plus the entire theme has had extra polish to ensure a consistent design language.
|
||||
|
||||
:rocket: Check out the [full changelog](https://github.com/jpanther/congo/blob/dev/CHANGELOG.md) to learn more.
|
||||
|
||||
## Next steps
|
||||
|
||||
If you're ready to upgrade, read the [upgrading from version 1 guide]({{< ref "upgrade" >}}) to get started. If you're new to Congo, check out the [Installation guide]({{< ref "docs/installation" >}}) to begin a new project.
|
||||
|
||||
---
|
||||
@@ -0,0 +1,97 @@
|
||||
---
|
||||
title: "2.0版本新特性 ✨"
|
||||
date: 2022-01-19
|
||||
draft: false
|
||||
description: "探索Congo 2.0的新功能"
|
||||
summary: "2.0版本将Congo推向新的高度，使主题变得更加强大，同时仍然保持其轻量的特点。"
|
||||
tags: ["new", "docs"]
|
||||
---
|
||||
|
||||
{{< lead >}}
|
||||
Congo 2.0版本中包含了大量的新功能和优化。
|
||||
{{< /lead >}}
|
||||
|
||||
Congo最初的目标是开发一个简单轻量的主题。第2版更进一步，使主题变得更加强大，同时仍然保持其轻量级的特点。
|
||||
|
||||
继续阅读下面的内容，了解新的特性。当您准备升级时，请查看 [升级指南]({{< ref "upgrade" >}})。
|
||||
|
||||
## Tailwind CSS 3.0
|
||||
|
||||
Tailwind CSS是Congo的核心，这个新版本包含最新的 [Tailwind CSS 版本 3](https://tailwindcss.com/blog/tailwindcss-v3)。它带来了性能优化和对一些出色的新CSS功能的支持。
|
||||
|
||||
{{< youtube "TmWIrBPE6Bc" >}}
|
||||
|
||||
实现这个新版本还删除了主题中的一些Tailwind插件依赖，使整体体积保持轻量。
|
||||
|
||||
## 国际化支持
|
||||
|
||||
一个备受期待的功能，Congo现在支持多语言了！如果您发布内容支持多种语言，网站将构建包含所有可用翻译的版本。
|
||||
|
||||
<div class="text-2xl text-center" style="font-size: 2.8rem">:gb: :de: :fr: :es: :cn: :jp: :brazil: :tr: :bangladesh:</div>
|
||||
|
||||
通过社区的贡献，Congo已经被翻译成[23种语言](https://github.com/jpanther/congo/tree/dev/i18n)以上。欢迎随时通过[Pull Request](https://github.com/jpanther/congo/pulls)提交新的翻译！
|
||||
|
||||
## RTL语言支持
|
||||
|
||||
新的Tailwind和多语言功能的一个好处是能够添加RTL（从右到左）语言支持。启用时，整个站点的内容都将从右到左重新排列。主题中的每个元素都经过重新设计，以确保在此模式下看起来很棒，有助于希望使用RTL语言生成内容的作者。
|
||||
|
||||
RTL是基于每种语言的控制，因此您可以在项目中混合和匹配RTL和LTR内容，主题将相应地进行响应。
|
||||
|
||||
## 自动图像调整大小
|
||||
|
||||
Congo 2.0的一个重大变化是添加了自动图像调整大小的功能。利用Hugo Pipes的强大功能，Markdown内容中的图像现在会自动缩放到不同的输出大小。然后使用HTML的 `srcset` 属性来呈现，从而能够为您的站点访问者提供优化过的文件大小。
|
||||
|
||||
|
||||
|
||||
```html
|
||||
<!-- Markdown:  -->
|
||||
<img
|
||||
srcset="
|
||||
/image_320x0_resize_q75_box.jpg 320w,
|
||||
/image_635x0_resize_q75_box.jpg 635w,
|
||||
/image_1024x0_resize_q75_box.jpg 1024w,
|
||||
/image_1270x0_resize_q75_box.jpg 2x"
|
||||
src="/image_635x0_resize_q75_box.jpg"
|
||||
alt="My image"
|
||||
/>
|
||||
```
|
||||
|
||||
最重要的是，您无需进行任何更改！只需插入标准的Markdown图像语法，让主题来处理其余的事情。如果您想要更多控制，`figure` shortcode已经完全重写，以提供相同的调整大小优势。
|
||||
|
||||
## 性能优化
|
||||
|
||||
此更新在整个主题中进行了性能优化。这个版本的一个关键目标是提高Lighthouse分数，而现在Congo在所有四个指标上都得分完美的100。
|
||||
|
||||
{{< screenshot src="lighthouse.jpg" >}}
|
||||
|
||||
有太多单独的更改，无法在这里一一突出显示，但结果不言而喻。如果您想深入了解，可以[查看Lighthouse报告](lighthouse.html)。实际的性能将根据服务器配置而有所不同。
|
||||
|
||||
## 站内搜索
|
||||
|
||||
该功能由 [Fuse.js](https://fusejs.io) 提供支持，站内搜索允许访问者快速轻松地找到您的内容。所有搜索都在客户端执行，这意味着在服务器上无需进行任何配置，查询速度非常快。只需在站点配置中启用此功能，就可以轻松使用。对了，它还支持完整的键盘导航！
|
||||
|
||||
## 目录
|
||||
|
||||
这是一个备受期待的功能，Congo现在支持在文章页面上显示目录。您可以在此页面上看到它的效果。目录是完全响应式的，将根据不同屏幕分辨率的可用空间进行调整。
|
||||
|
||||
可以在全局或每篇文章的基础上使用，目录可以使用标准的Hugo配置值进行全面定制，从而使您能够调整其行为以适应您的项目。
|
||||
|
||||
## 可访问性改进
|
||||
|
||||
从为更多项目添加ARIA描述到可以调整某些文本元素的对比度，此版本是迄今为止最具可访问性的。
|
||||
|
||||
第2版还引入了"跳转到内容"和"返回顶部"的链接，以实现快速导航。还有用于启用诸如搜索之类的项目的键盘快捷键，无需使用鼠标。
|
||||
|
||||
新的图像调整大小功能还提供对`alt`和`title`元素的完全控制，为所有访问者提供了可访问的体验。
|
||||
|
||||
## 还有很多改进
|
||||
|
||||
还有无数其他的小改变值得探索。从能够在文章和列表页面上显示分类法，到使用新的`headline`作者参数自定义您的主页。还有改进的JSON-LD结构化数据，进一步优化了SEO性能。此外，整个主题都经过了额外的润色，以确保一致的设计语言。
|
||||
|
||||
:rocket: 查看[完整的更改日志](https://github.com/jpanther/congo/blob/dev/CHANGELOG.md)以了解更多信息。
|
||||
|
||||
## 下一步
|
||||
|
||||
如果您准备升级，请阅读 [从版本1升级的指南]({{< ref "upgrade" >}}) 开始。如果您是Congo的新用户，请查看 [安装指南]({{< ref "docs/installation" >}}) 开始一个新项目。
|
||||
|
||||
---
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 247 KiB |
File diff suppressed because one or more lines are too long
Binary file not shown.
|
After Width: | Height: | Size: 63 KiB |
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 13 KiB |
@@ -0,0 +1,198 @@
|
||||
---
|
||||
title: "Congo 1.xからのアップグレード"
|
||||
date: 2022-01-20
|
||||
draft: false
|
||||
description: "Congo 1.xからのアップグレード"
|
||||
tags: ["new", "docs"]
|
||||
---
|
||||
|
||||
Congo 2.0には多くの変更点が含まれていますが、最新リリースへのアップグレードに必要な労力を最小限に抑えるように設計されています。
|
||||
|
||||
とはいえ、Version 1.xで構築された既存のサイトには、調整が必要な場合もあります。このガイドでは、そのプロセスを順を追って説明し、考慮すべき点を説明します。
|
||||
|
||||
## Step 1: Hugoのアップグレード
|
||||
|
||||
{{< alert >}}
|
||||
Congo 2.0は**Hugo v0.87.0以上**が必要です。
|
||||
{{< /alert >}}
|
||||
|
||||
Congoは、Hugoの最新機能のいくつかを利用するように作られています。問題を避けるために、定期的にHugoのインストールを最新の状態に保つ必要があります。
|
||||
|
||||
Hugoのバージョンは `hugo version` コマンドで確認できます。あなたのプラットフォーム用の新しいリリースを入手する方法については、[Hugoのドキュメント](https://gohugo.io/getting-started/installing/)をご覧ください。
|
||||
|
||||
## Step 2: Congoのアップグレード
|
||||
|
||||
Congoをアップグレードする手順は、プロジェクトにどのようにテーマを含めるかによって異なります。各手順は以下にあります。
|
||||
|
||||
- [Upgrade using Hugo](#upgrade-using-hugo)
|
||||
- [Upgrade using Git](#upgrade-using-git)
|
||||
- [Upgrade manually](#upgrade-manually)
|
||||
|
||||
### Upgrade using Hugo
|
||||
|
||||
Goモジュールを新しいメジャーリリースにアップグレードするには、 `modules.toml` と `go.mod` ファイルを更新する必要があります。それぞれのファイルで、テーマへのパスを `github.com/jpanther/congo` から `github.com/jpanther/congo/v2` に更新してください。
|
||||
|
||||
そして、プロジェクト・ディレクトリに移動し、以下のコマンドを実行してください。
|
||||
|
||||
```shell
|
||||
hugo mod get -u
|
||||
```
|
||||
|
||||
Hugo がローカルにモジュールをキャッシュしているため、状況によってはこのステップで問題が発生する場合があることに注意してください。上記のコマンドがうまくいかない場合は、 `hugo mod clean` を使ってローカルキャッシュを消去し、モジュールを再ダウンロードしてみてください。
|
||||
|
||||
Congoがアップグレードされたら、次のステップに進みます。
|
||||
|
||||
### Upgrade using Git
|
||||
|
||||
Git サブモジュールは `git` コマンドを使ってアップグレードできます。次のコマンドを実行するだけで、最新バージョンのテーマがローカルリポジトリにダウンロードされます:
|
||||
|
||||
```shell
|
||||
git submodule update --remote --merge
|
||||
```
|
||||
|
||||
サブモジュールがアップデートされたら、次のステップに進みます。
|
||||
|
||||
### Upgrade manually
|
||||
|
||||
Congoを手動で更新するには、テーマの最新コピーをダウンロードして、プロジェクト内の古いバージョンを置き換える必要があります。
|
||||
|
||||
{{< alert >}}
|
||||
テーマファイルに対して行ったローカルでのカスタマイズは、この処理中に失われますのでご注意ください。
|
||||
{{< /alert >}}
|
||||
|
||||
1. テーマのソースコードの最新リリースをダウンロードする。
|
||||
|
||||
{{< button href="https://github.com/jpanther/congo/releases/latest" target="_blank" >}}Download from Github{{< /button >}}
|
||||
|
||||
2. アーカイブを解凍し、ディレクトリ名を `congo` に変更して、Hugoプロジェクトのルートディレクトリ内の `themes/` ディレクトリに移動します。すべてのテーマファイルを置き換えるには、既存のディレクトリを上書きする必要があります。
|
||||
|
||||
3. 次のステップに進んでください。
|
||||
|
||||
## Step 3: テーマの設定
|
||||
|
||||
Congo 2.0では新しいテーマ設定パラメーターが多数導入されています。このテーマは既存のバージョン1の設定に適応しますが、より新しいテーマ機能のいくつかを利用するためには、既存の設定を調整する必要があります。
|
||||
|
||||
これを行う最も簡単な方法は、テーマのデフォルト設定のコピーを取り、既存のファイルと比較することです。以下にその手順を詳しく説明します。
|
||||
|
||||
### languages.toml
|
||||
|
||||
多言語サポートを提供するために、言語固有のテーマパラメーターは新しい設定ファイル `languages.[lang-code].toml` に移動されました。テーマにはテンプレート `languages.en.toml` ファイルが付属しており、ガイドとして使用することができます。
|
||||
|
||||
{{< alert >}}
|
||||
多言語サポートが必要ない場合は、このステップは必要ありません。
|
||||
{{< /alert >}}
|
||||
|
||||
言語設定ファイルはこのような構造になっています:
|
||||
|
||||
```toml
|
||||
# config/_default/languagues.en.toml
|
||||
|
||||
languageCode = "en"
|
||||
languageName = "English"
|
||||
displayName = "EN"
|
||||
htmlCode = "en"
|
||||
weight = 1
|
||||
rtl = false
|
||||
|
||||
# Language-specific parameters go here
|
||||
```
|
||||
|
||||
お好みの言語を使って、 `config/_default/` に新しいファイルを作成し、既存の設定ファイルから言語固有のパラメーターをこの新しいファイルに移動するだけです。下の表は移動させる必要のあるパラメーターの概要です。
|
||||
|
||||
| Parameter | Old location |
|
||||
| ------------- | ------------- |
|
||||
| `title` | `config.toml` |
|
||||
| `description` | `params.toml` |
|
||||
| `copyright` | `config.toml` |
|
||||
| `dateFormat` | `params.toml` |
|
||||
| `[author]` | `config.toml` |
|
||||
|
||||
値を移行したら、これらのパラメーターは元の場所から削除すべきです。
|
||||
|
||||
### menus.toml
|
||||
|
||||
テーマが言語を認識するようになったので、 `menus.toml` ファイルの名前も言語コードを含むように変更する必要があります。既存の `menus.toml` を `menus.[lang-code].toml` にリネームしてください。言語コードは前のセクションの `languages.toml` ファイルで使用したコードと同じです。
|
||||
|
||||
### config.toml
|
||||
|
||||
config.toml`ファイルには、Hugoの基本設定値のみが含まれるようになりました。上記の言語固有の文字列を削除した以外に、考慮すべき変更は2つだけです。
|
||||
|
||||
英語以外の言語を使用している場合は、その言語用に作成した設定ファイルの言語コードと一致する `defaultContentLanguage` 値を指定してください。次に、Congo 2.0の新しいサイト内検索を利用するために、 `[outputs]` ブロックを用意する必要があります。
|
||||
|
||||
```toml
|
||||
# config/_default/config.toml
|
||||
|
||||
defaultContentLanguage = "en"
|
||||
|
||||
enableRobotsTXT = true
|
||||
paginate = 10
|
||||
summaryLength = 0
|
||||
|
||||
[outputs]
|
||||
home = ["HTML", "RSS", "JSON"]
|
||||
```
|
||||
|
||||
### markup.toml
|
||||
|
||||
Congo 2.0では記事ページの目次がサポートされました。Hugoには目次を生成するためのデフォルト設定が同梱されていますが、 `markup.toml` ファイルに新しい `[tableOfContents]` ブロックを追加することで、この動作を調整することができます。
|
||||
|
||||
推奨設定は以下のとおりで、目次にレベル2、3、4のの見出しを含みます:
|
||||
|
||||
```toml
|
||||
# config/_default/markup.toml
|
||||
|
||||
[tableOfContents]
|
||||
startLevel = 2
|
||||
endLevel = 4
|
||||
```
|
||||
|
||||
### params.toml
|
||||
|
||||
Congo 2.0では多くの新しいテーマ・パラメーターが導入されました。既存の設定にも若干の変更が必要です。パラメーターが提供されない場合、常にデフォルト値に戻ることを覚えておいてください。
|
||||
|
||||
Congoでのダークモードの動作方法が変更され、より柔軟に設定できるようになりました。従来の `darkMode` と `darkToggle` パラメーターは **削除され、3つの新しいパラメーターに置き換えられました**。これらの新しいオプションはそれぞれ独立して動作するため、強制的に表示させることができ、またユーザーが上書きすることもできます。
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
| New parameter | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `defaultAppearance` | String | `"light"` | デフォルトの外観; `light` か `dark` のどちらか。<br>:warning: _`light` に設定すると以前の `darkMode = false` の設定が再現され、 `dark` に設定すると `darkMode = true` の設定が再現される。_ |
|
||||
| `autoSwitchAppearance` | Boolean | `true` | 外観をオペレーティングシステムの環境設定に基づいて自動的に切り替えるかどうか。 `false` に設定すると、常に `defaultAppearance` を使用します。 <br>:warning: _これを `true` にすることで以前の `darkMode = "auto"` 設定が再現されます。_ |
|
||||
| `showAppearanceSwitcher` | Boolean | `false` | 外観スイッチャーをフッターに表示するかどうか。 <br>:warning: _この設定は `darkToggle` を置き換えます。_ |
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
次の表は、Version 2の新機能を制御する、その他の主要なパラメーターの概要です:
|
||||
|
||||
| New parameter | Type | Default |
|
||||
| ----------------------------- | ------- | ------- |
|
||||
| `enableSearch` | Boolean | `false` |
|
||||
| `showScrollToTop` | Boolean | `true` |
|
||||
| `article.showTaxonomies` | Boolean | `false` |
|
||||
| `article.showTableOfContents` | Boolean | `false` |
|
||||
| `list.showTableOfContents` | Boolean | `false` |
|
||||
|
||||
サポートされるすべてのパラメーターについては[設定]({{< ref "docs/configuration" >}})を参照ください。
|
||||
|
||||
## Step 4: assetsの移動
|
||||
|
||||
ファビコンを除くすべてのassetsが、Hugo Pipesにて最適化されるようになりました。テーマがあなたのファイルを見つけるためには、以前の `static/` から `assets/` ディレクトリに移動する必要があります。主に、著者画像とサイトロゴです:
|
||||
|
||||
`static/me.jpg` **→** `assets/me.jpg`
|
||||
`static/logo.jpg` **→** `assets/logo.jpg`
|
||||
|
||||
著者画像やサイトロゴを提供した場合は、これらのアセットを `static/` から `assets/` に移動するだけです。同じディレクトリ構造を使用している場合、テーマはこれらのファイルがどこにあるかを自動的に認識します。新しいパスを指定したい場合は、 `logo` と `author.image` の設定値を適宜更新してください。
|
||||
|
||||
このステップは、プロジェクト内の静的なassetsには適用されないことに注意してください。例えば、記事内から直接リンクしているPDFファイルは静的なassetsです。これらのファイルは、Hugoがサイトを構築するときに出力ディレクトリに確実にコピーされるよう、`static/` ディレクトリに残しておく必要があります。
|
||||
|
||||
## Step 5: コンテンツの確認
|
||||
|
||||
Congo 2.0では `figure` ショートコードの振る舞いが変わります。記事内で `figure` を使用している場合、パラメーターを調整する必要があるかもしれません。
|
||||
|
||||
サポートされているパラメーターについては、[shortcode]({{< ref "docs/shortcodes#figure" >}})を参照してください。
|
||||
|
||||
## Step 6: 再構築
|
||||
|
||||
これですべての設定変更が完了したので、いよいよサイトを再構築します。 `hugo` またはあなたのビルドコマンドを実行し、すべてが期待通りに動作することを確認してください。
|
||||
|
||||
エラーに遭遇した場合は、設定が正しいことを確認し、[ドキュメント]({{<ref "docs" >}})を参照してください。テーマに同梱されている設定ファイルの例には、デフォルトのパラメーターがすべて含まれており、出発点として最適です。
|
||||
|
||||
🙋♀️ それでもまだ助けが必要な場合は、[GitHub Discussions](https://github.com/jpanther/congo/discussions)で遠慮なく質問してください。
|
||||
@@ -0,0 +1,198 @@
|
||||
---
|
||||
title: "Upgrading from Congo 1.x"
|
||||
date: 2022-01-20
|
||||
draft: false
|
||||
description: "Discover what's new in Congo version 2.0."
|
||||
tags: ["new", "docs"]
|
||||
---
|
||||
|
||||
Although Congo 2.0 contains a large number of changes, the theme has been designed to minimise the effort required to upgrade to the latest release.
|
||||
|
||||
That said, there are some changes that require adjustments to existing sites that are built with Congo version 1.x. This guide will step you through the process and highlight things you need to consider.
|
||||
|
||||
## Step 1: Upgrade Hugo
|
||||
|
||||
{{< alert >}}
|
||||
Congo 2.0 requires a minimum of **Hugo v0.87.0 or later**
|
||||
{{< /alert >}}
|
||||
|
||||
Congo is built to take advantage of some of the latest Hugo features. You should regularly keep your Hugo installation up to date to avoid any issues.
|
||||
|
||||
You can check your current version using the command `hugo version`. Visit the [Hugo docs](https://gohugo.io/getting-started/installing/) for information on obtaining a newer release for your platform.
|
||||
|
||||
## Step 2: Upgrade Congo
|
||||
|
||||
The process for upgrading Congo will depend on how you include the theme in your project. Instructions for each method can be found below.
|
||||
|
||||
- [Upgrade using Hugo](#upgrade-using-hugo)
|
||||
- [Upgrade using git](#upgrade-using-git)
|
||||
- [Upgrade manually](#upgrade-manually)
|
||||
|
||||
### Upgrade using Hugo
|
||||
|
||||
To upgrade a go module to a new major release, the `modules.toml` and `go.mod` files need to be updated. In each file, update the path to the theme from `github.com/jpanther/congo` to `github.com/jpanther/congo/v2`.
|
||||
|
||||
Then change into your project directory and execute the following command:
|
||||
|
||||
```shell
|
||||
hugo mod get -u
|
||||
```
|
||||
|
||||
Note that in some circumstances there may be issues with this step due to the way that Hugo locally caches modules. If the command above doesn't work, try using `hugo mod clean` to clear out the local cache and re-download any modules.
|
||||
|
||||
Once the theme has been upgraded, continue to the [next section](#step-3-theme-configuration).
|
||||
|
||||
### Upgrade using git
|
||||
|
||||
Git submodules can be upgraded using the `git` command. Simply execute the following command and the latest version of the theme will be downloaded into your local repository:
|
||||
|
||||
```shell
|
||||
git submodule update --remote --merge
|
||||
```
|
||||
|
||||
Once the submodule has been upgraded, continue to the [next section](#step-3-theme-configuration).
|
||||
|
||||
### Upgrade manually
|
||||
|
||||
Updating Congo manually requires you to download the latest copy of the theme and replace the old version in your project.
|
||||
|
||||
{{< alert >}}
|
||||
Note that any local customisations you have made to the theme files will be lost during this process.
|
||||
{{< /alert >}}
|
||||
|
||||
1. Download the latest release of the theme source code.
|
||||
|
||||
{{< button href="https://github.com/jpanther/congo/releases/latest" target="_blank" >}}Download from Github{{< /button >}}
|
||||
|
||||
2. Extract the archive, rename the folder to `congo` and move it to the `themes/` directory inside your Hugo project's root folder. You will need to overwrite the existing directory to replace all the theme files.
|
||||
|
||||
3. Continue to the [next section](#step-3-theme-configuration).
|
||||
|
||||
## Step 3: Theme configuration
|
||||
|
||||
Congo 2.0 introduces a number of new theme configuration parameters. Although the theme will adapt to existing version 1 configurations, in order to take advantage of some of the newer theme features, you will need to adjust your existing configuration.
|
||||
|
||||
The simplest way to do this is to take a copy of the theme's default configuration and compare it to your existing files. The process is outlined in greater detail below.
|
||||
|
||||
### Languages.toml
|
||||
|
||||
In order to provide multilingual support, language-specific theme parameters have been moved to a new config file `languages.[lang-code].toml`. The theme comes with a template `languages.en.toml` file which can be used as a guide.
|
||||
|
||||
{{< alert >}}
|
||||
This step is optional if you do not need multilingual support, although completing it now will make future theme upgrades easier.
|
||||
{{< /alert >}}
|
||||
|
||||
The languages config file follows this structure:
|
||||
|
||||
```toml
|
||||
# config/_default/languagues.en.toml
|
||||
|
||||
languageCode = "en"
|
||||
languageName = "English"
|
||||
displayName = "EN"
|
||||
htmlCode = "en"
|
||||
weight = 1
|
||||
rtl = false
|
||||
|
||||
# Language-specific parameters go here
|
||||
```
|
||||
|
||||
Using your preferred language, simply create this new file in `config/_default/` and then move the language-specific parameters from any existing config files over to this new file. The table below outlines the parameters that need to be moved.
|
||||
|
||||
| Parameter | Old location |
|
||||
| ------------- | ------------- |
|
||||
| `title` | `config.toml` |
|
||||
| `description` | `params.toml` |
|
||||
| `copyright` | `config.toml` |
|
||||
| `dateFormat` | `params.toml` |
|
||||
| `[author]` | `config.toml` |
|
||||
|
||||
Once the values have been moved to the new location, these parameters should be deleted from their original locations.
|
||||
|
||||
### Menus.toml
|
||||
|
||||
As the theme is now aware of languages, the `menus.toml` file should also be renamed to include a language code. Rename the existing `menus.toml` to `menus.[lang-code].toml`, where the language code matches the code used in the `languages.toml` file in the previous section.
|
||||
|
||||
### Config.toml
|
||||
|
||||
The `config.toml` file now only contains base Hugo configuration values. Other than removing the language-specific strings above, there are only two changes to consider.
|
||||
|
||||
If you're using a language other than English, provide a `defaultContentLanguage` value that matches the language code in the config file you created for your language. Secondly, to take advange of the new site search in Congo 2.0, an `[outputs]` block needs to be provided.
|
||||
|
||||
```toml
|
||||
# config/_default/config.toml
|
||||
|
||||
defaultContentLanguage = "en"
|
||||
|
||||
enableRobotsTXT = true
|
||||
paginate = 10
|
||||
summaryLength = 0
|
||||
|
||||
[outputs]
|
||||
home = ["HTML", "RSS", "JSON"]
|
||||
```
|
||||
|
||||
### Markup.toml
|
||||
|
||||
Congo 2.0 adds support for tables of contents on article pages. Although Hugo ships with default settings for generating contents listings, you can adjust this behaviour by adding a new `[tableOfContents]` block to your `markup.toml` file.
|
||||
|
||||
The recommended settings are as follows, which includes any headings in the Markdown content at levels 2, 3 and 4:
|
||||
|
||||
```toml
|
||||
# config/_default/markup.toml
|
||||
|
||||
[tableOfContents]
|
||||
startLevel = 2
|
||||
endLevel = 4
|
||||
```
|
||||
|
||||
### Params.toml
|
||||
|
||||
A number of new theme parameters have been introduced in Congo 2.0. Some minor changes are requried to existing configurations. Remember, the theme will always revert to a sensible default if a parameter is not provided.
|
||||
|
||||
The way that dark mode works in Congo has been changed to allow greater flexibility around configuration. The old `darkMode` and `darkToggle` parameters have been **removed and replaced** by three new parameters. These new options operate independently of each other, making it possible to force the appearance while still allowing the user to override.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
| New parameter | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `defaultAppearance` | String | `"light"` | Default theme appearance; either `light` or `dark`.<br>:warning: _Setting this to `light` replicates the old `darkMode = false` setting, while `dark` replicates `darkMode = true`._ |
|
||||
| `autoSwitchAppearance` | Boolean | `true` | Whether the theme appearance automatically switches based upon the operating system preference. Set to `false` to force the site to always use the `defaultAppearance`. <br>:warning: _Setting this to `true` replicates the old `darkMode = "auto"` setting._ |
|
||||
| `showAppearanceSwitcher` | Boolean | `false` | Whether the theme appearance switcher is dispalyed in the site footer. <br>:warning: _This parameter replaces `darkToggle`._ |
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
The following table outlines some other key **new parameters** that control new features in version 2:
|
||||
|
||||
| New parameter | Type | Default |
|
||||
| ----------------------------- | ------- | ------- |
|
||||
| `enableSearch` | Boolean | `false` |
|
||||
| `showScrollToTop` | Boolean | `true` |
|
||||
| `article.showTaxonomies` | Boolean | `false` |
|
||||
| `article.showTableOfContents` | Boolean | `false` |
|
||||
| `list.showTableOfContents` | Boolean | `false` |
|
||||
|
||||
For the full list of supported parameters, refer to the [Configuration]({{< ref "docs/configuration" >}}) docs.
|
||||
|
||||
## Step 4: Move assets
|
||||
|
||||
All site assets, with the exception of favicons, now use Hugo Pipes to build an optimised version of your project. In order for the theme to locate your files, any previously static theme assets need to be moved to the Hugo assets folder. Primarily this is the author image and site logo:
|
||||
|
||||
`static/me.jpg` **→** `assets/me.jpg`
|
||||
`static/logo.jpg` **→** `assets/logo.jpg`
|
||||
|
||||
If you have provided an author image or site logo, simply move these assets from `static/` to `assets/`. If you use the same directory structure the theme will know where to find these files automatically. If you would like to provide a new path, update the `logo` and `author.image` config values accordingly.
|
||||
|
||||
Note that this step does not apply to any assets in your project that are actually static. For example, a PDF file that you link directly to from within an article is a static asset. These files should remain in the `static/` directory to ensure they are copied to the output folder when Hugo builds the site.
|
||||
|
||||
## Step 5: Check content
|
||||
|
||||
The behavior of the `figure` shortcode is different in version 2. If you are using `figure` in your content and have advanced use cases, you may need to adjust the parameters you are providing.
|
||||
|
||||
Consult the [shortcode docs]({{< ref "docs/shortcodes#figure" >}}) to learn more about supported parameters.
|
||||
|
||||
## Step 6: Rebuild
|
||||
|
||||
Now that all the configuration changes are complete, it's time to rebuild the site. Run `hugo`, or your build command, and check that everything works as expected.
|
||||
|
||||
If you come across any errors, check the configuration is correct and refer to the [full documentation]({{< ref "docs" >}}) for further guidance. Remember, the example config files bundled with the theme contain all the default parameters and are a great starting point.
|
||||
|
||||
🙋♀️ If you still need help, feel free to ask your question on [GitHub Discussions](https://github.com/jpanther/congo/discussions).
|
||||
@@ -0,0 +1,223 @@
|
||||
---
|
||||
title: "从Congo 1.x升级"
|
||||
date: 2022-01-20
|
||||
draft: false
|
||||
description: "探索2.0的新特性"
|
||||
tags: ["new", "docs"]
|
||||
---
|
||||
|
||||
尽管 Congo 2.0 包含大量变化，但主题已经经过设计，以最小化升级到最新版本所需的努力。
|
||||
|
||||
话虽如此，有一些变化需要调整使用 Congo 1.x 构建的现有站点。本指南将引导你完成整个过程，并突出需要考虑的事项。
|
||||
|
||||
## 步骤1：升级Hugo
|
||||
|
||||
{{< alert >}}
|
||||
Congo 2.0 要求最低 **Hugo v0.87.0 或更高版本**
|
||||
{{< /alert >}}
|
||||
|
||||
Congo被设计以充分利用一些最新的Hugo功能。为避免任何问题，你应该定期保持Hugo的安装版本。
|
||||
|
||||
你可以使用命令 `hugo version` 检查你当前的版本。请访问[Hugo文档](https://gohugo.io/getting-started/installing/)获取适用于你平台的更新版本的信息。
|
||||
|
||||
## 步骤2：升级Congo
|
||||
|
||||
升级Congo的过程取决于你如何在项目中引入主题。每种方法的说明如下。
|
||||
|
||||
- [使用Hugo升级](#使用Hugo升级)
|
||||
- [使用git升级](#使用git升级)
|
||||
- [手动升级](#手动升级)
|
||||
|
||||
### 使用Hugo升级
|
||||
|
||||
要将go模块升级到新的主版本，需要更新 `modules.toml` 和 `go.mod` 文件。在每个文件中，将主题的路径从 `github.com/jpanther/congo` 更新为 `github.com/jpanther/congo/v2`。
|
||||
|
||||
然后进入你的项目目录并执行以下命令：
|
||||
|
||||
```shell
|
||||
hugo mod get -u
|
||||
```
|
||||
|
||||
请注意，在某些情况下，由于Hugo本地缓存模块的方式，此步骤可能会出现问题。如果上述命令不起作用，请尝试使用 `hugo mod clean` 来清除本地缓存并重新下载任何模块。
|
||||
|
||||
一旦主题已经升级，继续到[下一节](#步骤-3-主题配置)。
|
||||
|
||||
### 使用git升级
|
||||
|
||||
可以使用`git`命令升级Git子模块。只需执行以下命令，最新版本的主题将被下载到你的本地存储库中：
|
||||
|
||||
```shell
|
||||
git submodule update --remote --merge
|
||||
```
|
||||
|
||||
一旦子模块升级完成，继续到[下一节](#step-3-theme-configuration)。
|
||||
|
||||
### 手动升级
|
||||
|
||||
手动更新Congo需要下载主题的最新副本，并替换项目中的旧版本。
|
||||
|
||||
{{< alert >}}
|
||||
请注意，在此过程中，您对主题文件所做的任何本地自定义将会丢失。
|
||||
{{< /alert >}}
|
||||
|
||||
1. 下载主题源代码的最新发布。
|
||||
|
||||
{{< button href="https://github.com/jpanther/congo/releases/latest" target="_blank" >}}从Github下载{{< /button >}}
|
||||
|
||||
2. 解压缩存档，将文件夹重命名为 `congo` 并将其移动到Hugo项目根目录下的 `themes/` 目录。你需要覆盖现有目录以替换所有主题文件。
|
||||
|
||||
3. 继续到[下一节](#step-3-theme-configuration)。
|
||||
|
||||
## 步骤 3：主题配置
|
||||
|
||||
Congo 2.0 引入了许多新的主题配置参数。虽然主题会适应现有的版本1配置，但为了利用一些新的主题功能，你需要调整你现有的配置。
|
||||
|
||||
最简单的方法是复制主题的默认配置并将其与你的现有文件进行比较。下面详细介绍了这个过程。
|
||||
|
||||
### Languages.toml
|
||||
|
||||
为了提供多语言支持，特定于语言的主题参数已移至新的配置文件 `languages.[lang-code].toml`。主题附带一个模板文件 `languages.en.toml`，可作为参考。
|
||||
|
||||
{{< alert >}}
|
||||
如果您不需要多语言支持，此步骤是可选的，但现在完成它将使未来的主题升级更容易。
|
||||
{{< /alert >}}
|
||||
|
||||
语言配置文件遵循以下结构：
|
||||
|
||||
```toml
|
||||
# config/_default/languagues.en.toml
|
||||
|
||||
languageCode = "en"
|
||||
languageName = "English"
|
||||
displayName = "EN"
|
||||
htmlCode = "en"
|
||||
weight = 1
|
||||
rtl = false
|
||||
|
||||
# Language-specific parameters go here
|
||||
```
|
||||
|
||||
### Languages.toml
|
||||
|
||||
为了提供多语言支持，特定于语言的主题参数已移至新的配置文件 `languages.[lang-code].toml`。主题附带一个模板文件 `languages.en.toml`，可作为参考。
|
||||
|
||||
{{< alert >}}
|
||||
如果您不需要多语言支持，此步骤是可选的，但现在完成它将使未来的主题升级更容易。
|
||||
{{< /alert >}}
|
||||
|
||||
语言配置文件遵循以下结构：
|
||||
|
||||
```toml
|
||||
# config/_default/languagues.en.toml
|
||||
|
||||
languageCode = "en"
|
||||
languageName = "English"
|
||||
displayName = "EN"
|
||||
htmlCode = "en"
|
||||
weight = 1
|
||||
rtl = false
|
||||
|
||||
# 此处放置特定于语言的参数
|
||||
```
|
||||
|
||||
使用你喜欢的语言，在 `config/_default/` 中创建这个新文件，然后将任何现有配置文件中的特定于语言的参数移到这个新文件中。下表概述了需要移动的参数。
|
||||
|
||||
| 参数 | 旧位置 |
|
||||
| ------------- | ------------- |
|
||||
| `title` | `config.toml` |
|
||||
| `description` | `params.toml` |
|
||||
| `copyright` | `config.toml` |
|
||||
| `dateFormat` | `params.toml` |
|
||||
| `[author]` | `config.toml` |
|
||||
|
||||
一旦值已经移动到新位置，应该从其原始位置删除这些参数。
|
||||
|
||||
### Menus.toml
|
||||
|
||||
由于主题现在支持多语言，`menus.toml` 文件也应该重命名，包含语言代码。将现有的 `menus.toml` 重命名为 `menus.[lang-code].toml`，其中语言代码与前一节中的 `languages.toml` 文件中使用的代码匹配。
|
||||
|
||||
### Config.toml
|
||||
|
||||
`config.toml` 文件现在只包含基本的Hugo配置值。除了删除上述特定于语言的字符串之外，只有两个更改需要考虑。
|
||||
|
||||
如果你使用的是英语以外的语言，请提供一个与你为语言创建的配置文件中的语言代码匹配的 `defaultContentLanguage` 值。其次，为了利用Congo 2.0中的新站点搜索，需要提供一个 `[outputs]` 块。
|
||||
|
||||
```toml
|
||||
# config/_default/config.toml
|
||||
|
||||
defaultContentLanguage = "en"
|
||||
|
||||
enableRobotsTXT = true
|
||||
paginate = 10
|
||||
summaryLength = 0
|
||||
|
||||
[outputs]
|
||||
home = ["HTML", "RSS", "JSON"]
|
||||
```
|
||||
|
||||
### Markup.toml
|
||||
|
||||
Congo 2.0 添加了对文章页面上目录的支持。尽管Hugo默认提供了生成目录列表的默认设置，你可以通过在 `markup.toml` 文件中添加一个新的 `[tableOfContents]` 块来调整此行为。
|
||||
|
||||
建议的设置如下，包括Markdown内容中的任何标题，级别为2、3和4：
|
||||
|
||||
```toml
|
||||
# config/_default/markup.toml
|
||||
|
||||
[tableOfContents]
|
||||
startLevel = 2
|
||||
endLevel = 4
|
||||
```
|
||||
|
||||
### Params.toml
|
||||
|
||||
Congo 2.0 引入了许多新的主题参数。一些现有配置需要进行一些小的更改。请记住，如果未提供参数，主题将始终恢复为合理的默认值。
|
||||
|
||||
Congo中深色模式的工作方式已更改，以提供更大的配置灵活性。旧的 `darkMode` 和 `darkToggle` 参数已被 **删除并替换** 为三个新参数。这些新选项彼此独立操作，使得可以强制外观同时仍然允许用户覆盖。
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
| 新参数 | 类型 | 默认值 | 描述 |
|
||||
| --- | --- | --- | --- |
|
||||
| `defaultAppearance` | 字符串 | `"light"` | 默认主题外观；可以是 `light` 或 `dark`。<br>:warning: _将其设置为 `light` 复制了旧的 `darkMode = false` 设置，而 `dark` 复制了 `darkMode = true`。_ |
|
||||
| `autoSwitchAppearance` | 布尔值 | `true` | 主题外观是否根据操作系统首选项自动切换。将其设置为 `false` 可始终强制站点使用 `defaultAppearance`。<br>:warning: _将其设置为 `true` 复制了旧的 `darkMode = "auto"` 设置。_ |
|
||||
| `showAppearanceSwitcher` | 布尔值 | `false` | 主题外观切换器是否显示在站点页脚中。<br>:warning: _此参数替代了 `darkToggle`。_ |
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
以下表格概述了版本2中控制新功能的一些其他关键 **新参数**。
|
||||
|
||||
| 新
|
||||
|
||||
参数 | 类型 | 默认值 |
|
||||
| ----------------------- | ------- | ------- |
|
||||
| `enableSearch` | 布尔值 | `false` |
|
||||
| `showScrollToTop` | 布尔值 | `true` |
|
||||
| `article.showTaxonomies` | 布尔值 | `false` |
|
||||
| `article.showTableOfContents` | 布尔值 | `false` |
|
||||
| `list.showTableOfContents` | 布尔值 | `false` |
|
||||
|
||||
有关支持的所有参数的完整列表，请参阅[配置]({{< ref "docs/configuration" >}})文档。
|
||||
|
||||
## 步骤4：移动assets
|
||||
|
||||
除了favicon之外，现在所有站点assets都使用Hugo Pipes构建项目的优化版本。为了使主题能够定位你的文件，任何先前的静态主题assets需要移动到Hugo资产文件夹。主要是作者图片和站点标志：
|
||||
|
||||
`static/me.jpg` **→** `assets/me.jpg`
|
||||
`static/logo.jpg` **→** `assets/logo.jpg`
|
||||
|
||||
如果你提供了作者图片或站点标志，只需将这些资产从 `static/` 移动到 `assets/`。如果使用相同的目录结构，主题将自动知道在哪里找到这些文件。如果想提供新的路径，相应地更新 `logo` 和 `author.image` 配置值。
|
||||
|
||||
请注意，此步骤不适用于项目中实际上是静态的任何assets。例如，直接从文章中链接的PDF文件是静态资产。这些文件应保留在 `static/` 目录中，以确保在Hugo构建站点时将它们复制到输出文件夹中。
|
||||
|
||||
## 步骤5：检查内容
|
||||
|
||||
版本2中 `figure` 短代码 的行为不同。如果在内容中使用 `figure` 并且有高级用例，可能需要调整提供的参数。
|
||||
|
||||
查阅[短代码文档]({{< ref "docs/shortcodes#figure" >}})以了解有关支持的参数的更多信息。
|
||||
|
||||
## 步骤6：重新构建
|
||||
|
||||
现在所有配置更改都已完成，是时候重新构建站点了。运行 `hugo` 或你的构建命令，并检查一切是否按预期工作。
|
||||
|
||||
如果遇到任何错误，请检查配置是否正确，并参考[完整文档]({{< ref "docs" >}})获取进一步的指导。记住，主题捆绑的示例配置文件包含所有默认参数，并且是一个很好的起点。
|
||||
|
||||
🙋♀️ 如果仍然需要帮助，请随时在[GitHub Discussions](https://github.com/jpanther/congo/discussions)上提问。
|
||||
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 75 KiB |
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: "Beispiele für Inhalte"
|
||||
description: "Sieh dir an, was mit Congo möglich ist."
|
||||
|
||||
cascade:
|
||||
showEdit: false
|
||||
showSummary: true
|
||||
---
|
||||
|
||||
{{< lead >}}
|
||||
Congo erweckt deinen Inhalt zum Leben. :heart_eyes:
|
||||
{{< /lead >}}
|
||||
|
||||
Dieser Abschnitt enthält einige Demoseiten, die zeigen, wie Congo verschiedene Arten von Inhalten wiedergibt. Sie können auch eine Beispielseite für ein [Taxonomieverzeichnis]({{< ref "tags" >}}) sehen.
|
||||
|
||||
_**Hinweis:** Diese Seite ist nur eine standardmäßige Congo-Artikelauflistung und Hugo wurde so konfiguriert, dass er einen Inhaltstyp "Beispiele" generiert und Artikelzusammenfassungen anzeigt._
|
||||
|
||||
---
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: "Páginas de ejemplo"
|
||||
description: "Vea lo que es posible con Congo."
|
||||
|
||||
cascade:
|
||||
showEdit: false
|
||||
showSummary: true
|
||||
---
|
||||
|
||||
{{< lead >}}
|
||||
Congo da vida a su contenido. :heart_eyes:
|
||||
{{< /lead >}}
|
||||
|
||||
Esta sección contiene ejemplos que muestran cómo Congo representa diferentes tipos de contenido. También puedes ver una página con una [lista de taxonomía]({{< ref "tags" >}}) de ejemplo.
|
||||
|
||||
_**Nota al margen:** Esta página es solo una lista estándar de artículos de Congo, y Hugo se ha configurado para generar un tipo de contenido de `ejemplos` y mostrar resúmenes de artículos._
|
||||
|
||||
---
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: "サンプル"
|
||||
description: "Congoの可能性を見てみましょう"
|
||||
|
||||
cascade:
|
||||
showEdit: false
|
||||
showSummary: true
|
||||
---
|
||||
|
||||
{{< lead >}}
|
||||
Congoはあなたのコンテンツに命を吹き込みます :heart_eyes:
|
||||
{{< /lead >}}
|
||||
|
||||
このセクションには、Congoがさまざまなタイプのコンテンツをどのようにレンダリングするかを示すいくつかのデモページがあります。また、[Tags]({{< ref "tags" >}})ページの例も見ることができます。
|
||||
|
||||
_**補足:** このページは標準的なCongoの記事リストであり、Hugoは `samples` コンテンツタイプを生成し、記事の要約を表示するように設定されています。_
|
||||
|
||||
---
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: "Content Samples"
|
||||
description: "See what's possible with Congo."
|
||||
|
||||
cascade:
|
||||
showEdit: false
|
||||
showSummary: true
|
||||
---
|
||||
|
||||
{{< lead >}}
|
||||
Congo brings your content to life. :heart_eyes:
|
||||
{{< /lead >}}
|
||||
|
||||
This section contains some demo pages that show how Congo renders different types of content. You can also see an example [taxonomy listing]({{< ref "tags" >}}) page.
|
||||
|
||||
_**Sidenote:** This page is just a standard Congo article listing and Hugo has been configured to generate a `samples` content type and display article summaries._
|
||||
|
||||
---
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: "内容样例"
|
||||
description: "探索Congo的无限可能"
|
||||
|
||||
cascade:
|
||||
showEdit: false
|
||||
showSummary: true
|
||||
---
|
||||
|
||||
{{< lead >}}
|
||||
Congo让您的内容栩栩如生。 :heart_eyes:
|
||||
{{< /lead >}}
|
||||
|
||||
这个部分包含一些演示页面，展示了Congo 如何呈现不同类型的内容。您还可以查看一个 [分类法列表]({{< ref "tags" >}}) 页面的示例。
|
||||
|
||||
_**附注：** 此页面只是一个标准的Congo文章列表，Hugo已经配置生成了一个`samples`内容类型并显示文章摘要。_
|
||||
|
||||
---
|
||||
@@ -0,0 +1,85 @@
|
||||
---
|
||||
title: "Charts"
|
||||
date: 2019-03-06
|
||||
description: "Leitfaden zur Verwendung von Chart.js mit Congo"
|
||||
summary: "Congo enthält Chart.js für leistungsstarke Charts und Datenvisualisierungen."
|
||||
tags: ["Chart", "Beispiele", "Graph", "Shortcodes"]
|
||||
---
|
||||
|
||||
Congo bietet Unterstützung für Chart.js unter Verwendung des Shortcodes `chart`. Füge einfach das Chart-Markup in den Shortcode ein. Congo gestaltet die Charts automatisch so, dass sie der Konfiguration des Parameters `colorScheme` entsprechen. Die Farben können jedoch mit der normalen Chart.js-Syntax angepasst werden.
|
||||
|
||||
Weitere Details findest du in der [Chart-Shortcode-Dokumentation]({{< ref path="docs/shortcodes#chart" lang="en" >}}).
|
||||
|
||||
Die folgenden Beispiele sind eine kleine Auswahl aus der [offiziellen Chart.js-Dokumentation](https://www.chartjs.org/docs/latest/samples). Du kannst auch [die Quelle der Seite](https://raw.githubusercontent.com/jpanther/congo/dev/exampleSite/content/samples/charts/index.de.md) auf GitHub aufrufen, um das Markup zu sehen.
|
||||
|
||||
## Säulendiagramm
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{{< chart >}}
|
||||
type: 'bar',
|
||||
data: {
|
||||
labels: ['Januar', 'Februar', 'März', 'April', 'Mai', 'Juni', 'Juli'],
|
||||
datasets: [{
|
||||
label: 'Mein erster Datensatz',
|
||||
data: [65, 59, 80, 81, 56, 55, 40],
|
||||
backgroundColor: [
|
||||
'rgba(255, 99, 132, 0.2)',
|
||||
'rgba(255, 159, 64, 0.2)',
|
||||
'rgba(255, 205, 86, 0.2)',
|
||||
'rgba(75, 192, 192, 0.2)',
|
||||
'rgba(54, 162, 235, 0.2)',
|
||||
'rgba(153, 102, 255, 0.2)',
|
||||
'rgba(201, 203, 207, 0.2)'
|
||||
],
|
||||
borderColor: [
|
||||
'rgb(255, 99, 132)',
|
||||
'rgb(255, 159, 64)',
|
||||
'rgb(255, 205, 86)',
|
||||
'rgb(75, 192, 192)',
|
||||
'rgb(54, 162, 235)',
|
||||
'rgb(153, 102, 255)',
|
||||
'rgb(201, 203, 207)'
|
||||
],
|
||||
borderWidth: 1
|
||||
}]
|
||||
}
|
||||
{{< /chart >}}
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## Linien-Diagramm
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{{< chart >}}
|
||||
type: 'line',
|
||||
data: {
|
||||
labels: ['Januar', 'Februar', 'März', 'April', 'Mai', 'Juni', 'Juli'],
|
||||
datasets: [{
|
||||
label: 'Mein erster Datensatz',
|
||||
data: [65, 59, 80, 81, 56, 55, 40],
|
||||
tension: 0.2
|
||||
}]
|
||||
}
|
||||
{{< /chart >}}
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## Doughnut-Chart
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{{< chart >}}
|
||||
type: 'doughnut',
|
||||
data: {
|
||||
labels: ['Rot', 'Blau', 'Gelb'],
|
||||
datasets: [{
|
||||
label: 'Mein erster Datensatz',
|
||||
data: [300, 50, 100],
|
||||
backgroundColor: [
|
||||
'rgba(255, 99, 132, 0.7)',
|
||||
'rgba(54, 162, 235, 0.7)',
|
||||
'rgba(255, 205, 86, 0.7)'
|
||||
],
|
||||
borderWidth: 0,
|
||||
hoverOffset: 4
|
||||
}]
|
||||
}
|
||||
{{< /chart >}}
|
||||
<!-- prettier-ignore-end -->
|
||||
@@ -0,0 +1,87 @@
|
||||
---
|
||||
title: "Gráficos"
|
||||
date: 2019-03-06
|
||||
description: "Guía para usar Chart.js en Congo"
|
||||
summary: "Congo incluye Chart.js para mostrar potentes gráficos y visualizaciones de datos."
|
||||
tags: ["chart", "sample", "graph", "shortcodes"]
|
||||
---
|
||||
|
||||
Congo incluye soporte para Chart.js usando el shortcode `chart`. Simplemente encierra las etiquetas del gráfico dentro del shortcode.
|
||||
|
||||
Congo crea temas de gráficos automáticamente para que coincidan con el parámetro `colorScheme` configurado. Sin embargo, los colores se pueden personalizar usando la sintaxis normal de Chart.js.
|
||||
|
||||
Consulta la documentación del [chart shortcode]({{< ref path="docs/shortcodes#chart" lang="en" >}}) para obtener más detalles.
|
||||
|
||||
Los ejemplos a continuación son una pequeña selección tomada de la [documentación oficial de Chart.js](https://www.chartjs.org/docs/latest/samples). También puedes ver el [código fuente de la página](https://raw.githubusercontent.com/jpanther/congo/dev/exampleSite/content/samples/charts.es.md) en GitHub para ver la sintaxis.
|
||||
|
||||
## Gráfico de barras
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{{< chart >}}
|
||||
type: 'bar',
|
||||
data: {
|
||||
labels: ['Enero', 'Febrero', 'Marzo', 'Abril', 'Mayo', 'Junio', 'Julio'],
|
||||
datasets: [{
|
||||
label: 'Mi primer Dataset',
|
||||
data: [65, 59, 80, 81, 56, 55, 40],
|
||||
backgroundColor: [
|
||||
'rgba(255, 99, 132, 0.2)',
|
||||
'rgba(255, 159, 64, 0.2)',
|
||||
'rgba(255, 205, 86, 0.2)',
|
||||
'rgba(75, 192, 192, 0.2)',
|
||||
'rgba(54, 162, 235, 0.2)',
|
||||
'rgba(153, 102, 255, 0.2)',
|
||||
'rgba(201, 203, 207, 0.2)'
|
||||
],
|
||||
borderColor: [
|
||||
'rgb(255, 99, 132)',
|
||||
'rgb(255, 159, 64)',
|
||||
'rgb(255, 205, 86)',
|
||||
'rgb(75, 192, 192)',
|
||||
'rgb(54, 162, 235)',
|
||||
'rgb(153, 102, 255)',
|
||||
'rgb(201, 203, 207)'
|
||||
],
|
||||
borderWidth: 1
|
||||
}]
|
||||
}
|
||||
{{< /chart >}}
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## Gráfico de linea
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{{< chart >}}
|
||||
type: 'line',
|
||||
data: {
|
||||
labels: ['Enero', 'Febrero', 'Marzo', 'Abril', 'Mayo', 'Junio', 'Julio'],
|
||||
datasets: [{
|
||||
label: 'Mi primer Dataset',
|
||||
data: [65, 59, 80, 81, 56, 55, 40],
|
||||
tension: 0.2
|
||||
}]
|
||||
}
|
||||
{{< /chart >}}
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## Gráfico de anillos
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{{< chart >}}
|
||||
type: 'doughnut',
|
||||
data: {
|
||||
labels: ['Rojo', 'Azul', 'Amarillo'],
|
||||
datasets: [{
|
||||
label: 'Mi primer Dataset',
|
||||
data: [300, 50, 100],
|
||||
backgroundColor: [
|
||||
'rgba(255, 99, 132, 0.7)',
|
||||
'rgba(54, 162, 235, 0.7)',
|
||||
'rgba(255, 205, 86, 0.7)'
|
||||
],
|
||||
borderWidth: 0,
|
||||
hoverOffset: 4
|
||||
}]
|
||||
}
|
||||
{{< /chart >}}
|
||||
<!-- prettier-ignore-end -->
|
||||
@@ -0,0 +1,85 @@
|
||||
---
|
||||
title: "チャート（グラフ）"
|
||||
date: 2019-03-06
|
||||
description: "Chart.jsの使い方について"
|
||||
summary: "CongoにはChart.jsが含まれており、パワフルなチャートとデータのビジュアライゼーションが可能です。"
|
||||
tags: ["chart", "sample", "graph", "shortcodes"]
|
||||
---
|
||||
|
||||
Congoは、 `chart` ショートコードを使ったChart.jsをサポートしています。チャートのマークアップをショートコードにラップするだけです。Congoは設定された `colorScheme` パラメーターに合うように自動的にチャートをテーマ化しますが、通常のChart.js構文を使って色をカスタマイズすることもできます。
|
||||
|
||||
詳細は[ショートコード - チャート]({{< ref "docs/shortcodes#チャート" >}})のドキュメントを参照してください。
|
||||
|
||||
以下の例は、[Chart.jsの公式ドキュメント](https://www.chartjs.org/docs/latest/samples)から抜粋したものです。GitHubの[ページのソースを見る](https://raw.githubusercontent.com/jpanther/congo/dev/exampleSite/content/samples/charts.md)からもマークアップを見ることができます。
|
||||
|
||||
## バーチャート（棒グラフ）
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{{< chart >}}
|
||||
type: 'bar',
|
||||
data: {
|
||||
labels: ['睦月', '如月', '弥生', '卯月', '皐月', '水無月', '文月'],
|
||||
datasets: [{
|
||||
label: 'データセット',
|
||||
data: [65, 59, 80, 81, 56, 55, 40],
|
||||
backgroundColor: [
|
||||
'rgba(255, 99, 132, 0.2)',
|
||||
'rgba(255, 159, 64, 0.2)',
|
||||
'rgba(255, 205, 86, 0.2)',
|
||||
'rgba(75, 192, 192, 0.2)',
|
||||
'rgba(54, 162, 235, 0.2)',
|
||||
'rgba(153, 102, 255, 0.2)',
|
||||
'rgba(201, 203, 207, 0.2)'
|
||||
],
|
||||
borderColor: [
|
||||
'rgb(255, 99, 132)',
|
||||
'rgb(255, 159, 64)',
|
||||
'rgb(255, 205, 86)',
|
||||
'rgb(75, 192, 192)',
|
||||
'rgb(54, 162, 235)',
|
||||
'rgb(153, 102, 255)',
|
||||
'rgb(201, 203, 207)'
|
||||
],
|
||||
borderWidth: 1
|
||||
}]
|
||||
}
|
||||
{{< /chart >}}
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## ラインチャート（折れ線グラフ）
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{{< chart >}}
|
||||
type: 'line',
|
||||
data: {
|
||||
labels: ['睦月', '如月', '弥生', '卯月', '皐月', '水無月', '文月'],
|
||||
datasets: [{
|
||||
label: 'データセット',
|
||||
data: [65, 59, 80, 81, 56, 55, 40],
|
||||
tension: 0.2
|
||||
}]
|
||||
}
|
||||
{{< /chart >}}
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## ドーナツチャート（円グラフ）
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{{< chart >}}
|
||||
type: 'doughnut',
|
||||
data: {
|
||||
labels: ['赤', '青', '黄'],
|
||||
datasets: [{
|
||||
label: 'My First Dataset',
|
||||
data: [300, 50, 100],
|
||||
backgroundColor: [
|
||||
'rgba(255, 99, 132, 0.7)',
|
||||
'rgba(54, 162, 235, 0.7)',
|
||||
'rgba(255, 205, 86, 0.7)'
|
||||
],
|
||||
borderWidth: 0,
|
||||
hoverOffset: 4
|
||||
}]
|
||||
}
|
||||
{{< /chart >}}
|
||||
<!-- prettier-ignore-end -->
|
||||
@@ -0,0 +1,85 @@
|
||||
---
|
||||
title: "Charts"
|
||||
date: 2019-03-06
|
||||
description: "Guide to Chart.js usage in Congo"
|
||||
summary: "Congo includes Chart.js for powerful charts and data visualisations."
|
||||
tags: ["chart", "sample", "graph", "shortcodes"]
|
||||
---
|
||||
|
||||
Congo includes support for Chart.js using the `chart` shortcode. Simply wrap the chart markup within the shortcode. Congo automatically themes charts to match the configured `colorScheme` parameter, however the colours can be customised using normal Chart.js syntax.
|
||||
|
||||
Refer to the [chart shortcode]({{< ref "docs/shortcodes#chart" >}}) docs for more details.
|
||||
|
||||
The examples below are a small selection taken from the [official Chart.js docs](https://www.chartjs.org/docs/latest/samples). You can also [view the page source](https://raw.githubusercontent.com/jpanther/congo/dev/exampleSite/content/samples/charts/index.md) on GitHub to see the markup.
|
||||
|
||||
## Bar chart
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{{< chart >}}
|
||||
type: 'bar',
|
||||
data: {
|
||||
labels: ['January', 'February', 'March', 'April', 'May', 'June', 'July'],
|
||||
datasets: [{
|
||||
label: 'My First Dataset',
|
||||
data: [65, 59, 80, 81, 56, 55, 40],
|
||||
backgroundColor: [
|
||||
'rgba(255, 99, 132, 0.2)',
|
||||
'rgba(255, 159, 64, 0.2)',
|
||||
'rgba(255, 205, 86, 0.2)',
|
||||
'rgba(75, 192, 192, 0.2)',
|
||||
'rgba(54, 162, 235, 0.2)',
|
||||
'rgba(153, 102, 255, 0.2)',
|
||||
'rgba(201, 203, 207, 0.2)'
|
||||
],
|
||||
borderColor: [
|
||||
'rgb(255, 99, 132)',
|
||||
'rgb(255, 159, 64)',
|
||||
'rgb(255, 205, 86)',
|
||||
'rgb(75, 192, 192)',
|
||||
'rgb(54, 162, 235)',
|
||||
'rgb(153, 102, 255)',
|
||||
'rgb(201, 203, 207)'
|
||||
],
|
||||
borderWidth: 1
|
||||
}]
|
||||
}
|
||||
{{< /chart >}}
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## Line chart
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{{< chart >}}
|
||||
type: 'line',
|
||||
data: {
|
||||
labels: ['January', 'February', 'March', 'April', 'May', 'June', 'July'],
|
||||
datasets: [{
|
||||
label: 'My First Dataset',
|
||||
data: [65, 59, 80, 81, 56, 55, 40],
|
||||
tension: 0.2
|
||||
}]
|
||||
}
|
||||
{{< /chart >}}
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## Doughnut chart
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{{< chart >}}
|
||||
type: 'doughnut',
|
||||
data: {
|
||||
labels: ['Red', 'Blue', 'Yellow'],
|
||||
datasets: [{
|
||||
label: 'My First Dataset',
|
||||
data: [300, 50, 100],
|
||||
backgroundColor: [
|
||||
'rgba(255, 99, 132, 0.7)',
|
||||
'rgba(54, 162, 235, 0.7)',
|
||||
'rgba(255, 205, 86, 0.7)'
|
||||
],
|
||||
borderWidth: 0,
|
||||
hoverOffset: 4
|
||||
}]
|
||||
}
|
||||
{{< /chart >}}
|
||||
<!-- prettier-ignore-end -->
|
||||
@@ -0,0 +1,85 @@
|
||||
---
|
||||
title: "表格"
|
||||
date: 2019-03-06
|
||||
description: "Chart.js在Congo中的用法"
|
||||
summary: "Congo使用chart.js来提供强大的表格支持和数据可视化。"
|
||||
tags: ["chart", "sample", "graph", "shortcodes"]
|
||||
---
|
||||
|
||||
Congo 包含对 Chart.js 的支持，使用 `chart` 短代码即可。只需将图表标记包裹在短代码内。Congo 会自动根据配置的 `colorScheme` 参数为图表添加主题，但颜色可以使用常规的 Chart.js 语法进行自定义。
|
||||
|
||||
有关更多详细信息，请参阅 [chart 短代码]({{< ref "docs/shortcodes#chart" >}}) 文档。
|
||||
|
||||
以下示例是从 [官方 Chart.js 文档](https://www.chartjs.org/docs/latest/samples) 中摘取的一小部分。您还可以在 GitHub 上 [查看页面源代码](https://raw.githubusercontent.com/jpanther/congo/dev/exampleSite/content/samples/charts/index.md) 以查看标记。
|
||||
|
||||
## 柱状图
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{{< chart >}}
|
||||
type: 'bar',
|
||||
data: {
|
||||
labels: ['一月', '二月', '三月', '四月', '五月', '六月', '七月'],
|
||||
datasets: [{
|
||||
label: '我的第一个数据集 ',
|
||||
data: [65, 59, 80, 81, 56, 55, 40],
|
||||
backgroundColor: [
|
||||
'rgba(255, 99, 132, 0.2)',
|
||||
'rgba(255, 159, 64, 0.2)',
|
||||
'rgba(255, 205, 86, 0.2)',
|
||||
'rgba(75, 192, 192, 0.2)',
|
||||
'rgba(54, 162, 235, 0.2)',
|
||||
'rgba(153, 102, 255, 0.2)',
|
||||
'rgba(201, 203, 207, 0.2)'
|
||||
],
|
||||
borderColor: [
|
||||
'rgb(255, 99, 132)',
|
||||
'rgb(255, 159, 64)',
|
||||
'rgb(255, 205, 86)',
|
||||
'rgb(75, 192, 192)',
|
||||
'rgb(54, 162, 235)',
|
||||
'rgb(153, 102, 255)',
|
||||
'rgb(201, 203, 207)'
|
||||
],
|
||||
borderWidth: 1
|
||||
}]
|
||||
}
|
||||
{{< /chart >}}
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## 折线图
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{{< chart >}}
|
||||
type: 'line',
|
||||
data: {
|
||||
labels: ['一月', '二月', '三月', '四月', '五月', '六月', '七月'],
|
||||
datasets: [{
|
||||
label: '我的第一个数据集',
|
||||
data: [65, 59, 80, 81, 56, 55, 40],
|
||||
tension: 0.2
|
||||
}]
|
||||
}
|
||||
{{< /chart >}}
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## 圆环图
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
{{< chart >}}
|
||||
type: 'doughnut',
|
||||
data: {
|
||||
labels: ['红', '蓝', '黄'],
|
||||
datasets: [{
|
||||
label: 'My First Dataset',
|
||||
data: [300, 50, 100],
|
||||
backgroundColor: [
|
||||
'rgba(255, 99, 132, 0.7)',
|
||||
'rgba(54, 162, 235, 0.7)',
|
||||
'rgba(255, 205, 86, 0.7)'
|
||||
],
|
||||
borderWidth: 0,
|
||||
hoverOffset: 4
|
||||
}]
|
||||
}
|
||||
{{< /chart >}}
|
||||
<!-- prettier-ignore-end -->
|
||||
BIN
Binary file not shown.
|
After Width: | Height: | Size: 147 KiB |
@@ -0,0 +1,92 @@
|
||||
---
|
||||
title: "Diagramme und Flussdiagramme"
|
||||
date: 2019-03-06
|
||||
description: "Leitfaden zur Verwendung von Mermaid in Congo"
|
||||
summary: "Mit Mermaid ist es einfach, Diagramme und Flussdiagramme zu Artikeln hinzuzufügen."
|
||||
tags: ["Mermaid", "Beispiele", "Diagramm", "Shortcodes"]
|
||||
---
|
||||
|
||||
Mermaid-Diagramme werden in Congo mit dem Shortcode `mermaid` unterstützt. Füge einfach das Diagramm-Markup in den Shortcode ein. Congo gestaltet Mermaid-Diagramme automatisch so, dass sie der Konfiguration des Parameters `colorScheme` entsprechen.
|
||||
|
||||
Weitere Details findest du in der [Mermaid-Shortcode-Dokumentation]({{< ref path="docs/shortcodes#mermaid" lang="en">}}).
|
||||
|
||||
Die folgenden Beispiele sind eine kleine Auswahl aus der [offiziellen Mermaid-Dokumentation](https://mermaid-js.github.io/mermaid/). Du kannst auch [die Quelle der Seite](https://raw.githubusercontent.com/jpanther/congo/dev/exampleSite/content/samples/diagrams-flowcharts/index.de.md) auf GitHub aufrufen, um das Markup zu sehen.
|
||||
|
||||
## Flussdiagramm
|
||||
|
||||
{{< mermaid >}}
|
||||
graph TD
|
||||
A[Weihnachten] -->|Erhalte Geld| B(Geh einkaufen)
|
||||
B --> C{Lass mich nachdenken}
|
||||
B --> G[/Sonstiges/]
|
||||
C ==>|Eins| D[Laptop]
|
||||
C -->|Zwei| E[iPhone]
|
||||
C -->|Drei| F[Auto]
|
||||
subgraph Section
|
||||
C
|
||||
D
|
||||
E
|
||||
F
|
||||
G
|
||||
end
|
||||
{{< /mermaid >}}
|
||||
|
||||
## Sequenzdiagramm
|
||||
|
||||
{{< mermaid >}}
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
par Action 1
|
||||
Alice->>John: Hallo John, wie geht es dir?
|
||||
and Action 2
|
||||
Alice->>Bob: Hallo Bob, wie geht es dir?
|
||||
end
|
||||
Alice->>+John: Hallo John, wie geht es dir?
|
||||
Alice->>+John: John, kannst du mich hören?
|
||||
John-->>-Alice: Hi Alice, ich kann dich hören!
|
||||
Note right of John: John ist aufmerksam
|
||||
John-->>-Alice: Mir geht es gut!
|
||||
loop Jede Minute
|
||||
John-->Alice: Super!
|
||||
end
|
||||
{{< /mermaid >}}
|
||||
|
||||
## Klassendiagramm
|
||||
|
||||
{{< mermaid >}}
|
||||
classDiagram
|
||||
Tier "1" <|-- Ente
|
||||
Tier <|-- Fisch
|
||||
Tier <--o Zebra
|
||||
Tier : +int alter
|
||||
Tier : +String geschlecht
|
||||
Tier: +istSaeugetier()
|
||||
Tier: +paaren()
|
||||
class Ente{
|
||||
+String schnabelFarbe
|
||||
+schwimmen()
|
||||
+quaken()
|
||||
}
|
||||
class Fisch{
|
||||
-int groesseInFuss
|
||||
-canFressen()
|
||||
}
|
||||
class Zebra{
|
||||
+bool ist_wild
|
||||
+rennen()
|
||||
}
|
||||
{{< /mermaid >}}
|
||||
|
||||
## Entitäts-Beziehungs-Diagramm
|
||||
|
||||
{{< mermaid >}}
|
||||
erDiagram
|
||||
KUNDE }|..|{ LIEFER-ADRESSE : hat
|
||||
KUNDE ||--o{ BESTELLUNG : platziert
|
||||
KUNDE ||--o{ RECHNUNG : "zustaendig fuer"
|
||||
LIEFER-ADRESSE ||--o{ BESTELLUNG : erhaelt
|
||||
RECHNUNG ||--|{ BESTELLUNG : "deckt ab"
|
||||
BESTELLUNG ||--|{ BESTELLTES-PRODUKT : enthaelt
|
||||
PRODUKT-KATEGORIE ||--|{ PRODUKT : enthaelt
|
||||
PRODUKT ||--o{ BESTELLTES-PRODUKT : "bestellt in"
|
||||
{{< /mermaid >}}
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user