Host your markdown docs on https://esa.io with your own css.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
assets
bin
config
src
templates
tests
var
web
.gitignore
.scrutinizer.yml
.travis.yml
LICENSE
README.ja.md
README.md
composer.json
package.json
phpunit.xml.dist
webpack.config.js

README.md

esaba

Build Status Scrutinizer Code Quality Code Coverage Total Downloads

日本語はこちら

What's this?

esaba hosts your markdown docs on esa.io. Url like /post/:post_number shows the post publicly.

on esa.io on esaba (with default css)
image image

Advantages compared to built-in "Share Post" feature

  • Can show posts with your own css/js (scss/webpack ready)
  • Flexible setting of access restriction for each category/tag
  • Useful for company internal publishing because it's on-premise
  • No need to know the special sharing urls for each post because of auto replacement of link to other post with corresponding esaba url

Requirements

Installation

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

You must to issue personal access token in advance.

image

Usage

Running in dev

$ COMPOSER_PROCESS_TIMEOUT=0 composer run

And go to http://localhost:8888/index_dev.php/post/:post_number

Configuration

Access restriction

// config/config.php

$app['config.esa.public'] = [
    'categories' => [
        // category names to be published.
        // empty to publish all.
    ],
    'tags' => [
        // tag names to be published.
    ],
];

$app['config.esa.private'] = [
    'categories' => [
        // category names to be withheld.
        // this overwrites esa.public config.
    ],
    'tags' => [
        // tag names to be withheld.
        // this overwrites esa.public config.
    ],
];

Html replacements

esaba replaces links to other post in content html of post with links to see the post on esaba automatically. And you can also fix content before rendering with arbitrary replacements. For example, you can remove all target="_blank" by following.

// config/config.php

$app['config.esa.html_replacements'] = [
    // '/regex pattern/' => 'replacement',
    '/target=(\'|")_blank\1/' => '',
];

Switching css/js according to categories/tags

// config/config.php

$app['config.esa.asset'] = [
    // if post matches multiple conditions, tag based condition overwrites category based condition.
    // if post matches multiple category based conditions, condition based deeper category is enabled.
    // if post matches multiple tag based conditions, any one is arbitrarily enabled.
    'category/full/name' => [
        'css' => 'css/post/your-own.css',
        'js' => 'js/post/your-own.js',
    ],
    '#tag_name' => [
        'css' => 'css/post/your-own.css',
        // if one of 'css' or 'js' is omitted, default.(css|js) is used.
    ],
];

And deploy ./web/css/post/your-own.css and ./web/js/post/your-own.js.

Building your own assets with webpack

esaba is scss/webpack ready. ./assets/post/*.(scss|js) will be built and deploy to ./web/(css|js)/post/*.(css|js) by webpack automatically just like below.

$ vi assets/post/your-own.scss
$ npm run build
  :
$ tree web/css/post
web/css/post
├── default.css
└── your-own.css

0 directories, 2 files

Webhook

You can configure to automatically warm-up caches for created/updated posts using esa Generic Webhook.

image

// config/config.secret.php

$app['config.esa.webhook_secret'] = 'Secret here';

Unrestricting access to /webhook/

If you set some access restrictions on web server layer, you must unrestrict access to /webhook/ for webhook request from esa.io.

For example, on Apache 2.4, config like below.

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

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