コンテンツ形式

HTML と Markdown の両方のコンテンツ形式をサポートしています。

On this page

content ディレクトリには任意のファイルタイプを入れることができますが、Hugo は markup というフロントマターの値が設定されている場合、またはファイルの拡張子 (下のテーブルの マークアップ識別子 を参照) を使って、マークアップを処理する必要があるかどうかを判断します。たとえば、

HTML に変換された Markdown
処理済みショートコード
適用されたレイアウト

コンテンツ形式の一覧

下表は、Hugo の現在のコンテンツ形式の一覧です。

名前	マークアップ識別子	コメント
Goldmark	md, markdown, goldmark	`md` と `markdown` のデフォルトハンドラーを別のものに設定できることに注意してください。「マークアップの設定」を参照してください。
Emacs Org-Mode	org	go-org を参照してください。
AsciiDoc	asciidocext, adoc, ad	Asciidoctor がインストールされている必要があります。
RST	rst	RST がインストールされている必要があります。
Pandoc	pandoc, pdc	Pandoc がインストールされている必要があります。
HTML	html, htm	レイアウトやショートコードなど、コンテンツファイルとして扱うには、フロントマターが必要です。そうでない場合は、そのままコピーされます。

マークアップ識別子 は、フロントマターの変数 markup か、ファイルの拡張子から取得されます。マークアップ関連の設定については、「マークアップの設定」を参照してください。

外部ヘルパー

上表の形式の中には、お使いの PC に外部ヘルパーをインストールする必要があるものがあります。たとえば、AsciiDoc ファイルの場合、Hugo は asciidoctor コマンドを呼び出そうとします。つまり、これらの形式を使用するには、関連するツールをマシンにインストールする必要があります。

Hugo は、デフォルトで以下のような適切なデフォルト引数をこれらの外部ヘルパーに渡します。

asciidoctor: --no-header-footer -
rst2html: --leave-comments --initial-header-level=2
pandoc: --mathjax

外部ヘルパー Asciidoctor

Asciidoctor コミュニティは、Hugo に追加してインストールできる、AsciiDoc フォーマットのための幅広いツール群を提供しています。インストール方法は Asciidoctor のドキュメントを参照してください。必要であれば、asciidoctor-diagram や asciidoctor-html5s などのオプションの拡張もすべてインストールされていることを確認してください。

外部の asciidoctor コマンドでは、 Hugo レンダリングが特定の宛先ディレクトリへ disk するように要求します。コマンドオプション --destination を指定して Hugo を実行する必要があります。

一部の Asciidoctor パラメータは、Hugo でカスタマイズできます。

パラメータ	コメント
backend	自分が何をしているのか分からない限り、これを変更しないでください。
doctype	現在、Hugo でサポートされているドキュメントタイプは `article` だけです。
extensions	使用できる拡張子は、 `asciidoctor-html5s`、`asciidoctor-bibtex`、`asciidoctor-diagram`、`asciidoctor-interdoc-reftext`、`asciidoctor-katex`、`asciidoctor-latex`、`asciidoctor-mathematical`、`asciidoctor-question`、`asciidoctor-rouge` です。
attributes	AsciiDoc ファイルで参照する変数です。これは変数名/値マップのリストです。「Asciidoctor の属性」を参照してください。
noHeaderOrFooter	ヘッダー、フッター、本文以外のものを除いた埋め込み可能なドキュメントを出力します。自分が何をしているのか分からない限り、これを変更しないでください。
safeMode	セーフモードのレベルを `unsafe`、`safe`、`server`、`secure` のいずれかから選択します。自分が何をしているのか分からない限り、これを変更しないでください。
sectionNumbers	セクションのタイトルに自動で番号を付けます。
verbose	処理情報と設定ファイルのチェックを stderr (標準エラー出力) に詳細に出力します。
trace	エラー時のバックトレース情報を含めます。
failureLevel	0以外の終了コード（失敗）をトリガーする最小のロギングレベルです。

Hugo は Asciidoctor の CLI オプションに直接マッピングされない、以下の追加設定を提供します。

workingFolderCurrent: 作業ディレクトリを、処理中の AsciiDoc ファイルのディレクトリと同じになるように設定します。これにより、include が相対パスで動作するようになります。この設定では、 asciidoctor の cli パラメータ --base-dir と属性 outdir= を使用します。 asciidoctor-diagram で図をレンダリングする場合には、 workingFolderCurrent を true に設定する必要があります。
preserveTOC: デフォルトでは、Hugo は Asciidoctor が生成した目次を削除し、組み込み変数 .TableOfContents を通して目次を提供し、さらなるカスタマイズとさまざまな Hugo テーマとのより良い統合を可能にします。このオプションを true に設定すると、生成されたページで Asciidoctor の TOC (目次) を保持できます。

以下は、Hugo における AsciiDoc 関連のすべての設定とそのデフォルト値になります。

markup:
  asciidocExt:
    attributes: {}
    backend: html5
    extensions: []
    failureLevel: fatal
    noHeaderOrFooter: true
    preserveTOC: false
    safeMode: unsafe
    sectionNumbers: false
    trace: false
    verbose: false
    workingFolderCurrent: false

[markup]
  [markup.asciidocExt]
    backend = 'html5'
    extensions = []
    failureLevel = 'fatal'
    noHeaderOrFooter = true
    preserveTOC = false
    safeMode = 'unsafe'
    sectionNumbers = false
    trace = false
    verbose = false
    workingFolderCurrent = false
    [markup.asciidocExt.attributes]

{
   "markup": {
      "asciidocExt": {
         "attributes": {},
         "backend": "html5",
         "extensions": [],
         "failureLevel": "fatal",
         "noHeaderOrFooter": true,
         "preserveTOC": false,
         "safeMode": "unsafe",
         "sectionNumbers": false,
         "trace": false,
         "verbose": false,
         "workingFolderCurrent": false
      }
   }
}

セキュリティ上の懸念から、パス区切り文字 (\、/、または .) を持たない拡張子のみが許可されることに注意してください。つまり、拡張機能は、Ruby の $LOAD_PATH にある場合にのみ呼び出すことができます (つまり、拡張機能がユーザーによってインストールされている可能性が最も高いです)。 Web サイトのパスに対して相対的に宣言された拡張子は受け入れられません。

以下は、拡張子や属性の設定例です。

[markup.asciidocExt]
    extensions = ["asciidoctor-html5s", "asciidoctor-diagram"]
    workingFolderCurrent = true
    [markup.asciidocExt.attributes]
        my-base-url = "https://example.com/"
        my-attribute-name = "my value"

複雑な Asciidoctor 環境では、外部ヘルパーをすべてのパラメータで正確に呼び出すことがデバッグに役立つことがあります。 -v で Hugo を実行すると、以下のような出力が得られます。

INFO 2019/12/22 09:08:48 Rendering book-as-pdf.adoc with C:\Ruby26-x64\bin\asciidoctor.bat using asciidoc args [--no-header-footer -r asciidoctor-html5s -b html5s -r asciidoctor-diagram --base-dir D:\prototypes\hugo_asciidoc_ddd\docs -a outdir=D:\prototypes\hugo_asciidoc_ddd\build -] ...

Markdown を学ぶ

Markdown の構文は一度で習得できるほどシンプルです。以下は、あなたが起動し、実行できる優れたリソースです。