DUICUO

現在の場所： ホーム > 記事 > DocsifyとGitHub Pagesを使ってドキュメントウェブサイトを作成する方法

DocsifyとGitHub Pagesを使ってドキュメントウェブサイトを作成する方法

[[340291]]

Docsify を使用してドキュメント Web ページを作成し、GitHub Pages に公開します。

ドキュメント作成は、オープンソースプロジェクトをユーザーがスムーズに進める上で重要な要素ですが、開発者にとって必ずしも最優先事項ではありません。開発者は、アプリケーションの改善に注力するあまり、ユーザーによる利用を支援することに注力していない場合があるからです。だからこそ、開発者にとってドキュメント作成を容易にすることが非常に重要になります。このチュートリアルでは、その方法の一つとして、DocsifyドキュメントジェネレーターとGitHub Pagesを組み合わせる方法を紹介します。

GitHub Pagesはデフォルトで、HTML、CSS、その他のウェブテクノロジーをサポートする静的ウェブサイトジェネレーターであるJekyllを使用するように促します。JekyllはMarkdownでエンコードされたドキュメントファイルから静的ウェブサイトを生成でき、GitHubはそれらの.mdまたは.markdown拡張子を自動的に認識します。この設定でも良いのですが、別の方法を試してみたかったのです。

幸いなことに、GitHub PagesはHTMLファイルをサポートしているため、Docsifyなどの他のウェブサイト構築ツールを使用してこのプラットフォーム上にウェブサイトを作成できます。DocsifyはMITライセンスに基づくオープンソースプロジェクトで、GitHub Pages上で魅力的で洗練されたドキュメントウェブサイトを簡単に作成できます。

ドクシファイ

Docsifyを使い始める

Docsify をインストールするには 2 つの方法があります。

  1. NPM 経由で Docsify のコマンドライン インターフェイス (CLI) をインストールします。
  2. 独自のindex.html手動で作成します。

DocsifyはNPMの使用を推奨していますが、私は2番目の方法を使用します。NPMを使用する場合は、クイックスタートガイドの指示に従ってください。

GitHubからサンプルコンテンツをダウンロードする

この例のソースコードは、プロジェクトのGitHubページに既に公開されています。ファイルを個別にダウンロードすることも、以下の方法でリポジトリをクローンすることもできます。

  1.  git clone https : //github.com/bryantson/OpensourceDotComDemos

次に、 cd使用してDocsifyDemoディレクトリに移動します。

以下に、Docsify の修正方法をご理解いただけるよう、サンプルリポジトリからクローンしたコードを示します。ご希望であれば、Docsify ドキュメントの例のように、新しいindex.htmlファイルを最初から作成することもできます。

  1.  <!-- index.html -->
  3.  <!DOCTYPE html>
  4.  <html>
  5.  <head>
  6.   <meta http-equiv = "X-UA-Compatible" content = "IE=edge,chrome=1" >
  7.   <meta name = "viewport" content = "width=device-width,initial-scale=1" >
  8.   <meta charset = "UTF-8" >
  9.   <link rel = "stylesheet" href = "//cdn.jsdelivr.net/npm/docsify/themes/vue.css" >
  10.  </head>
  11.  <body>
  12.   <div id = "app" ></div>
  13.   <script>
  14.  window . $docsify = {
  15.       //...
  16.     }
  17.   </script>
  18.   <script src = "//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js" ></script>
  19.  </body>
  20.  </html>

Docsifyの仕組みを見る

私の GitHub リポジトリをクローンしてDocsifyDemoディレクトリに切り替えると、次のようなファイル構造が表示されます。

クローンしたGitHubのファイル内容

ファイル名/フォルダ名コンテンツ
index.html Docsify のメイン初期化ファイル。最も重要なファイルでもあります。
_sidebar.mdナビゲーションを生成する
README.mdドキュメントルートディレクトリ内のデフォルトのMarkdownファイル
images README.md
その他のディレクトリとファイルナビゲート可能なMarkdownファイルが含まれています

Docsify が動作するために必要なのはindex.htmlだけです。このファイルを開いて内容を確認してください。

  1.  <!-- index.html -->
  3.  <!DOCTYPE html>
  4.  <html>
  5.  <head>
  6.   <meta http-equiv = "X-UA-Compatible" content = "IE=edge,chrome=1" >
  7.   <meta name = "viewport" content = "width=device-width,initial-scale=1" >
  8.   <meta charset = "UTF-8" >
  9.   <link rel = "stylesheet" href = "//cdn.jsdelivr.net/npm/docsify/themes/vue.css" >
  10.   <title> Docsify Demo </title>
  11.  </head>
  12.  <body>
  13.   <div id = "app" ></div>
  14.   <script>
  15.  window . $docsify = {
  16.  el : "#app" ,
  17.  repo : 'https://github.com/bryantson/OpensourceDotComDemos/tree/master/DocsifyDemo' ,
  18.  loadSidebar : true ,
  19.     }
  20.   </script>
  21.   <script src = "//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js" ></script>
  22.  </body>
  23.  </html>

これは基本的には通常の HTML ファイルですが、次の 2 行を見てください。

  1.  <link rel = "stylesheet" href = "//cdn.jsdelivr.net/npm/docsify/themes/vue.css" >
  2.  ... 一些其它内容...
  3.  <script src = "//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js" ></script>

これらの行は、コンテンツ配信ネットワーク（CDN）URLを使用してCSSとJavaScriptを提供し、ウェブサイトをDocsifyサイトに変換します。これらの行を追加することで、通常のGitHubページをDocsifyページに変換できます。

<body> ` タグの後の最初の行は、レンダリングされるコンテンツを指定します。

  1.  <div id = "app" ></div>

Docsify は、完全に新しいページを更新する代わりに、シングルページ アプリケーション (SPA) アプローチを使用して要求されたページをレンダリングします。

最後に、 <script> ` ブロック内の行を見てみましょう。

  1.  <script>
  2.  window . $docsify = {
  3.  el : "#app" ,
  4.  repo : 'https://github.com/bryantson/OpensourceDotComDemos/tree/master/DocsifyDemo' ,
  5.  loadSidebar : true ,
  6.     }
  7.  </script>

このブロックでは:

  • el属性は基本的に、「これは私が探しているidなので、これを見つけてそこにレンダリングしてください」という意味です。
  • repo値を変更して、ユーザーが右上隅の GitHub アイコンをクリックしたときにリダイレクトされるページを決定します。

  • loadSideBar trueに設定すると、Docsify はナビゲーション リンクを含む_sidebar.mdファイルを検索します。

すべてのオプションは、Docsify ドキュメントの設定セクションで確認できます。

次に、 _sidebar.mdファイルを見てみましょうindex.htmlでloadSidebar属性をtrueに設定しているため、Docsify は_sidebar.mdファイルを検索し、その内容に基づいてナビゲーションファイルを生成します。サンプルリポジトリの_sidebar.mdの内容は次のとおりです。

  1.  <!-- docs/_sidebar.md -->
  4.  * [HOME](./)
  6.  * [Tutorials](./tutorials/index)
  7.  * [Tomcat](./tutorials/tomcat/index)
  8.  * [Cloud](./tutorials/cloud/index)
  9.  * [Java](./tutorials/java/index)
  11.  * [About](./about/index)
  13.  * [Contact](./contact/index)

Markdownのリンクフォーマットを使用してナビゲーションを作成します。「Tomcat」、「Cloud」、「Java」などのリンクはインデントされていることに注意してください。つまり、親リンクの下に子リンクとして表示されます。

README.mdやimagesなどのファイルはリポジトリの構造に関連しますが、その他のすべての Markdown ファイルは Docsify Web ページに関連します。

ダウンロードしたファイルを必要に応じて修正してください。次に、これらのファイルをGitHubリポジトリに追加し、GitHub Pagesを有効にしてプロジェクトを完了します。

GitHubページを有効にする

サンプルの GitHub リポジトリを作成し、次の GitHub コマンドを使用してコードをチェックアウト、コミット、プッシュします。

  1.  $ git clone 你的 GitHub 存储库位置
  2. $ cd 你的 GitHub 存储库位置
  3. $ git add .
  4.  $ git commit - m "My first Docsify!"
  5.  $ git push

GitHub Pagesページを設定します。新しいGitHubリポジトリで「設定」をクリックします。

GitHubの設定リンク

「GitHub Pages」が表示されるまで下にスクロールします。

GitHub Pagesの設定

「ソース」セクションを見つけます。

GitHub Pagesの設定

「ソース」の下のドロップダウンメニューをクリックします。通常は「masterブランチ」に設定しますが、必要に応じて他のブランチを使用することもできます。

ソースをマスターブランチに設定する

これで完了です！GitHub Pagesページへのリンクが作成されました。リンクをクリックするとページに移動し、Docsifyでレンダリングできます。

GitHub Pagesドキュメントサイトへのリンク

次のようになります。

GitHub Pages 上の Docsify サイトの例

結論は

Docsifyを使えば、HTMLファイルとMarkdownテキストを編集するだけで、美しくデザインされたドキュメントウェブサイトを作成できます。どう思われますか？ぜひコメントを残していただくか、GitHub Pagesで使える他のオープンソースツールを共有してください。

ラベル

関連するおすすめ記事

ランダムにおすすめされた記事

人気のタグ