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:

1. The actual tag, which also defines the set of conferences
2. The bib source file, which defines the list of publications
3. 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.

Example bib file

@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.

Example config with comments

{% 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 occurence
• publist_link: optional, can appear multiple times. Show a hyperlink button in the result. The content is of the format title || url. If relative, it will be resolved from the base pub_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 and publist_abstract are present, the latter is used.
• publist_xxx: optional, can appear multiple times. Metadata fields. Can be used in extra_filters as path: 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 key publist.
• src/bib-renderer.js reads .bib files under source/_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 under widget 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.