add doc/file-structure.md

doc/file-structure.md

@@ -0,0 +1,59 @@
+# blogsyncのエントリーファイル構成
+
+## ブログIDと配信ドメイン
+前提として、blogsyncの設定ファイルのキーに使うドメイン状の文字列は「ブログID」です。これはブログ開設時に決めたドメインで不変です。ですので、多くの場合、ブログIDはブログの配信ドメインと一致します。しかし、独自ドメイン利用している場合、ブログIDと配信ドメインは一致しないことに注意してください。この場合、設定した独自ドメインがブログIDにはならず、当初のものがそのまま使われます。
+
+例えば、筆者(Songmu)は、 https://blog.song.mu という独自ドメインでブログを運営していますが、開設時に指定した songmu.hateblo.jp がブログIDです。
+
+## blogsyncがファイル配置するローカルのルートディレクトリ
+
+blogsyncは設定ファイルの `local_root` と ブログID を連結したパス(`$local_root/$blogID`)をルートディレクトリとしてコンテンツファイルを配置します。
+
+```yaml
+songmu.hateblo.jp:
+  local_root: /Users/Songmu/Blog
+```
+
+例えば上記のような設定に対して `blogsync pull songmu.hateblo.jp` すると `/Users/Songmu/Blog/songmu.hateblo.jp` 以下にコンテンツファイルが配置されます。
+
+ブログIDの `songmu.hateblo.jp` ディレクトリが掘られることが冗長に感じるかもしれません。その場合は `omit_domain` 設定で階層を浅くできます。以下のような具合です。
+
+
+```yaml
+songmu.hateblo.jp:
+  local_root: /Users/Songmu/Blog
+  omit_domain: true
+```
+
+こうすると `/Users/Songmu/Blog` がルートになります。
+
+余談ですが、`local_root` 設定が少し分かりづらい理由としては、当初はオリジナル作者(motemen)に複数ブログを特定のディレクトリ配下で管理したいという動機があり `default.local_root` 一つだけ設定しておけば、そこ配下にブログID毎にディレクトリを掘ることを想定してたのではないかと予想しています。なので、ブログ個別設定に`local_root`を設定することをあまり想定していなかった可能性があります。例えば以下のような設定ファイルを想定していたのではないでしょうか。
+
+```yaml
+songmu.hateblo.jp:
+songmu.hatenablog.com:
+default:
+  local_root: /Users/Songmu/Blogs
+  username: Songmu
+  ...
+```
+
+この辺りは、複雑で分かりづらく、`omit_domain` という設定も後付け感があり名付けもイマイチなので、その辺りを含めて将来的に非互換変更を入れる可能性があります。
+
+## コンテンツファイルの配置
+blogsyncは公開URLのパスと対応した位置にコンテンツファイルを保存します。サブディレクトリ運用の場合、サブディレクトリ含めて保存されます。また、URLのパスは以下の2種類に分かれます。
+
+- 執筆者が明示的に指定するもの。いわゆるslug
+    - ブログ管理画面上では「カスタムURL」、blogsync上は"CustomPath"と呼ばれる
+- はてなブログ側が自動付与するもの
+
+執筆者が明示しない場合の自動付与は **記事公開時**におこなわれる。標準では `2001/02/03/150405` のような時刻ベースのフォーマットになる。他にも、はてなダイヤリーフォーマットや、タイトルを付与したフォーマットがあり、ブログ管理画面から切り替え設定できる。
+
+自動付与の場合「記事公開時に」と書いた通り、下書き時にはURLの付与は行われない。APIのレスポンスには仮のURLが返される。この仮のURLはAPIリクエスト時刻が基準になったものが返されるので、下書き更新時に毎回異なるものが返される。
+
+なので、カスタムパス未指定の下書きは、URLのパスが実質的に未確定なので、blogsyncは `entry/_draft/$entryID.md` という位置にファイルを保存します。この `entryID` はエントリーのEditURLに含まれる数字列のIDです。ちなみに、固定ページはカスタムパス指定必須なので、この位置に下書きが保存されることはありません。
+
+エントリーのURLを変更したい場合、ローカルのコンテンツファイル名を変更してpushすれば、URLも変更されます。
+
+## エントリーと固定ページ
+TBA