ttskch/esaba

Host your markdown docs on esa.io with your own css.

esaba

, _(*1)

esabaとは

esa.io 上の記事データをホストするためのPHP製のWebアプリケーションです。/post/{記事ID} というURLでesa.io上の任意の記事を公開できます。, _(*2)

esa.io	esaba (デフォルトのcss)

esa.io標準の 記事の外部公開 との違い

• 記事の表示に独自のcss/jsを使うことができる（scss/webpack対応）
• カテゴリやタグごとに細かく公開/非公開を設定できる
• 社内のみに公開したい場合などに便利（オンプレなのでWebサーバーレベルでアクセス制限可能）
• 記事中に他の記事へのリンクがある場合は esabaのURLに変換して出力してくれる ので、記事本体のURLと公開用のURLを別々に管理する必要がない

環境要件

• PHP >=8.0.2
• Node >=12
• Composer
• npm

インストール方法

アクセストークンの発行

事前に https://{チーム名}.esa.io/user/tokens/new にてRead権限を持った アクセストークン を発行しておく必要があります。, _(*3)

, _(*4)

任意のサーバーへのインストール

$ composer create-project ttskch/esaba # automatically npm install
$ cd esaba
$ cp .env{,.local}
$ vi .env.local # tailor to your env

# and serve under ./public with your web server

Herokuへのデプロイ

本リポジトリをフォークするか（デプロイ先が公開されてしまってよい場合）、以下の手順にて本リポジトリのコードベースをprivateリポジトリにコピーしてください。, _(*5)

$ git clone git@github.com:ttskch/esaba.git
$ cd esaba
$ git remote set-url origin git@github.com:{user}/{repo}.git # privateリポジトリのURLをセット
$ git push

その上で、 https://heroku.com/deploy?template=https://github.com/{user}/{repo} をブラウザで開くとHerokuにデプロイできます。, _(*6)

, _(*7)

使い方

設定

設定は .env.local または config/esaba.php で行います。, _(*8)

最小限の設定

# .env.local

ESA_TEAM_NAME={チーム名}
ESA_ACCESS_TOKEN={アクセストークン}

アクセス制限

カテゴリ/タグに応じて公開/非公開を設定することができます。設定値はJSON形式の文字列とする必要があり .env.local ではエスケープなどが面倒なので、config/esaba.php で設定するのがおすすめです。, _(*9)

<?php
// config/esaba.php

return json_encode([
    // ...

    // empty to publish all
    'ESABA_PUBLIC_CATEGORIES' => json_encode([
//        'path/to/category1',
//        'path/to/category2',
    ]),

    'ESABA_PUBLIC_TAGS' => json_encode([
//        'tag1',
//        'tag2',
    ]),

    // takes priority of over ESABA_PUBLIC_CATEGORIES
    'ESABA_PRIVATE_CATEGORIES' => json_encode([
//        'path/to/category1/subcategory1',
//        'path/to/category1/subcategory2',
    ]),

    // takes priority of over ESABA_PUBLIC_TAGS
    'ESABA_PRIVATE_TAGS' => json_encode([
//        'tag3',
//        'tag4',
    ]),
]);

また、esabaで配信されるすべてのページについて、検索エンジンのインデックス対象とするかどうかを設定することができます。, _(*10)

設定を省略した場合はデフォルトで「インデックス対象としない」設定になります。インデックス対象としたい場合にのみ、以下のように設定を変更してください。, _(*11)

# .env.local

ESABA_ENABLE_INDEXING=true

HTMLの置換

記事中に他の記事へのリンクがある場合は、esabaでその記事を閲覧するためのURLに自動で置き換えられます。, _(*12)

また、それとは別に任意の置換ルールを設定しておくこともできます。例えば、すべての target="_blank" を削除したい場合は、以下のように設定します。, _(*13)

<?php

return json_encode([
    // ...

    'ESABA_HTML_REPLACEMENTS' => json_encode([
//        '/regex pattern/' => 'replacement',
        '/target=(\'|")_blank\1/' => '',
    ]),
]);

カテゴリ/タグに応じたcss/jsの切り替え

<?php
// config/esaba.php

return json_encode([
    // ...

    // if post matches multiple conditions, tag based condition taks priority of over category based condition
    // if post matches multiple category based conditions, condition for deeper category is enabled
    // if post matches multiple tag based conditions, any arbitrarily one is enabled
    'ESABA_USER_ASSETS' => json_encode([
        'path/to/category' => [
            'css' => 'css/your-own.css',
            'js' => 'js/your-own.js',
        ],
        '#tag_name' => [
            'css' => 'css/your-own.css',
            // if one of "css" or "js" is omitted, default.(css|js) is used
        ],
    ]),
]);

上記のように設定した上で、 ./public/css/post/your-own.css および ./public/js/post/your-own.js を設置することで、path/to/category カテゴリや #tag_name タグに該当する記事に対して指定したcss/jsを適用させることができます。, _(*14)

Webhook

esa Generic Webhook を使うことで、esa.io上で記事が作成/更新されたときに、esaba側のキャッシュを自動で更新させることができます。, _(*15)

, _(*16)

# .env.local

ESA_WEBHOOK_SECRET={シークレット} # シークレットなしの場合は設定不要

/webhook へのアクセスの解放

もしWebサーバーレベルでのアクセス制限を設定している場合、 /webhook へのアクセスはesa.ioからのwebhookリクエストを受け取るために解放しておく必要があります。, _(*17)

例えば、Apache 2.4の場合は以下のような設定が必要になります。, _(*18)

<Location />
    Require ip xxx.xxx.xxx.xxx
</Location>

<LocationMatch ^/(index.php|webhook?)$>
    Require all granted
</LocationMatch>

開発

ローカルサーバー起動

$ php -S localhost:8000 -t public
# or if symfony-cli is installed
$ symfony serve

ブラウザで http://localhost:8000/post/:post_number へアクセス。, _(*19)

webpackによる独自アセットのビルド

esabaはscss/webpackに対応しています。, _(*20)

./assets/post/user/{エントリー名}.(scss|js) に独自アセットを配置し、, _(*21)

$ yarn build
# or
$ npm run build

を実行すると、以下のように build/{エントリー名}.(css|js) というパスで利用できるようになります。, _(*22)

<?php
// config/esaba.php

return json_encode([
    // ...

    'ESABA_USER_ASSETS' => json_encode([
        'path/to/category' => [
            'css' => 'build/your-own.css',
            'js' => 'build/your-own.js',
        ],
    ]),
]);