README

esaba是什么

esaba是一个PHP制的Web应用程序，用于在esa.io上托管文章数据。/post/{文章ID} 这样的URL可以公开esa.io上的任何文章。

与esa.io标准 文章外部公开 的不同

• 可以使用自定义的css/js显示文章（支持scss/webpack）
• 可以按类别或标签分别设置公开/不公开
• 对于只想在内部公开的情况很方便（本地部署，可以在Web服务器级别进行访问限制）
• 如果文章中包含指向其他文章的链接，则 esaba会自动将其转换为esaba的URL并输出，因此无需分别管理文章本身的URL和公开URL

环境要求

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

安装方法

发布访问令牌

需要事先在 https://{团队名}.esa.io/user/tokens/new 上发布具有读取权限的 访问令牌。

在任意服务器上安装

$ 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

将本存储库fork（如果部署目标是公开的），然后按照以下步骤将本存储库的代码库复制到私有存储库中。

$ 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。

使用方法

设置

设置通过 .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会自动将其替换为用于在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',
        ],
    ]),
]);