DropPagesというDropboxにテンプレートファイルとMarkdownで書いたコンテンツ(記事)を置いて公開できるサービスを利用してどこでもコードリーディングができる環境を作って使っています。

DropPagesについて

DropPagesの導入方法

詳細はGetting started | DropPages.comを見る。

  1. DropPagesから好きなThemeファイルのzipをダウンロードする
  2. zipを展開すると.droppages.com というフォルダができるので、
    このフォルダ毎、Dropboxフォルダの好きな所に置く
  3. ..droppages.com のを自分の使いたいサブドメイン名にする。
    たとえばうちはhttp://sig.droppages.com/なので、sig.droppages.comというフォルダ名にリネーム。
  4. Dropboxフォルダ内なら、右クリック->Dropbox->このフォルダを共有からDropboxのサイトが開いて、
    コラボレータのメールアドレスを入力する画面になる。
  5. 招待するコラボレーターにserver1@droppages.comと入力すれば共有は完了。

image

後は、その共有したフォルダ名のアドレス(sig.droppages.comならhttp://sig.droppages.com/)にアクセスできるようになるまで待つだけ(結構かかります。一日とか)

Droppagesの構造

FolderLayout | DropPages.com

sig.droppages.com
├Content[DIR]
│  └記事となるmarkdownファイル
├Public[DIR]
│  └css, js ,画像などのテンプレートから呼び出すリソース
└Templates[DIR]
   └テンプレート.html
どのテンプレートも3つのフォルダからできていて、それぞれの意味は上のような感じです。
Publicは単純にリソースをおけて、テンプレートやコンテンツから/ ルートでアクセスできます。
テンプレートは思ったより頑張れるので、Managing pages | DropPages.comや既存のテーマを参考にいじってみるのがいいと思います。
簡単にまとめると

構文

意味

:テンプレート名

テンプレート間でのテンプレート内容を継承
@変数名 変数に入れたい文字列
@変数名
変数に入れたい文字列のブロック
複数行でもいい(Bodyとかに使われてる)
変数名の定義はコンテンツ、テンプレートどちらでもできる。
変数名に入れたものはテンプレートから参照して使う。
で参照できて、プレースホルダ部分は変数が定義されてないときの初期値を決められる。
@Titleや@Bodyなど



最初から決められてる特殊な変数がある。
Managing templates | DropPages.com
テンプレートを書くときに、子のコンテンツを列挙するやサイトマップ的なやパンくずリスト的ななどは結構工夫すればブログみたいになる
_drafts フォルダ _drafts という名前でコンテンツ内にフォルダを作れば、それはドラフト扱いになり公開されない。
フォルダじゃなくても_と先頭につければ
などの列挙対象にはならない気がする。(直接URLたたくとアクセスできるけど)

自分のサイトはazu/4-Code-Reading – GitHubでコンテンツ共々テンプレートも公開しているので、適当に見てください。(アクセス解析のコードとは固有になっちゃってるけど)

Droppagesのコンテンツ(記事)はtxtファイルに、以下のような感じで書いていって保存すると、Dropboxで同期されて自動でWebサイト側が更新される仕組みなってます。

@Title タイトル
@Body
記事内容書ける
Markdown記法を使える
これ以外にも変数は定義できるけど
自分がDroppagesを気に入った理由にMarkdown記法で書けるという所が結構大きくて、これが結構便利です。
デモなどではtxtファイルになっていますが拡張子がmdなmarkdownファイルでも問題なく扱えます!
Markdownの書き方は

などを見るとよいと思います。

MarkdownならiPadのTextasticなど対応してるアプリもいろいろある。

コードリーディング

Droppagesを使えば、markdownファイルに書いて保存するだけど自動的にWebに公開するという手順が簡単に行えます。
で、なんでコードリーディングサイトにしようと思ったのかは、元々Markdownなどでコードリーディング記録を書きたいなーと思っててGithub pages + Sphinxなどいろいろ試してたんですが面倒な手順が多くて、そこに自動的にMarkdownを変換して公開できるサービスとしてDropPagesがきたわけです。

コードリーディングの環境にはWebStormを使っています。
WebStormならMarkdownプラグイン(EAPだと動かなかったりするのでWebstormは正式版を使う)があるのと、WebStormには構文解析をおこなってコードの構造がつかみやすいのでコードリーディング自体に最適だと思います。
(ブックマークや変数、関数、参照先へのジャンプ、アウトラインなどなど)

WebStormはファイルの分割表示を持ってるので、左でコードを読んで、右でMarkdown形式でコードリーディングの記録を書いていくという事もできます(EmacsとかVimとかでも似たような環境作れると思う)

imageimageimageMarkdownのプレビューもその場でできる。

少し戻って、テンプレートはいろいろいじって、記事毎にいろいろメタ情報の変数を定義させるようにすれば、普通のブログと遜色ないぐらいの記事が簡単に作れます。
毎回その変数定義を手入力だと面倒なので、WebStormのテンプレートからファイルを作るFile Templeteの機能を使って以下のような感じにしています

実際に入力して出てくる感じは下のようなもの。後はBody以下を書いていくだけ。

@Title Underscore.js
@description 便利関数の詰め合わせライブラリUnderscore.jsのコードリーディング
@keywords Underscore.js
@Dates 2011年05月03日
@Body
[Underscore.js] 1.1.6のソースコードを見ていく

Table of Contentsによるとそれぞれジャンル分けされているので、それに沿って読む。
実際にUnderscore.jsのコードリーディングをしていて、Markdownはコードリーディングととても相性がよいと思いました。
> が先頭にあれば引用になったり(一行preみたいな使い方できる)
タブがスペース4つで字下げすれば、コードブロックになるので編集中もとても読みやすくコードを書ける。(他の記法のように何かで囲むなどをしなくていいので見通しがよい)
後はMarkdownのリンク管理ですが、これも一カ所にリンクをまめて書くことができるので、上手くやればいい感じにリンクを書ける。
実際の自分のコードリーディング手順は以下のような感じで
  1. コードはブロックぐらいで適当に区切って読んでいく
  2. ## ブロックタイトル とMarkdownにブロックのタイトルをつける(テンプレートで自動的に目次生成をしているため)
  3. コードを読みながらコード本体にコメントとして、コードの解説やアノテーションなどを書いていく
  4. コードブロックを読みながら、気になったことや使い方や例などはMarkdownに書いていく
  5. コードブロックを読み終わったら、そのコードブロックをMarkdownにコピペする(先ほどのように字下げしてpreにする)
  6. 1から繰り返し
  7. 全部読み終わったらDoccoでコンパイルして、コード全体とコメントを見比べしやすいHTMLを生成する。(コード本体にコメントを書いていくのはこれも目的にしているため)

## でサブタイトルをつけて区切っていくのは英語が読めない人向け、英語技術書の読み方 | Web scratchでやっていたような章ごとに本を読んでいくのと同じ感覚でやっています。
またFunctions of undersocore.js – 4 Code Readingなど適当なページを見てもらうと分かると思いますが、h2,h3などのタグには自動的に内部リンクを振って目次を作るためにもサブタイトルをつけています。

また、コンテンツは先ほどから言っているようにmarkdownで書けるので、githubとも相性がいいです。(githubはmdファイルを変換して表示してくれる)
どこまで読んだかをgitで管理できたり、githubなどを使って複数人で共有したりもできるのでいろいろな使い道があると思います。また仮にDropPagesが消滅しても手元にはコンテンツファイルが残るので、markdownならそこそこメジャーなので逃げ道もいろいろあると思います(htmlに変換もできるし)

Dropbox+DropPages+Markdown+GitHub+WebStorm(任意のエディタ)

= 素敵なコードリーディング生活

ここからDropboxに登録すれば250MBのボーナスがうんぬんです。