みなさん、ドキュメントは何を使って書いていますか？
筆者の場合、提出用のドキュメントは、WordやExcelで作っていますが、その他の多くのドキュメントはテキストエディタで書いています。 最近では、テキストファイルの書式をMarkdown記法に統一するようにしています。
Markdownは、ここで紹介されているように、簡単な文法を覚えるだけでパーサー（変換機）を通すと読みやすいHTMLに変換できる言語です。文法も直感的で比較的覚えやすいので好んで利用するようにしています。
他にもTextileやWikiなど様々な記法があり、好みも分かれますが、どちらにしても後で整形できる書式でドキュメントを書いておけばよいので、軽いテキストファイルでドキュメントを残している人は多いと思います。
しかし、ドキュメントをまとめて見る場合、手動でパーサーを通したりサーバーにアップしてサーバーサイドで変換するのは面倒です。 そこで、テキストベースのMarkdown・Textile・Wiki記法で書かれたドキュメントが簡単に見るためのドキュメントフレームワーク「Invisible.js」を作ることにしました。
フレームワークでは、できるだけ環境依存しないようにJavaScriptだけで動くようにし、ブラウザでドキュメントをまとめて見れるようにしています。
オープンソース(MIT License)として公開しているので、ご自由にお使いいただけます。
ひとまずデモとドキュメントとサンプルを見てもらえれば、なんとなくイメージがつかめると思います。 （張り切って英語でドキュメントを作ってみようとしたのですが、途中から気力が衰えてきてむちゃくちゃな英語になってしまっています。すみません）
最新のパッケージはGoogle Codeにアップしていますので、そちらからダウンロードしてください。
英語では伝わらない部分も多いので、「Invisible.js」の使い方も含めて日本語で詳しく紹介しておきます。
「Invisible.js」とは？
「Invisible.js」は、JavaScriptで作られたドキュメントフレームワークです。 簡単に言うと、テキスト形式のドキュメントファイルを整形してブラウザで見るツールです。
「Invisible.js」の特徴
- 用意しておいたテンプレートにドキュメントを読み込んで表示します。
- ドキュメントファイルの指定はURLのアンカーで行います。
- ドキュメントファイルの読み込みはAjaxで動的に行われます。
- Markdown、Textile、Wiki、JSON、HTMLのフォーマットに対応しています。
- 記法をコンバートするためのプログラムを自作して組み込むこともできます。
- ドキュメントファイルの拡張子によってフォーマットを自動判別します。
- テンプレートエンジン「Jarty」を利用することができます。
- 1つのページに複数のドキュメントを読み込むことができます。
ダウンロード
「Invisible.js」ダウンロードページから最新のパッケージ(zipファイル)をダウンロードしてください。
解凍した中にある、docs/index.htmlをブラウザで開いてください。 「Invisible.js」のドキュメントが表示されます。このドキュメントの読み込みもフレームワークが使われています。
但し、ブラウザによってはローカルファイルを開く際に設定が必要です。
- InternetExplorerの場合、ローカルファイルをブラウザで開くとセキュリティの警告がでますが、許可して表示してください。
- Chromeの場合、デフォルトではローカルファイルでAjaxが使えないので起動オプションに-allow-file-access-from-filesを加えてください。
- FirefoxとSfariは問題なく開きます。(Windows XPで確認しました)
「Invisible.js」の仕組み
先程、アクセスしたdemo/index.htmlを見てみましょう。
head部分で、フレームワークの本体と必要なJavaScriptを読み込んでいます。
<script type="text/javascript" src="../lib/jquery-1.5.2.min.js"></script> <script type="text/javascript" src="../lib/jquery.history.js"></script> <script type="text/javascript" src="../lib/invisible.js"></script>
body部分は、下記のようにヘッダーとフッター以外は、空のDIVタグしかありません。
<header> <h1><a href="#/">Invisible.js</a></h1> </header> <div id="content"></div> <footer> <p>Copyright © 2011 <a href="http://www.liveout.co.jp/" target="_blank">LIVEOUT, Inc.</a>, All Rights Reserved.</p> </footer>
この状態で、アクセスされるとフレームワークは、IDが"content"となっている場所にドキュメントを読み込んでパースします。 読み込まれるドキュメントのファイル名は、デフォルトで"default.txt"となります。 したがって、demo/default.txtが読み込まれます。
default.txtは、下記のようなMarkdown記法で書かれたファイルです。
## Documentation ### About Invisible.js Invisible.js is javascript documentation framework. ### Features - document auto loading (url anchor or html attribute) - switching parser (Markdown, Textile, Wiki, Json, Html) - dynamically switching between documents (browser back support) - attach jarty template engine (Smarty like language)
このように、アクセスしたindex.htmlがテンプレートとなり、ドキュメントファイルを読み込んでコンテンツ部分を動的書き換えられる仕組みです。
ドキュメントを作っている人は、HTMLやJavaScript、CSSののことを意識する必要はありません。 テキストファイルを自分の好きな記法で書くだけでよいのです。
ページ遷移
他のドキュメントのページに遷移する場合、URLのアンカーを利用します。
例えば、下記のようなHTMLのリンクがあった場合、アンカーがsampleとなっているのでsample.txtドキュメントをコンテンツ部分に読み込みます。（拡張子を指定しない場合は、デフォルトで".txt"になります）
<a href="#sample">sample page</a>
もちろんMarkdownでもアンカーリンクは指定できます。
[sample page](#sample)
別のフォルダのドキュメントを読みたい場合は、URLのアンカーにパスを含めて指定します。
例えば、newfolder/test.txtがドキュメントファイルの場合は下記のようなリンクになります。拡張子を自分で指定してもかまいません。
<a href="#newfolder/test.txt">test page</a>
テンプレートの編集
先程のテンプレートでは、DIVタグの"content"にだけドキュメントが読み込まれましたが、ヘッダーやフッターなど別の場所にドキュメントを読み込ませることもできます。
<header data-file="header"></header> <div id="content"></div> <footer id="footer" class="importdoc"></footer>
上記の場合は、コンテンツ部分だけでなく、ヘッダー部分にheader.txt、フッター部分にfooter.txtのドキュメントが読み込まれます。
読み込ませたい要素に、data-file属性でドキュメントファイル名を指定します。 それ以外の方法として、classにimportdocを指定すると、idをドキュメントファイル名として読み込むこともできます。
別のフォーマットで書かれたドキュメントを読み込む
今までは、Markdownだけでしたが、TextileやWikiなど他のフォーマットで書かれたドキュメントを読み込むこともできます。
フォーマットを指定する方法として、テンプレートで指定する方法とURLのアンカーで指定する方法の2種類があります。
テンプレートで指定する場合は、下記のようにdata-format属性で指定します。
<div id="content" data-format="textile"></div>
URLのアンカーで指定する場合は、下記のようにアンカーの後ろにパイプ＋フォーマットを加えます。
<a href="#sample|textile">textile sample page</a>
しかし、このような指定の方法は煩わしく感じると思います。 フレームワークでは、フォーマットを拡張子から自動判別することができます。 フォーマットにautoが指定されると自動判別になります。（何も指定されていない場合は、autoになっています。）
したがって、ドキュメントはフォーマットにあわせた拡張子で保存しておくだけで問題ありません。
フレームワークがサポートしているドキュメントのフォーマットと拡張子は下記のものです。
| フォーマット | 拡張子 | 備考 |
|---|---|---|
| auto | 自動判別 | (デフォルト) |
| markdown | .txt, .markdown, .md, .mkd | Markdown記法 |
| textile | .textile, .tt | Textile記法 |
| wiki | .wiki | Wiki記法 |
| json | .json | JSONフォーマット |
| html | .html, .htm |
基本セットアップ
実際に、自分が作成したドキュメントファイルをフレームワークで閲覧したい場合、次の手順でセットアップを行ってください。
ドキュメントのルートフォルダに、テンプレートファイルを用意します。docs/index.htmlを参考にしてください。 テンプレートファイル名は、index.htmlでなくてもかまいません。viewer.htmlなど自由に決めてください。
フレームワークのライブラリーをコピーしてください。ライブラリーは、libフォルダの中にあります。
これで準備完了です。
default.txtファイルを用意して目次となるドキュメントを作り、そこから各ドキュメントへのリンクを張ると良いでしょう。
「Invisible.js」の使いどころ
シンプルなドキュメントフレームワークなので、いろいろな場所で使えると思います。
個人的には、Dropboxの中にこのフレームワークを入れておくと、ものすごく重宝するのでおすすめです。Publicフォルダの下においておくと、ドキュメントを簡単に外部公開できます。この辺のやり方は、別の機会にでも詳しく首魁したいと思います。
その他にも、社内のドキュメントサーバーの共有フォルダーに入れたり、プログラムのヘルプページとして使ったりもできると思います。
MIT Licenseで公開しているので、いろいろ改造してもらっても問題ありません。
この記事では、全ての機能を紹介しきれていません。 パッケージの中に入っているドキュメントやサンプルにも載っていますので詳しくはそちらをご覧ください。
最後に、ドキュメントを見るためのフレームワークなのに、なんでInvisible（目に見えない）というネーミングなのか？とツッコまれそうなので、一応理由を書いておきます。
仕組みを理解してもらえると分かるのですが、テンプレートとなるhtmlそのものには何もありません。したがって、ブラウザでソースを見てもドキュメントのソースは目に見えません(Ajaxで動的に読み込まれているため)。 ドキュメントのソースは見えないけど表示されているから不思議？！そんな発想でネーミングをつけてみました。
是非、試していただき、もっとこうしてほしいなどの要望をフィードバックしてもらえるとうれしいです。
【HTML5で新しくサイトを作る人にオススメ】 「HTML KickStart」を使えば、ベースとなる要素が整備されているので、スクラッチでサイトを素早く作ることができますよ。是非チェックしてみてください。 人と違うデザインのサイトをスクラッチで作るならHTML KickStartをベースにするといいですよ！
【マウスで銀はがしを体験できるプラグイン】 こちらはユニークはjQueryプラインです。用途としては、ブラウザ上で簡単なスクラッチくじを実現したい場合や、宝探しゲームのようなものや、レア画像を削って見せていくなどに使えそうですよw スクラッチ宝くじのような削ると見えてくるjQueryプラグイン「wScratchPad」
【コーディングスピードが一気に加速するHTMLエディタ】 コーディングしながらリアルタイムに結果を確認することができるブラウザ上で動作するHTMLエディタです。とても便利なので是非チェックしてみてください。 HTML5、CSS3、JavaScriptがリアルタイム編集できる！軽量HTMLエディタ「Liveweave」