Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ttskch/esaba
Host your markdown docs on https://esa.io with your own css.
https://github.com/ttskch/esaba
css esa-io markdown scss webpack
Last synced: 2 months ago
JSON representation
Host your markdown docs on https://esa.io with your own css.
- Host: GitHub
- URL: https://github.com/ttskch/esaba
- Owner: ttskch
- License: mit
- Created: 2017-10-13T23:53:46.000Z (about 7 years ago)
- Default Branch: main
- Last Pushed: 2022-05-16T08:45:19.000Z (over 2 years ago)
- Last Synced: 2024-04-28T07:01:26.480Z (8 months ago)
- Topics: css, esa-io, markdown, scss, webpack
- Language: PHP
- Homepage:
- Size: 335 KB
- Stars: 18
- Watchers: 4
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# esaba
[](https://github.com/ttskch/esaba/actions/workflows/test.yaml)
[](https://scrutinizer-ci.com/g/ttskch/esaba)
[](https://scrutinizer-ci.com/g/ttskch/esaba)
[](https://packagist.org/packages/ttskch/esaba)
[](https://packagist.org/packages/ttskch/esaba)
## esabaとは
[esa.io](https://esa.io) 上の記事データをホストするためのPHP製のWebアプリケーションです。`/post/{記事ID}` というURLでesa.io上の任意の記事を公開できます。
| esa.io | esaba (デフォルトのcss) |
| --- | --- |
|  |  |
## esa.io標準の [記事の外部公開](https://docs.esa.io/posts/110) との違い
- 記事の表示に独自のcss/jsを使うことができる（scss/webpack対応）
- カテゴリやタグごとに細かく公開/非公開を設定できる
- 社内のみに公開したい場合などに便利（オンプレなのでWebサーバーレベルでアクセス制限可能）
- 記事中に他の記事へのリンクがある場合は **esabaのURLに変換して出力してくれる** ので、記事本体のURLと公開用のURLを別々に管理する必要がない
## 環境要件
- PHP >=8.0.2
- Node >=12
- [Composer](https://getcomposer.org/)
- [npm](https://www.npmjs.com/)
## インストール方法
### アクセストークンの発行
事前に `https://{チーム名}.esa.io/user/tokens/new` にてRead権限を持った [アクセストークン](https://docs.esa.io/posts/102#%E8%AA%8D%E8%A8%BC%E3%81%A8%E8%AA%8D%E5%8F%AF) を発行しておく必要があります。
### 任意のサーバーへのインストール
```bash
$ 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リポジトリにコピーしてください。
```bash
$ 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
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
json_encode([
// '/regex pattern/' => 'replacement',
'/target=(\'|")_blank\1/' => '',
]),
]);
```
#### カテゴリ/タグに応じたcss/jsの切り替え
```php
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](https://docs.esa.io/posts/37) を使うことで、esa.io上で記事が作成/更新されたときに、esaba側のキャッシュを自動で更新させることができます。
```
# .env.local
ESA_WEBHOOK_SECRET={シークレット} # シークレットなしの場合は設定不要
```
#### `/webhook` へのアクセスの解放
もしWebサーバーレベルでのアクセス制限を設定している場合、 `/webhook` へのアクセスはesa.ioからのwebhookリクエストを受け取るために解放しておく必要があります。
例えば、Apache 2.4の場合は以下のような設定が必要になります。
```
Require ip xxx.xxx.xxx.xxx
Require all granted
```
## 開発
### ローカルサーバー起動
```bash
$ 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)` に独自アセットを配置し、
```bash
$ yarn build
# or
$ npm run build
```
を実行すると、以下のように `build/{エントリー名}.(css|js)` というパスで利用できるようになります。
```php
json_encode([
'path/to/category' => [
'css' => 'build/your-own.css',
'js' => 'build/your-own.js',
],
]),
]);
```