Manage your academic publications page with Pelican and pybtex (BibTeX)
Project description
pybtex: A Plugin for Pelican
Organize your scientific publications with pybtex (BibTeX) in Pelican.
Installation
This plugin can be installed via:
pip install pelican-pybtex
This a "namespace plugin" for Pelican. After installation, it should be automatically
detected. It is enabled by default if PLUGINS
is not set on your configuration. In
case that variable is set, add pybtex
to the list of plugins to load. For more
information, check How to Use
Plugins
documentation.
Usage
This plugin reads a user-specified pybtex supported
file and populates the
global Jinja2 context used by Pelican with a publications
variable. The publications
variable is a list of dictionaries itself, each containing the following fields,
corresponding to individual entries in the provided compatible files:
label
: The formatted label (depends on the used style, but usually something like3
,Ein05
, orEinstein, 1905
).key
: The pybtex (BibTeX) database keyyear
: The year of the entryhtml
: An HTML-formatted version of the entrybibtex
: A BibTeX-formatted version of the entry, wrapped in a pygments HTML-formatted version. The pygments output respects the settings forPYGMENTS_RST_OPTIONS
in Pelican.
Use the following Pelican configuration key to list sources to be parsed and populate
the publications
context:
# any pybtex supported input format is accepted
PYBTEX_SOURCES = ["content/publications.bib"]
If files indicated on that list are present and readable, they will be loaded. Errors are reported, but ignored during generation. Check Pelican logs for details while building your site.
Note that relative paths are considered with respect to the location of the setting of
PATH
in pelicanconf.py
(typically the content
directory). If PATH
itself is
relative, it is considered relative to the location of pelicanconf.py
itself.
Extra fields
If you also set PYBTEX_ADD_ENTRY_FIELDS
, then if any other field listed in this
setting will also be included verbatim in the dictionary of each entry. This feature
can be used, e.g., to include more URLs in a work, and then display those using a
custom template as explained later.
PYBTEX_ADD_ENTRY_FIELDS = ["url", "pdf", "slides", "poster"]
Formatting style
By default, PYBTEX_FORMAT_STYLE
is set to plain
. You may further customize this
setting to one of the biobliography formatting styles supported by pybtex (currently
"plain", "alpha", "unsrt", and "unsrtalpha"). You may check the formatting style of
these BibTeX styles on this
reference. We
currently do not support custom bibliographic styles. Create an issue if you would like
to work on this.
Publications page
This plugin provides a default
publications.html
template
that will render all publications correctly loaded from PYBTEX_SOURCES
, ordered by
year, in reverse chronological order, and without BibTeX-style labels. Note that, if
there are no valid entries on PYBTEX_SOURCES
, then a publications.html
page is not
generated.
You may also want to override the default template, or parts of it with your own
modifications. To do so, create your own publications.html
template, then use
THEME_TEMPLATES_OVERRIDES
and THEME_STATIC_PATHS
to add search paths for template
resolution. For example, to add a short introductory text, we could override the
before_content
block on the default template like so:
-
Create a file called
templates/publications.html
on your site sources, with the following (example) contents:{% extends "!pybtex/publications.html" %} {% block before_content %} <p id="before-para">This will appear before the publication lists. One could use this to display their h-index, provide links to Google Scholar or ORCid.</p> {% endblock %} <!-- set PYBTEX_ADD_ENTRY_FIELDS = ["url", "pdf", "slides", "poster"] --> <!-- then, use it in your template override like so: --> {% block content_pybtex %} <div id="pybtex"> {% for item in publications %} <details id="{{ item.key }}"> <summary>[{{ item.label }}] {{ item.html }}</summary> <ul> {% for k in ("url", "pdf", "slides", "poster") %} {% if k in item %}<li>{{ k }}: {{ item[k] }}</li>{% endif %} {% endfor %} </ul> </details> {% endfor %} </div> {% endblock %}
-
Optionally, create a directory called
static
in which you may pour static files that control the look of your inserted content. -
In
pelicanconf.py
, set:THEME_TEMPLATES_OVERRIDES = ["templates"] # STATIC_PATHS = ["static"] ## if you also have static files to be copied # PUBLICATIONS_SAVE_AS = "publications/index.html" ## to change the default output file # PUBLICATIONS_URL = "publications/" ## to change the default URL for publications
Local bibliography in articles and pages
You may use markers such as [@bibkey]
or [@@bibkey]
on your articles and pages in
restructuredtext or markdown formats, to refer to bibliography entries from the
PYBTEX_SOURCES
. This process is similar to using BibTeX database entries in your
LaTeX sources by using the \cite{bibkey}
command. In this case, this plugin will
replace these citations with links to a bibliography database injected at the end of
the article or post.
The global PYBTEX_FORMAT_STYLE
is respected while formatting bibliographies. You may
override the style for the current article or page using the metadata entry
pybtex_format_style
. The same mechanism is available for PYBTEX_ADD_ENTRY_FIELDS
,
which can be locally overriden by pybtex_add_entry_fields
metadata entry.
You may also add further enrich article or page metadata defining a specific
pybtex_sources
. In such a case, these files will be loaded respecting the same rules
as for PYBTEX_SOURCES
. Specifically, relative paths are first searched at the location
of the article or page, and then default on using the PATH
setting in
pelicanconf.py
. Article and page bibliography markers will then be resolved by first
looking at entries in the local pybtex_sources
, and then on the global
PYBTEX_SOURCES
entry in pelicanconf.py
.
Be aware that in case repeated citation keys are found across all bibliography databases, the last occurence is used while resolving local bibliography for articles an pages.
Finally, local bibliography formatting is controlled by the default
bibliography.html
template
that is shipped with this package. This templates defines the contents of the
injected bibliography section on articles and pages. You may override this template in
a similar way to what was explained above for the global publications.html
template,
by setting the THEME_TEMPLATES_OVERRIDES
Pelican variable.
Contributing
Contributions are welcome and appreciated. Every little bit helps. You can contribute by improving the documentation, adding missing features, and fixing bugs. You can also help out by reviewing and commenting on existing issues.
To start contributing to this plugin, review the Contributing to Pelican documentation, beginning with the Contributing Code section.
License
This project was inspired by the original BibTeX plugin, developed by Vlad Niculae, and pelican-cite plugin, by Arvid Norlander. This project and further modifications are licensed under the MIT license.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file pelican_pybtex-1.0.1.tar.gz
.
File metadata
- Download URL: pelican_pybtex-1.0.1.tar.gz
- Upload date:
- Size: 14.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/5.1.1 CPython/3.12.7
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | c58bb2b33d6957c6e02b05d8c3bf7b13728d153b6f36bd23ee37a6033c8b161e |
|
MD5 | fcaad8ac55a5709eb2d6b0a74b20f786 |
|
BLAKE2b-256 | 6fde5b8f16c768c8ceb0525680034a4f58b3aeb6ceee50780af6f7373842e03b |
Provenance
The following attestation bundles were made for pelican_pybtex-1.0.1.tar.gz
:
Publisher:
main.yml
on anjos/pelican-pybtex
-
Statement type:
https://in-toto.io/Statement/v1
- Predicate type:
https://docs.pypi.org/attestations/publish/v1
- Subject name:
pelican_pybtex-1.0.1.tar.gz
- Subject digest:
c58bb2b33d6957c6e02b05d8c3bf7b13728d153b6f36bd23ee37a6033c8b161e
- Sigstore transparency entry: 147606354
- Sigstore integration time:
- Predicate type:
File details
Details for the file pelican_pybtex-1.0.1-py3-none-any.whl
.
File metadata
- Download URL: pelican_pybtex-1.0.1-py3-none-any.whl
- Upload date:
- Size: 15.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/5.1.1 CPython/3.12.7
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 39185acaae6804b07a71cd2e56e69587c6013a0bbb3caaf01bd309ce89f86855 |
|
MD5 | 614380b4ebac58025b0ee74e6aded373 |
|
BLAKE2b-256 | 7e8f15eb48766659016fb0670d6bb25a8ac899748426bf43e457dc7b1d1329e9 |
Provenance
The following attestation bundles were made for pelican_pybtex-1.0.1-py3-none-any.whl
:
Publisher:
main.yml
on anjos/pelican-pybtex
-
Statement type:
https://in-toto.io/Statement/v1
- Predicate type:
https://docs.pypi.org/attestations/publish/v1
- Subject name:
pelican_pybtex-1.0.1-py3-none-any.whl
- Subject digest:
39185acaae6804b07a71cd2e56e69587c6013a0bbb3caaf01bd309ce89f86855
- Sigstore transparency entry: 147606358
- Sigstore integration time:
- Predicate type: