hexo-next-publist
v2.2.1
Published
Filterable publication list
Downloads
74
Readme
hexo-next-publist
Show a list of publications anywhere in the markdown post. There is also a customizable panel to filter the results.
Demo
The research page in my my blog are generated by this plugin. Please go and take a look. The source code is available on Github.
Installation
npm i -S hexo-next-publist
This will install hexo-next-publist
and add it as a dependency in your package.json
.
NOTE: There are also several peer dependencies you may need to install. Follow the instruction printed when running the previous command to install the missing ones.
Usage
There are three pieces to be defined:
- The actual tag, which also defines the set of conferences
- The bib source file, which defines the list of publications
- The publication assets directory, which contains the (optional) downloadable files
Tag
To create a publist, use the publist
tag in the post markdown source.
The only argument in the opening tag is the name of bib file.
The content between the tags defines any conferences the bibtex file will refer. More examples.
{% publist mypubs %}
version: 2
pub_dir: assets/pub
highlight_authors: []
# extra filters to show, they will filter on the item using given path
extra_filters: []
venues:
MLSys:
category: Conferences
occurrences:
# key is used in publist_confkey, must be unique across conferences
- key: MLSys'20
# conference full name
name: The 3rd Conference on Machine Learning and Systems
# conference date for sorting (optional)
date: 2020-03-02
# conference website (optional)
url: https://mlsys.org/Conferences/2020
# conference acceptance rate (optional)
acceptance: 19.2%
{% endpublist %}
Bib source file
Bib source files are treated as data sources, so they need to be placed in the source/_data
folder. You can then refer to them via the file name when using the publist
tag.
You'll need to add some publist specific fields in the bib file to control the handling, and they will be striped out when shown in the UI.
@inproceedings{yu20mlsys,
title = {{Salus}: Find-grained {GPU} Sharing primitives for Deep Learning Applications},
author = {Yu, Peifeng and Chowdhury, Mosharaf},
booktitle = {Proceedings of the 3rd Conference on Machine Learning and Systems},
year = {2020},
publist_confkey = {MLSys'20},
publist_link = {paper || yu20mlsys.pdf},
publist_link = {talk || yu20mlsys-talk.pptx},
publist_link = {poster || yu20mlsys-poster.pdf},
publist_badge = {Artifacts Available},
publist_badge = {Artifacts Evaluated Functional},
publist_badge = {Artifacts Replicated},
publist_abstract = {
This is an abstract.
The common spaces before each line will be stripped.
}
publist_tag = {tagA},
publist_tag = {tagB},
publist_topic = {Deep Learning},
publist_topic = {GPU},
}
Publication Assets Directory
Set by pub_dir
in the instance options.
The publist_link
field in the bib source refers to files in this directory.
One subfolder following the entry key per entry, containing slides, pdf, or any additional files.
If the link part starts with /
, then it is intepreted as an absolute path.
If the link starts with http
, then it is used as is.
Configuration
Instance options between the tags
The full spec of this content is defined as a JSON schema.
{% publist mypubs %}
# the version of the config
version: 2
pub_dir: assets/pub
# whether to show entries with date in the future
show_unpublished: false
highlight_authors: []
# extra filters to show, they will filter on the item using given path
extra_filters:
- name: Topic
path: meta.topic
- name: Badge
path: badges
venues:
MLSys:
category: Conferences
occurrences:
# key is used in publist_confkey, must be unique across conferences
- key: MLSys'20
# conference full name
name: The 3rd Conference on Machine Learning and Systems
# conference date for sorting (optional. If this is missing, the year and month in bib entry will be used)
date: 2020-03-02
# conference website (optional. Will use an url from the parent level if there's one)
url: https://mlsys.org/Conferences/2020
# conference acceptance rate (optional)
acceptance: 19.2%
arXiv:
category: Technical Reports
# url can also be set on the whole (optional)
url: https://arxiv.org
occurrences:
- key: arXiv-all
# instead of using key to match confkey in literal,
# use the regex given here.
# the key still have to be unique globally
matches: arXiv:(.*)
# then the name can refer to capture groups
name: 'arXiv$1'
# link, optional, makes the name a url when shown in the UI, can contain capture groups
link: 'https://arxiv.org/$1'
# url, optional, can contain capture groups
url: 'https://arxiv.org/$1'
{% endpublist %}
Extra fields in bib source
The following extra fields specific to publist control the display of an entry. They will be stripped away from the bib source shown in the UI.
publist_confkey
: optional. Link this entry to a conference occurencepublist_link
: optional, can appear multiple times. Show a hyperlink button in the result. The content is of the formattitle || url
. If relative, it will be resolved from the basepub_dir/citekey
.publist_badge
: optional, can appear multiple times. Show a badge under the title.publist_abstract
: optional. Markdown rendered abstract, with support for latex math (If you have math plugin enabled).abstract
: optional. Verbatim abstract. Note that this will NOT be stripped. When both this field andpublist_abstract
are present, the latter is used.publist_xxx
: optional, can appear multiple times. Metadata fields. Can be used inextra_filters
aspath: meta_xxx
.
Global options in _config.yml
publist:
# where should the publist js and css files be served
# publist will generate its own js and css file under this prefix
assets_prefix: assets/publist
# entries within the last `new_months` will be marked new
new_months: 3
# if strict mode is enabled, any bibtex parsing errors will be fatal
strict: false
# whether to embed css file directly in html, may help FUOC when using pjax
embed_css: true
Internals
_config.yml
contains main options under the keypublist
.src/bib-renderer.js
reads.bib
files undersource/_data
in the user's repo. The result will be available as data in the data model.src/widget
implements a hexo box, processing all assets underwidget
using webpack, and serving them.src/publist.js
is the actual tag plugin, which reads bib data from the data model and renders the html.