From 5661c86c5ee993d150624d01ba7f75ceaa4123bf Mon Sep 17 00:00:00 2001 From: SHINICHIRO SUZUKI Date: Tue, 25 Jul 2023 23:36:20 +0900 Subject: [PATCH] docs: :notebook: add Japanese documents --- exampleSite/config/_default/languages.ja.toml | 28 ++ exampleSite/config/_default/menus.ja.toml | 50 +++ exampleSite/content/docs/_index.ja.md | 22 ++ .../docs/advanced-customisation/index.ja.md | 183 ++++++++++ .../content/docs/configuration/index.ja.md | 183 ++++++++++ .../content/docs/content-examples/index.ja.md | 317 ++++++++++++++++++ .../content/docs/front-matter/index.ja.md | 51 +++ .../content/docs/getting-started/index.ja.md | 246 ++++++++++++++ .../content/docs/homepage-layout/index.ja.md | 53 +++ .../docs/hosting-deployment/index.ja.md | 149 ++++++++ .../content/docs/installation/index.ja.md | 178 ++++++++++ exampleSite/content/docs/partials/index.ja.md | 99 ++++++ .../content/docs/shortcodes/index.ja.md | 236 +++++++++++++ exampleSite/content/docs/shortcodes/index.md | 2 +- .../content/docs/version-2/_index.ja.md | 97 ++++++ exampleSite/content/docs/version-2/_index.md | 2 +- .../docs/version-2/upgrade/index.ja.md | 199 +++++++++++ 17 files changed, 2093 insertions(+), 2 deletions(-) create mode 100644 exampleSite/config/_default/languages.ja.toml create mode 100644 exampleSite/config/_default/menus.ja.toml create mode 100644 exampleSite/content/docs/_index.ja.md create mode 100644 exampleSite/content/docs/advanced-customisation/index.ja.md create mode 100644 exampleSite/content/docs/configuration/index.ja.md create mode 100644 exampleSite/content/docs/content-examples/index.ja.md create mode 100644 exampleSite/content/docs/front-matter/index.ja.md create mode 100644 exampleSite/content/docs/getting-started/index.ja.md create mode 100644 exampleSite/content/docs/homepage-layout/index.ja.md create mode 100644 exampleSite/content/docs/hosting-deployment/index.ja.md create mode 100644 exampleSite/content/docs/installation/index.ja.md create mode 100644 exampleSite/content/docs/partials/index.ja.md create mode 100644 exampleSite/content/docs/shortcodes/index.ja.md create mode 100644 exampleSite/content/docs/version-2/_index.ja.md create mode 100644 exampleSite/content/docs/version-2/upgrade/index.ja.md diff --git a/exampleSite/config/_default/languages.ja.toml b/exampleSite/config/_default/languages.ja.toml new file mode 100644 index 00000000..810f4bee --- /dev/null +++ b/exampleSite/config/_default/languages.ja.toml @@ -0,0 +1,28 @@ +languageCode = "ja" +languageName = "日本語" +weight = 2 + +title = "Congo" +copyright = "© 2023 Congo contributors" + +[params] + isoCode = "ja" + displayName = ":jp:" + rtl = false + + dateFormat = "2006年1月2日" + + mainSections = ["samples"] + description = "Tailwind CSSをベースに開発された強力で軽量なHugo向けテーマ" + +[author] + name = "Congo" + image = "img/author.jpg" + headline = "ただならぬテーマ!" + bio = "これは著者の経歴の例で、ここには犬の画像があるが、実際には人間が作成したものである。 :dog:" + links = [ + { twitter = "https://twitter.com/" }, + { facebook = "https://facebook.com/" }, + { linkedin = "https://linkedin.com/" }, + { youtube = "https://youtube.com/" }, + ] diff --git a/exampleSite/config/_default/menus.ja.toml b/exampleSite/config/_default/menus.ja.toml new file mode 100644 index 00000000..a0f79a38 --- /dev/null +++ b/exampleSite/config/_default/menus.ja.toml @@ -0,0 +1,50 @@ +# -- 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" + +# -- 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 diff --git a/exampleSite/content/docs/_index.ja.md b/exampleSite/content/docs/_index.ja.md new file mode 100644 index 00000000..d1258cef --- /dev/null +++ b/exampleSite/content/docs/_index.ja.md @@ -0,0 +1,22 @@ +--- +title: "ドキュメント" +description: "Congoの特徴とその使い方について" + +cascade: + showDate: false + showAuthor: false + showSummary: true + invertPagination: true +--- + +{{< lead >}} +シンプルでパワフル。Congoの使い方と特徴をご紹介します。 +{{< /lead >}} + +![Screenshots of Congo on an iPhone, iPad and MacBook](screenshot.png) + +このセクションにはCongoの知るべきすべてが含まれています。もしあなたがCongoに触れるのが初めてならば、[インストール]({{< ref "docs/installation" >}})ガイドを読むか、[例]({{< ref "samples" >}})を見て、Congoは何ができるか確認してください。 + +_このドキュメントに素晴らしいイラストを提供してくれた[Katerina Limpitsouni](https://ninalimpi.com)に感謝します。_ + +--- diff --git a/exampleSite/content/docs/advanced-customisation/index.ja.md b/exampleSite/content/docs/advanced-customisation/index.ja.md new file mode 100644 index 00000000..8358cae4 --- /dev/null +++ b/exampleSite/content/docs/advanced-customisation/index.ja.md @@ -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/` ディレクトリに `.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)に質問を投稿してください。 diff --git a/exampleSite/content/docs/configuration/index.ja.md b/exampleSite/content/docs/configuration/index.ja.md new file mode 100644 index 00000000..e98ed2b3 --- /dev/null +++ b/exampleSite/content/docs/configuration/index.ja.md @@ -0,0 +1,183 @@ +--- +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` を指します）。 + + +|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" >}})セクションを参照してください。| + + +## 言語と国際化 + +Congoは完全な多言語ウェブサイト用に最適化されており、テーマのアセットはすぐに複数の言語に翻訳されます。言語設定により、複数バージョンのコンテンツを生成し、訪問者の母国語でカスタマイズされたエクスペリエンスを提供することができます。 + +Congoは現在、以下の言語に対応しています: + +| Language | Code | +| --------------------------------------- | ------- | +| :gb: **English (default)** | `en` | +| :egypt: Arabic | `ar` | +| :bangladesh: Bengali | `bn` | +| :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` | +| :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` | +| :tr: Turkish | `tr` | + +翻訳文字列を含むカスタムファイルを `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 >}} + + +|Name|Default|Description| +|---|---|---| +|`languageCode`|`"en"`|このファイルの言語コード。トップレベル言語 (例 `en`)またはサブ変数 (例 `en-au`)で、ファイル名の `[language-code]` と一致する必要があります。Hugoはこの値が常に小文字であることを期待しています。HTMLに正しく準拠するためには、大文字と小文字を区別する `params.isoCode` パラメーターを設定してください。| +|`languageName`|`"English"`|言語名。| +|`weight`|`1`|多言語サイトを構築する際の優先順序。| +|`title`|`"Congo"`|ウェブサイトのタイトル。サイトのヘッダーとフッターに表示されます。| +|`copyright`|_Not set_|サイトのフッターに表示する著作権メッセージを含むMarkdown文字列。何も指定されない場合、Congoは `title` を使って自動的にコピーライト文字列を生成します。| +|`params.isoCode`|`"en"`|HTMLメタデータ用のISO言語コード。トップレベル言語 (例 `en`)またはサブバリアント (例 `en-AU`)です。| +|`params.displayName`|`"EN"`|ウェブサイトに表示される際に使用される言語名。| +|`params.rtl`|`false`|RTL言語かどうか。 `true` に設定すると、コンテンツを右から左にリフローする。CongoはRTL言語とLTR言語の同時使用を完全にサポートしており、動的に両方の言語に調整します。| +|`params.dateFormat`|`"2 January 2006"`|日付の書式。許容される書式については、[Hugo docs](https://gohugo.io/functions/format/#gos-layout-string)を参照してください。| +|`params.mainSections`|_Not set_|最近の記事リストに表示するセクション。指定されていない場合は、記事の数が最も多いセクションが使われます。| +|`params.description`|_Not set_|ウェブサイトの説明。これはサイトのメタデータに使用されます。| +|`author.name`|_Not set_|著者の名前。これは記事のフッターと、プロフィールレイアウトが使用されている場合にホームページに表示されます。| +|`author.image`|_Not set_|著者の画像ファイルへのパス。画像は縦横比1:1で、 `assets/` に置くこと。| +|`author.headline`|_Not set_|著者の見出しを含むMarkdown文字列。プロフィールのトップページで著者の名前の下に表示されます。| +|`author.bio`|_Not set_|著者の経歴を含むMarkdown文字列。記事のフッターに表示されます。| +|`author.links`|_Not set_|著者の詳細とともに表示するリンク。設定ファイルにはリンクの例が含まれており、コメントを外すだけで有効にすることができます。リンクが表示される順番は、配列に表示される順番によって決まります。 `assets/icons/` に対応するSVGアイコンを用意することで、カスタムリンクを追加することもできます。| + + +### メニュー + +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" >}})セクションを参照してください。 + + +|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`|`` ブロックに対してクリップボードへのコピーボタンを有効にするかどうか。 `highlight.noClasses` が `false` に設定されていなければ、コードコピーは正しく機能しません。[その他の設定ファイル](#その他の設定ファイル)については以下を参照してください。| +|`enableImageLazyLoading`|`true`|ブラウザが遅延ロードするように画像をマークするかどうか。| +|`robots`|_Not set_|ロボットがあなたのサイトをどのように扱うべきかを示す文字列。設定された場合、 `` に出力されます。有効な値については[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#アナリティクス" >}})を参照してください。| +|`fathomAnalytics.domain`|_Not set_|Fathom Analyticsでカスタムドメインを使用している場合、カスタムドメインから`script.js`を提供するためにここに指定します。| +|`verification.google`|_Not set_|サイトのメタデータに含めるGoogleが提供するサイト検証文字列。| +|`verification.bing`|_Not set_|サイトのメタデータに含めるBingが提供するサイト検証文字列。| +|`verification.pinterest`|_Not set_|サイトのメタデータに含めるPinterestが提供するサイト検証文字列。| +|`verification.yandex`|_Not set_|サイトのメタデータに含めるYandexが提供するサイト検証文字列。| + + +## その他の設定ファイル + +このテーマには `markup.toml` 設定ファイルも含まれています。このファイルにはいくつかの重要なパラメータが含まれており、Congoで構築されたサイトを生成するためにHugoが正しく設定されるようにします。 + +このファイルがconfigディレクトリに存在し、必要な値が設定されていることを常に確認してください。これを行わないと、特定の機能が正しく動作しなかったり、意図しない動作になったりする可能性があります。 diff --git a/exampleSite/content/docs/content-examples/index.ja.md b/exampleSite/content/docs/content-examples/index.ja.md new file mode 100644 index 00000000..67d5b683 --- /dev/null +++ b/exampleSite/content/docs/content-examples/index.ja.md @@ -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" }} +
+ {{ range .Pages }} + + {{ end }} +
+{{ end }} +``` + +これは非常にわかりやすい例ですが、このセクションの各ページ（つまり各プロジェクト）を順に見ていき、各プロジェクトへのHTMLリンクをアイコンと一緒に出力していることがわかります。各プロジェクトのフロントマターのメタデータは、どの情報を表示するかを決定するために使われます。 + +関連するスタイルとクラスが利用可能であることを確認する必要があり、Tailwind CSSを再コンパイルする必要があるかもしれないことを覚えておいてください。これについては、[高度なカスタマイズ]({{< ref "advanced-customisation" >}})セクションで詳しく説明します。 + +このようなカスタムテンプレートを作成する場合、デフォルトのCongoテンプレートがどのように動作するかを見て、それをガイドとして使用するのが最も簡単です。[Hugo docs](https://gohugo.io/templates/introduction/)はテンプレートの作成についてもっと学ぶための素晴らしいリソースです。 diff --git a/exampleSite/content/docs/front-matter/index.ja.md b/exampleSite/content/docs/front-matter/index.ja.md new file mode 100644 index 00000000..6bcf0e40 --- /dev/null +++ b/exampleSite/content/docs/front-matter/index.ja.md @@ -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" >}})から継承されるので、デフォルトを上書きしたい場合にのみフロントマターでこれらのパラメーターを指定する必要があります。 + + +|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_|ロボットがこの記事をどのように扱うべきかを示す文字列。設定された場合、 `` に出力されます。有効な値については[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` ファイルに含まれるかどうか。| + diff --git a/exampleSite/content/docs/getting-started/index.ja.md b/exampleSite/content/docs/getting-started/index.ja.md new file mode 100644 index 00000000..9bc25efb --- /dev/null +++ b/exampleSite/content/docs/getting-started/index.ja.md @@ -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" + +[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 >}} +`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` 画像は個々の記事ページで記事内容の上部に表示されます。 + +![A screenshot of an article with a thumbnail image](article-screenshot.jpg "この例では、 `thumb` 画像付きの記事を示しています。") + +{{< 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" >}})セクションを参照してください。 diff --git a/exampleSite/content/docs/homepage-layout/index.ja.md b/exampleSite/content/docs/homepage-layout/index.ja.md new file mode 100644 index 00000000..9e7c725d --- /dev/null +++ b/exampleSite/content/docs/homepage-layout/index.ja.md @@ -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コンテンツを表示します。静的なウェブサイトには最適で、多くの柔軟性を提供します。 + +![Screenshot of homepage layout](home-page.jpg) + +ページレイアウトを有効にするには、 `params.toml` 設定ファイルで `homepage.layout = "page"` を設定します。 + +## プロフィールレイアウト + +プロフィールレイアウトは、個人のウェブサイトやブログに最適です。画像とソーシャル・プロフィールへのリンクを提供することで、著者の詳細を前面に押し出します。 + +![Screenshot of profile layout](home-profile.jpg) + +著者情報は `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` にするだけです。 + +![Profile layout with recent articles](home-profile-list.jpg) + +このセクションにリストされる記事は、 `mainSections` 設定から派生したもので、あなたのウェブサイトで使用しているコンテンツタイプに対応します。例えば、 _posts_ と _projects_ のコンテンツセクションがある場合、この設定を `["posts", "projects"]` に設定することで、これら2つのセクションにあるすべての記事が最近の記事リストに出力されます。Congoはこの設定が配列であることを想定しているので、すべてのコンテンツに1つのセクションしか使用しない場合は、この設定を適宜変更してください: `["blog"]` diff --git a/exampleSite/content/docs/hosting-deployment/index.ja.md b/exampleSite/content/docs/hosting-deployment/index.ja.md new file mode 100644 index 00000000..e5abe292 --- /dev/null +++ b/exampleSite/content/docs/hosting-deployment/index.ja.md @@ -0,0 +1,149 @@ +--- +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] + NODE_ENV = "production" + GO_VERSION = "1.20" + TZ = "UTC" # Set to preferred timezone + +[context.production.environment] + HUGO_VERSION = "0.112.7" + HUGO_ENV = "production" + +[context.deploy-preview.environment] + HUGO_VERSION = "0.112.7" +``` + +上の例は、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ドルの無料クレジットがもらえます。_ diff --git a/exampleSite/content/docs/installation/index.ja.md b/exampleSite/content/docs/installation/index.ja.md new file mode 100644 index 00000000..725339d4 --- /dev/null +++ b/exampleSite/content/docs/installation/index.ja.md @@ -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// + + # ローカルでプロジェクトを管理している場合 + 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. サイトを再構築し、すべてが期待通りに動作することを確認してください。 diff --git a/exampleSite/content/docs/partials/index.ja.md b/exampleSite/content/docs/partials/index.ja.md new file mode 100644 index 00000000..469edacc --- /dev/null +++ b/exampleSite/content/docs/partials/index.ja.md @@ -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` ファイルをプロジェクトに作成するだけで、ウェブサイトの `` に自動的にインクルードされます。 + +## コメント + +記事にコメント機能を追加するために、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` ファイルをプロジェクトに提供するだけで、デフォルトのアセットの代わりに `` に注入されます。 + +## アイコン + +[ショートコード - アイコン]({{< 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 + +テンプレートの `` と `