is it possible to use bibtex entries within README's written with reStructuredText (*.rst)

[mccroweyclinton-EPA]

Select Topic Area

Question

Body

I would like to add a bibliography to my README.rst file using bibtext (e.g. sphinxcontrib-bibtex or something similar). Bibtex references seems to work with README files using markdown, so should I assume that they work with reStructuredText (*.rst) as well? If so, is there a guide on how to include bibtext references within a github README.rst file.

Also note that I am aware that I can compile the reStructuredText file to html using sphinx, or convert the restructured text file to markdown using pandoc. If I am going to do all of that I might as well just re-write the README in markdown. I just want to know if bibtex references are supported in pure reStructuredText?

[mccroweyclinton-EPA]

I will interpret the lack of responses as a sign that using bibtex entries in reStruturedText is currently not supported on github README pages.

[KiranJITdesign]

Hi @mccroweyclinton-EPA,

GitHub can render README.rst, but it does not run Sphinx extensions such as sphinxcontrib-bibtex.

There is an important distinction:

• Native reStructuredText: Supports manually defined citations and references using citation syntax such as [Smith2024]_.
• BibTeX integration: Requires an extension such as sphinxcontrib-bibtex to read .bib files and generate citations and bibliographies.

Since GitHub renders the README directly rather than building it through a configured Sphinx project, automatic BibTeX processing is not supported.

If you want to keep a pure README.rst, you can define the references manually using reStructuredText's built-in citation syntax.

References:

• [reStructuredText citation syntax](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#citations)
• [sphinxcontrib-bibtex](https://pypi.org/project/sphinxcontrib-bibtex/)