From a2707b45ecd3dbd40344d384a3c9a0c280e3942c Mon Sep 17 00:00:00 2001 From: liolok Date: Thu, 29 Aug 2019 19:11:54 +0800 Subject: [PATCH] update readme --- README.md | 53 +++++++++++++++++++++++++---------------------------- 1 file changed, 25 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 58e8772..1fbc6f1 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,31 @@ -# hexo-asset-link +# hexo-asset-link [![NPM version](https://badge.fury.io/js/hexo-asset-link.svg)](https://www.npmjs.com/package/hexo-asset-link) Convert base-relative asset links to root-relative ones, so that user can insert assets like images in markdown way. -[![NPM version](https://badge.fury.io/js/hexo-asset-link.svg)](https://www.npmjs.com/package/hexo-asset-link) - ## Install +In Hexo blog instance directory: + ```shell -$ npm i --save hexo-asset-link +$ npm i -s hexo-asset-link ``` ## Config -This plugin only works when [`Asset Folders`](https://hexo.io/docs/asset-folders) feature enabled in `_config.yml`: +This plugin works only when [`Post Asset Folders`](https://hexo.io/docs/asset-folders#Post-Asset-Folder) feature enabled in `_config.yml`: ```yml post_asset_folder: true ``` -## Write +## Usage For example, if you have these files in `source/_post/`: ``` -+-- _posts ++-- _posts/ | +-- 2019-02-14-Test-Post.md -| +-- 2019-02-14-Test-Post +| +-- 2019-02-14-Test-Post/ | +-- Test-Image.png | +-- Test-Other-File.pdf ``` @@ -46,37 +46,34 @@ Then in `2019-02-14-Test-Post.md`: [Text](2019-02-14-Test-Post/Test-Other-File.pdf) ``` -### Unrecommended Way - -This way is quite dirty, and will **not** work when there exists **any subdirectory**, e.g. `2019-02-14-Test-Post/Sub/Directory/Test-Image.png`. - -```markdown -![Alt Text](Test-Image.png "Title Text") -[Text](Test-Other-File.pdf) -``` +After this we'll get the right asset path result in: -Writing in this way makes no sense to markdown, asset files will **not** be found correctly. +- Blog home page of `hexo server` preview; +- Blog post page of `hexo server` preview; +- Blog home page of online website; +- Blog post page of online website; +- Markdown preview of editors like VS Code. -## FAQ +Now shall we just have fun writing! -### Why not hexo-asset-image? +## Comparision to `hexo-asset-image` -1. It has been unmaintained for two years; -2. It has security vulnerability due to out-dated dependency; -3. It seems incompatible with plugins like hexo-abbrlink. +At first when I wrote this plugin, the older `hexo-asset-image` has been inactive for quite a long while. -### Then is hexo-asset-link better? + Up to now, there is still a lot of issues remaining open. And I smell of hardcode (no offence), which may lead to more and more problems. -1. My code is really better (^_^); -2. If this plugin meets your requirement, just install and have fun writing; -3. A detailed issue is always welcomed if any trouble. +In the end, all of these trouble comes from upstream Hexo, I'll keep an eye on it. This plugin's maintenance will last until I deprecate Hexo, which would a long time later, no need to worry. ## Reference -Coding style and `cheerio` usage: [hexo/external_link.js at 3.8.0 · hexojs/hexo](https://github.com/hexojs/hexo/blob/3.8.0/lib/plugins/filter/after_post_render/external_link.js) +Coding style and `cheerio` usage: [hexo/external_link.js at 3.9.0 · hexojs/hexo](https://github.com/hexojs/hexo/blob/3.9.0/lib/plugins/filter/after_post_render/external_link.js) ### API [Filter | Hexo](https://hexo.io/api/filter) -[URL | Node.js v10.15.1 Documentation](https://nodejs.org/docs/latest-v10.x/api/url.html) +[`url.parse`](https://nodejs.org/docs/latest-v12.x/api/url.html#url_url_parse_urlstring_parsequerystring_slashesdenotehost "URL | Node.js v12.9.1 Documentation") + +[`url.pathname`](https://nodejs.org/docs/latest-v12.x/api/url.html#url_url_pathname "URL | Node.js v12.9.1 Documentation") + +[`url.protocol`](https://nodejs.org/docs/latest-v12.x/api/url.html#url_url_protocol "URL | Node.js v12.9.1 Documentation")