Leafonyの技術資料をまとめたサイトをgithub.ioで公開

Leafony

皆さんこんにちは。　taltalpと申します。

今回は、Leafonyの技術資料をまとめたサイトを公開したので、
どのように変わったのか、どのようにしてサイトを作ったのかを書きたいと思います。
ハードウェア製品のドキュメントページを作る方にとって参考になれば嬉しいです。

まずはじめに、こちらが今回公開したサイトです。

https://docs.leafony.com/

ぜひサイトにアクセスして確かめてみて下さい。

Leafonyを使う人、使おうと考えている人が、簡単に使い方やサンプル、回路図などを知っていただけるようなページを目指しています。

質問や分かりにくいところがありましたら、お気軽にご連絡ください。

もともとのLeafonyの技術資料はトリリオンノード研究会のページにありました。

しかし、このページはLeafonyを開発している団体向けのページで、開発段階時点での資料等古い情報が載っていたり、研究会に関する情報が載っていたりなど、技術資料以外にも様々な情報が載っているため、単にLeafonyを使いたいというユーザにとっては分かりにくいページでした。

新しいページでは技術資料のみを取り出し、Leafonyを使う人にとって必要な情報のみが見れるよう、シンプルな作りのページにまとめました。

ここからが本題です。

新しいLeafonyのページでは以下の点に留意して開発しました。

記事の更新履歴を残すことができる
サーバーの管理はなるべく容易に
定期的な記事の更新が簡単に行える
Markdownで記事が書ける
サイトのスタイル等は柔軟に変更可能であること

まず、一番最初に、サーバーの管理の負担をなるべく減らすべく、サイトはGitHub Pagesで公開することを決めていました。

GitHub PagesはGitHubのリポジトリ上にHTMLやMarkdown等で記述したWebページを置いておくと、それをWebサイトとしてインターネット上に公開してくれるサービスで無料で使えます。

サイトへのアクセス数が増加した時の対応や、サーバーのセキュリティ対策を行うことは、素人がやるべき事ではないので、このあたりをすべてGitHub Pagesに任せてしまうことで、負担が一気に減ります。また、GitHubはファイルの編集履歴を残すためのツールなので、更新履歴機能の実装もこれで解決できました。

次に、MarkdownでGitHub Pagesで公開できるようなページを生成するツールとしてHugoという静的サイトジェネレータを使用しました。HugoはMarkdownでスタイリングしたテキストをHTMLやCSSといったファイルに変換してくれるツールです。

さらに、Hugo向けのテーマとしてDocsyを使いました。
Hugoには様々なテーマがありますが、Docsyは技術資料を公開するのに特化したテーマです。
Markdownは文章の情報しか持つことができませんが、HugoはこのDocsyテーマを元にテキストやサイドバー等の配置を決めて、最終的にHTMLとCSSを生成します。

後はこれらをGithubリポジトリにコミットすることで公開できます。

参考までに、新しいLeafonyのページのGitHubリポジトリはこちらです。
https://github.com/Leafony/leafony.github.io

各ツールの使い方やインストール方法等については今回は説明を省略しますが、非常に便利なツールがフリーで使えるということで紹介させていただきました。

Leafonyのページを見て、自分の製品等の資料をまとめるのに使えそうだなと思っていただければ嬉しいです。