Trez/hugo_it-services
4
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Activity

Initial commit for Hugo site.

Browse Source
This commit is contained in:
Charish Patel
2025-02-20 08:28:31 -05:00
parent 737c448252
commit 045d0c24f3
696 changed files with 91218 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
themes/congo/exampleSite/content/docs/content-examples/index.ja.md
+317
View File
@@ -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/)はテンプレートの作成についてもっと学ぶための素晴らしいリソースです。
themes/congo/exampleSite/content/docs/content-examples/index.md
+317
View File
@@ -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.
themes/congo/exampleSite/content/docs/content-examples/index.zh-cn.md
+316
View File
@@ -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/)也是学习有关创建模板的更多信息的绝佳资源。
themes/congo/exampleSite/content/docs/content-examples/thumb-inspiration.svg
+1
View File
File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 17 KiB