esaba
esabaとは
esa.io 上の記事データをホストするためのPHP製のWebアプリケーションです。/post/{記事ID} というURLでesa.io上の任意の記事を公開できます。
| esa.io | esaba (デフォルトのcss) |
|---|---|
 |
 |
esa.io標準の 記事の外部公開 との違い
- 記事の表示に独自のcss/jsを使うことができる（scss/webpack対応）
- カテゴリやタグごとに細かく公開/非公開を設定できる
- 社内のみに公開したい場合などに便利（オンプレなのでWebサーバーレベルでアクセス制限可能）
- 記事中に他の記事へのリンクがある場合は esabaのURLに変換して出力してくれる ので、記事本体のURLと公開用のURLを別々に管理する必要がない
環境要件
インストール方法
アクセストークンの発行
事前に https://{チーム名}.esa.io/user/tokens/new にてRead権限を持った アクセストークン を発行しておく必要があります。
任意のサーバーへのインストール
$ 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 serverHerokuへのデプロイ
本リポジトリをフォークするか（デプロイ先が公開されてしまってよい場合）、以下の手順にて本リポジトリのコードベースをprivateリポジトリにコピーしてください。
$ git clone [email protected]:ttskch/esaba.git
$ cd esaba
$ git remote set-url origin [email protected]:{user}/{repo}.git # privateリポジトリのURLをセット
$ git pushその上で、 https://heroku.com/deploy?template=https://github.com/{user}/{repo} をブラウザで開くとHerokuにデプロイできます。
使い方
設定
設定は .env.local または config/esaba.php で行います。
最小限の設定
# .env.local
ESA_TEAM_NAME={チーム名}
ESA_ACCESS_TOKEN={アクセストークン}
アクセス制限
カテゴリ/タグに応じて公開/非公開を設定することができます。設定値はJSON形式の文字列とする必要があり .env.local ではエスケープなどが面倒なので、config/esaba.php で設定するのがおすすめです。
<?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で配信されるすべてのページについて、検索エンジンのインデックス対象とするかどうかを設定することができます。
設定を省略した場合はデフォルトで「インデックス対象としない」設定になります。インデックス対象としたい場合にのみ、以下のように設定を変更してください。
# .env.local
ESABA_ENABLE_INDEXING=true
HTMLの置換
記事中に他の記事へのリンクがある場合は、esabaでその記事を閲覧するためのURLに自動で置き換えられます。
また、それとは別に任意の置換ルールを設定しておくこともできます。例えば、すべての target="_blank" を削除したい場合は、以下のように設定します。
<?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を適用させることができます。
Webhook
esa Generic Webhook を使うことで、esa.io上で記事が作成/更新されたときに、esaba側のキャッシュを自動で更新させることができます。
# .env.local
ESA_WEBHOOK_SECRET={シークレット} # シークレットなしの場合は設定不要
/webhook へのアクセスの解放
もしWebサーバーレベルでのアクセス制限を設定している場合、 /webhook へのアクセスはesa.ioからのwebhookリクエストを受け取るために解放しておく必要があります。
例えば、Apache 2.4の場合は以下のような設定が必要になります。
<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 へアクセス。
webpackによる独自アセットのビルド
esabaはscss/webpackに対応しています。
./assets/post/user/{エントリー名}.(scss|js) に独自アセットを配置し、
$ yarn build
# or
$ npm run buildを実行すると、以下のように build/{エントリー名}.(css|js) というパスで利用できるようになります。
<?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',
],
]),
]);![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent