【ドキュメント静的ジェネレータ】docsifyを使ってみる

こんにちは!たぬきうどんです!

私は2018年に非IT業界から未経験でエンジニアに転職し、現在までエンジニアとして働いています。

この記事ではドキュメント静的ジェネレータ「docsify」の紹介について書いています。

「docsify」ってなんだろう?

という方にオススメの記事となっています。

docsifyを使うと簡単にドキュメントサイトが作成できるので、ぜひご覧ください!

docsifyとは?

docsifyMarkdownファイルをロード、解析し、Webサイトとして表示する静的サイトジェネレータです。

静的ファイルがビルド&生成されないことが最も特徴的な点として挙げられます。

公式では

A magical documentation site generator.

docsify -Document-

と謳っています。

直訳すると、「魔法のドキュメントサイトジェネレータ」ですね。

docsifyの特徴としては

  • ビルドされるHTMLがない
  • シンプルで軽量
  • スマートな全文検索プラグイン
  • 複数のテーマあり
  • 便利なプラグインAPIあり
  • 絵文字のサポート
  • IE11との互換性あり
  • server-side renderingをサポート

が挙げられます。

docsifyを使用した実際のサイトは以下のような感じです。

導入方法

この記事執筆時の環境は以下です。

  • Windows10
  • コマンドプロンプト
  • Node v16.13.1
  • npm v8.1.2

今回はdocsifyのインストールからローカルプレビューまでの手順を紹介します。

手順

docsify-cliのインストール

まずはdocsify-cliのインストールを行います。

このcliを使用し、初期化やローカル環境でのプレビューを行います。

任意のディレクトリで以下のコマンドを実行しましょう。

今回はローカルディレクトリのみにインストールします。

コマンドプロンプト
npm i docsify-cli

インストールが終わったらpackage.jsonscripts部分に初期化コマンドとプレビューコマンドを定義しておきましょう。

今回は初期化コマンドををinit、プレビューコマンドをpreviewnpm runにて実行できるようにしておきます。

package.json
{
  "scripts": {
    "init": "docsify init ./docs",
    "preview": "docsify serve docs"
  }
}

初期化

それでは初期化を行っていきます。

コマンドプロンプト
npm run init

上記のコマンドを実行することで、docsify init ./docsが実行され、docsディレクトリに以下のファイルが生成されます。

index.htmlエントリーファイル。
README.md Webサイトの核となるMDファイル。
このファイルが解析され、ページが作られる。
.nojekyllGitHub Pagesでホスティングする際に
Jekyllの処理エンジンを使わないようにするためのファイル。

コンテンツはREADME.mdに書いていきます。

プレビュー実行

それではプレビューしてみましょう。

コマンドプロンプト
npm run preview

上記のコマンドを実行することで、docsify serve docsが実行され、http://localhost:3000でローカルサーバーが起動します。

http://localhost:3000にアクセスし、サイトのプレビューを確認し、ちゃんとREADME.mdの内容が表示されていればOKです。

Netlifyでdocsifyサイトを公開してみる

最後に静的サイトのホスティングサービスであるNetlifyを使用して、docsifyを使用したサイトをホスティングしてみます。

実際にホスティングしたものがこれです。

それでは手順を紹介していきます。

デプロイ手順

Netlifyへのデプロイ方法は公式のドキュメントに書かれていますので、今回はざっくりとした手順を紹介します。

GitHubに公開したいdocsifyプロジェクトのリポジトリを作成し、コードをプッシュしておく。
Netlifyにログインし、「Team overview」ページから「Add new site」ボタンをクリックし、「Import an existing project from a Git repository」を選択する。
「Connect to Git provider」で「GitHub」を選択する。
GitHubの公開したいdocsifyプロジェクトのリポジトリを選択する。
「Site settings」のステップにある「Basic build settings」まで進んだら、「Base directory」と「Build command」は空白、「Publish directory」はindex.htmlが配置されているディレクトリを指定する。
「Deploy site」ボタンをクリックし、サイトのデプロイが成功すればOK。

以上がNetlifyへのデプロイ方法です。

さいごに

以上がドキュメント静的ジェネレータ「docsify」の紹介でした。

docsifyのメリットはMarkdownファイルで簡単&爆速でシンプルなドキュメントサイトを作ることができる点です。

Markdownはナレッジ管理する上でもオススメなフォーマットです。

Markdown + Gitでナレッジ管理をオススメする理由」という記事も書いているので、ぜひそちらもご覧ください!

Markdown + Gitでナレッジ管理をオススメする理由

docsifyにはまだまだいろいろなテーマやプラグイン等があるようなので、気になった方は公式のドキュメントを覗いてみてください。

この記事が皆さんの助けになれば幸いです!

最後まで読んでいただき、ありがとうございました!

コメントを残す

メールアドレスが公開されることはありません。