Initial commit for Hugo site.
This commit is contained in:
Charish Patel
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 |
Reference in New Issue
Block a user