メインコンテンツへスキップ

Hugoのドキュメント用テーマDoksの導入から公開まで

·2562 文字·6 分
目次

はじめに
#

Doksは静的サイトジェネレータHugoのテーマの1つであり、ドキュメントサイトの構築に向いています。Doksテーマの導入から、Netlifyを使ったサンプルサイトの公開までをまとめました。

Doks theme main
Doks theme main

HugoはWebサイトを構築するフレームワークで、Markdownなどで記述された記事をHTMLファイルなどに変換できます。 Hugoでは、「テーマ」を設定することでサイトの外観を変更できます。 Hugoのテーマはブログ用のものが多いですが、Doksはソフトウェアのリファレンスのようなドキュメントを公開するのに向いたテーマです。 ただし、Doksテーマを導入するにはNode.jsが必要であり(HugoはNode.jsのバックエンドとして使用されます)、若干クセがあります。

この記事では、Doksの導入方法からNetlifyを使った公開までをまとめています。

バージョンは以下の通りです(HugoはNode.jsを使ってインストールするので、表に含めていません)。 また、OSはWindows 10 Homeです。

バージョン
Doks 0.3.5
Node.js 16.13.0
Git for windows 2.34.1

また、Gitのバージョンは2.28以降とする必要があります。後述のnpm run initコマンドではgit init -b mainが実行されるのですが、-bオプションはバージョン2.28で追加されています。 Git - git-init Documentation (Version 2.28.0)

Doksテーマの特徴
#

Doksテーマのリファレンスサイトは以下になります。ページ上部の"Showcase"から、Doksを使って構築したサイトのサンプルにアクセスできます。 Doks - Modern Documentation Theme

Doksの主な機能は以下の通りです。

  • Markdownによるドキュメントの記述
  • FlexSearchによる全文検索
  • 多言語対応
  • KaTeXによる数式表示
  • highlight.jsによるシンタックスハイライト
  • バージョン切り替え機能
  • ダークモード

また、Doksはchild themeとstarter themeの2つに分かれています。

  • child themeはサイトをあまりカスタムせず、将来的なDoksテーマのアップデートを利用したい場合に選択します(初心者向け)。
  • starter themeはサイトをカスタムできる幅が大きいですが、将来的なDoksテーマのアップデートが必要でない場合に選択します。

starter themeでは以下のカスタムを容易にできます(child themeには括弧内のフォルダが存在しない)。

  • Markdownのテンプレートを変更する(archetypesフォルダ)
  • デフォルトのJavaScriptやCSSを修正する(assetsフォルダ)
  • 任意のファイルを公開する(staticフォルダ)

事前準備
#

Doksテーマを使用する前に、Node.jsをインストールします。Node.jsはJavaScriptの実行環境です。 Node.js https://nodejs.org/ja/

Doksテーマを使う場合、Hugoを手動で別途インストールする必要はありません。後述のnpm installコマンド実行時に、Node.jsを使ってHugoをダウンロードします。

次に、Gitをインストールします。 Git https://git-scm.com/

さらに、GitHubとNetlifyのアカウントをそれぞれ作成します。 GitHub https://github.com/ Netlify https://www.netlify.com/

Doksのセットアップ
#

まず、Gitを使ってDoks starter themeをローカルにcloneします。

git clone https://github.com/h-enk/doks.git my-doks-site

Doks child themeの場合は、以下のリポジトリになります。

git clone https://github.com/h-enk/doks-child-theme.git my-doks-site

実行すると、my-doks-siteフォルダ内にテーマがダウンロードされます。

次に、my-doks-siteフォルダに移動し、依存関係のあるソフトウェア(Hugoなど)をインストールします。

> cd my-doks-site
> npm install

ちなみにnpmはNode.jsのパッケージ管理システムです。 npm installを実行すると、package.jsonに記載されているライブラリがインストールされます。

さらに以下のコマンドを実行します。

npm run start

すると、ローカルサーバが起動するので、http://localhost:1313をブラウザで開くと、Doksのサンプルサイトが表示されます。 なお、npm run startというコマンドの裏側ではHugoが実行されています(startはエイリアスで、実際のコマンドはpackage.jsonに記載されています)。

Doks theme main
Doks theme main

サイトの公開
#

最後に、DoksのサイトをNetlifyで公開します。 (サイトのカスタム方法などは別の記事にまとめる予定です)

GitHubのリポジトリ作成
#

まず、GitHubの自分のアカウントで、空のプロジェクトを作成します。 “Repository name"は好きなように設定して構いません。また、“Initialize this repository with"のチェックは全て外します。

Create new repository on GitHub
Create new repository on GitHub

次に、PowerShellを起動し、my-doks-siteフォルダに移動します。 以下を実行して、Doksテーマのリポジトリの情報を削除し、新規のリポジトリとします。ブランチ名はmainになります。

npm run init

my-doks-siteフォルダ内のファイルを全てコミットします(カスタマイズする前に、一度コミットした方が良いでしょう)。

> git add .
> git commit -m "First commit"

さらに、GitHubのリモートリポジトリのURLを設定します。

git remote add origin <remote repository URL>

以下を実行すると、リモートリポジトリのURLが正しく設定されたか確認できます。

git remote -v

最後にリポジトリをGitHubにpushします。

git push -u origin main

2回目以降のpushではgit pushだけでOKです。

Netlifyでデプロイ
#

続いて、GitHubのリポジトリをNetlifyで公開します。 Netlifyでビルド(Markdownなどを公開用のHTMLファイルに変換する処理)を行います。

Netlifyにログインし、GitHubのリポジトリ (mysite) をインポートします。 ビルドオプションは表示されているものでOKです(これらのオプションはnetlify.tomlに記載されています)。

Build settings on Netlify
Build settings on Netlify

“Deploy site"ボタンを押して2~3分ほど待つと、サンプルサイトが公開されます。

まとめ
#

Hugoのテーマの1つであり、ドキュメントサイトの構築に向いているDoksの導入から公開までをまとめました。

参考
#

Helve
著者
Helve
関西在住、電機メーカ勤務のエンジニア。X(旧Twitter)で新着記事を配信中です

関連記事

静的サイトをブログ村に登録するならNetlifyがオススメ
·1250 文字·3 分
静的サイトをブログ村に登録する場合、Netlify以外のホスティングサービスを使用すると最新記事を取得してくれない可能性がある。
HugoのZzoテーマで記事の日付・著者の絵文字をSVGに変更する
·1953 文字·4 分
HugoのZzoテーマで記事の日付・著者に設定されている絵文字アイコンを、モダンなデザインのSVG画像に変更する方法を解説する。
HugoのZzoテーマでTwitter Card用の画像を設定する
·1621 文字·4 分
HugoのZzoテーマでTwitter Cardに表示する画像を設定する方法をまとめた
Hugoサイトにお問い合わせフォームを設置する
·994 文字·2 分
HugoのZZoテーマに、Googleフォームを利用したお問い合わせフォームを設置した。
Hugoサイトに最新版のGoogle Analyticsのタグを埋め込む
·1241 文字·3 分
HugoのPartial Templatesを利用して、最新版のGoogle Analytics (gtag.js) のトラッキングコードを埋め込む方法をまとめた。
Hugoでよく使うコマンド一覧
·1485 文字·3 分
静的サイトジェネレータHugoで使用頻度の高いコマンドをまとめた。