Skip to content
This repository was archived by the owner on Nov 28, 2025. It is now read-only.
This repository was archived by the owner on Nov 28, 2025. It is now read-only.

mkdocs with mkdocs-bibtex not rendering citation stlye IEEE correctly #332

Open
Open
mkdocs with mkdocs-bibtex not rendering citation stlye IEEE correctly#332

Description

@engineertrooper
engineertrooper
opened on Jul 7, 2025

Hi, after some hours of trouble shotting and reading the docs...

General

Problem Description: mkdocs-bibtex is not replaceing the old footnotes citation with the new IEEE citation via .csl .

Setup is inside a pip venv and install via requirements.txt:

mkdocs==1.6.1
mkdocs-material==9.6.15
pandoc==2.4
pypandoc==1.15
mkdocs-bibtex==4.4.0
setuptools==80.9.0

mkdocs.yml:

site_name: Docs XYZ
site_url: https://docs.xyz.com

plugins:
  - search
  - bibtex:
      bib_file: "docs/assets/refs/refs.bib"
      csl_file: "docs/assets/refs/ieee-with-url_2024-01-11.csl"
      csl_file_encoding: "utf-8"

markdown_extensions:
  - footnotes
  - pymdownx.caret

extra_css:
  - assets/css/style.css

nav:
  - SectionTest1:
    - Test1: content/test1neu.md
  • running on localhost: 127.0.0.1
  • running mkdocs in stric mode: mkdocs serve --strict -v
  • testing with minimal data and setup

Debug Log

Short description what is going on/wrong according to debug log (only refering to bibtex stuff)

  • pandoc is found
  • citationkey [@texbook]
  • pandoc output of correct citation format as \[1\] means recognition of citation style works
  • but inside the markdown output the footnote format is given as [^texbook] -> From my understanding something went wrong at this point or before.
  • Documentation built succsessfuly
  • Citation style is superscript footnotes inside webbrowser

Any Idea what went wrong? Thanks for helping out!

The beautiful full log:

DEBUG   -  Loading configuration file: /home/engi/Desktop/docs.xyz.com/docsXYZ/mkdocs.yml
DEBUG   -  Loaded theme configuration for 'mkdocs' from '/home/engi/Desktop/docs.xyz.com/venv/lib/python3.12/site-packages/mkdocs/themes/mkdocs/mkdocs_theme.yml': {'static_templates': ['404.html'],
           'locale': 'en', 'include_search_page': False, 'search_index_only': False, 'highlightjs': True, 'hljs_languages': [], 'hljs_style': 'github', 'hljs_style_dark': 'github-dark', 'navigation_depth': 2,
           'nav_style': 'primary', 'color_mode': 'light', 'user_color_mode_toggle': False, 'analytics': {'gtag': None}, 'shortcuts': {'help': 191, 'next': 78, 'previous': 80, 'search': 83}}
INFO    -  UserWarning: pkg_resources is deprecated as an API. See https://setuptools.pypa.io/en/latest/pkg_resources.html. The pkg_resources package is slated for removal as early as 2025-11-30. Refrain from
           using this package or pin to Setuptools<81.
             File "/home/engi/Desktop/docs.xyz.com/venv/lib/python3.12/site-packages/pybtex/plugin/__init__.py", line 26, in <module>
               import pkg_resources
             File "/home/engi/Desktop/docs.xyz.com/venv/lib/python3.12/site-packages/pkg_resources/__init__.py", line 98, in <module>
               warnings.warn(
DEBUG   -  Config value 'config_file_path' = '/home/engi/Desktop/docs.xyz.com/docsXYZ/mkdocs.yml'
DEBUG   -  Config value 'site_name' = 'Docs XYZ'
DEBUG   -  Config value 'nav' = [{'SectionTest1': [{'Test1': 'content/test1neu.md'}]}]
DEBUG   -  Config value 'pages' = None
DEBUG   -  Config value 'exclude_docs' = None
DEBUG   -  Config value 'draft_docs' = None
DEBUG   -  Config value 'not_in_nav' = None
DEBUG   -  Config value 'site_url' = 'https://docs.xyz.com/'
DEBUG   -  Config value 'site_description' = None
DEBUG   -  Config value 'site_author' = None
DEBUG   -  Config value 'theme' = Theme(name='mkdocs', dirs=['/home/engi/Desktop/docs.xyz.com/venv/lib/python3.12/site-packages/mkdocs/themes/mkdocs',
           '/home/engi/Desktop/docs.xyz.com/venv/lib/python3.12/site-packages/mkdocs/templates'], static_templates={'sitemap.xml', '404.html'}, name='mkdocs', locale=Locale('en'),
           include_search_page=False, search_index_only=False, highlightjs=True, hljs_languages=[], hljs_style='github', hljs_style_dark='github-dark', navigation_depth=2, nav_style='primary', color_mode='light',
           user_color_mode_toggle=False, analytics={'gtag': None}, shortcuts={'help': 191, 'next': 78, 'previous': 80, 'search': 83})
DEBUG   -  Config value 'docs_dir' = '/home/engi/Desktop/docs.xyz.com/docsXYZ/docs'
DEBUG   -  Config value 'site_dir' = '/tmp/mkdocs_zwv0s7th'
DEBUG   -  Config value 'copyright' = None
DEBUG   -  Config value 'google_analytics' = None
DEBUG   -  Config value 'dev_addr' = _IpAddressValue(host='127.0.0.1', port=8000)
DEBUG   -  Config value 'use_directory_urls' = True
DEBUG   -  Config value 'repo_url' = None
DEBUG   -  Config value 'repo_name' = None
DEBUG   -  Config value 'edit_uri_template' = None
DEBUG   -  Config value 'edit_uri' = None
DEBUG   -  Config value 'extra_css' = ['assets/css/style.css']
DEBUG   -  Config value 'extra_javascript' = []
DEBUG   -  Config value 'extra_templates' = []
DEBUG   -  Config value 'markdown_extensions' = ['toc', 'tables', 'fenced_code', 'footnotes', 'pymdownx.caret']
DEBUG   -  Config value 'mdx_configs' = {}
DEBUG   -  Config value 'strict' = True
DEBUG   -  Config value 'remote_branch' = 'gh-pages'
DEBUG   -  Config value 'remote_name' = 'origin'
DEBUG   -  Config value 'extra' = {}
DEBUG   -  Config value 'plugins' = {'search': <mkdocs.contrib.search.SearchPlugin object at 0x74dad3f9ffb0>, 'bibtex': <mkdocs_bibtex.plugin.BibTexPlugin object at 0x74dad4cbdfa0>}
DEBUG   -  Config value 'hooks' = {}
DEBUG   -  Config value 'watch' = []
DEBUG   -  Config value 'validation' = {'nav': {'omitted_files': 20, 'not_found': 30, 'absolute_links': 20}, 'links': {'not_found': 30, 'absolute_links': 20, 'unrecognized_links': 20, 'anchors': 20}}
DEBUG   -  Running `startup` event from plugin 'bibtex'
INFO    -  Building documentation...
DEBUG   -  Running `config` event from plugin 'search'
DEBUG   -  Running `config` event from plugin 'bibtex'
INFO    -  Loading data from bib files: ['/home/engi/Desktop/docs.xyz.com/docsXYZ/docs/assets/refs/refs.bib']
DEBUG   -  Parsing bibtex file /home/engi/Desktop/docs.xyz.com/docsXYZ/docs/assets/refs/refs.bib
DEBUG   -  Running `pre_build` event from plugin 'search'
INFO    -  Cleaning site directory
DEBUG   -  Looking for translations for locale 'en'
DEBUG   -  No translations found here: '/home/engi/Desktop/docs.xyz.com/venv/lib/python3.12/site-packages/mkdocs/contrib/search/templates/locales'
DEBUG   -  No translations found here: '/home/engi/Desktop/docs.xyz.com/venv/lib/python3.12/site-packages/mkdocs/templates/locales'
DEBUG   -  No translations found here: '/home/engi/Desktop/docs.xyz.com/venv/lib/python3.12/site-packages/mkdocs/themes/mkdocs/locales'
INFO    -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
             - index.md
DEBUG   -  Reading markdown pages.
DEBUG   -  Reading: index.md
DEBUG   -  Running `page_markdown` event from plugin 'bibtex'
DEBUG   -  Converting with pandoc:
DEBUG   -   ---
           link-citations: false
           ---

           0. [@texbook]

           # References

INFO    -  DeprecationWarning: open_text is deprecated. Use files() instead. Refer to https://importlib-resources.readthedocs.io/en/latest/using.html#migrating-from-legacy for migration advice.
             File "/home/engi/Desktop/docs.xyz.com/venv/lib/python3.12/site-packages/latexcodec/codec.py", line 102, in load_unicode_latex_table
               with pkg_resources.open_text('latexcodec', 'table.txt') as datafile:
             File "/usr/lib/python3.12/importlib/resources/_legacy.py", line 18, in wrapper
               warnings.warn(
DEBUG   -  Pandoc output:
DEBUG   -  0.  \[1\]

           # References {#references .unnumbered}

           :::: {#refs .references .csl-bib-body entry-spacing="0"}
           ::: {#ref-texbook .csl-entry}
           [\[1\] ]{.csl-left-margin}[D. E. Knuth, *The TeX book*. Addison-Wesley
           Professional, 1986.]{.csl-right-inline}
           :::
           ::::
DEBUG   -  Inline cache: {'[@texbook]': '\\[1\\]'}
DEBUG   -  Reference cache: {'texbook': 'D. E. Knuth, *The TeX book*. Addison-Wesley Professional, 1986.'}
DEBUG   -  Markdown:
           # Docs XYZ - Startseite

           1234567890

           abcdefghijklmnopqrstuvwxyz

           ABCDEFGHIJKLMNOPQRSTUVWXYZ

           Literaturverweisversuch [^texbook]

           Literaturverweisversuch 2



           Non existing citation
           This should fail on --strict mode



           Citation with affix

           Citation with multiple affixes

           Bibliography
           [^texbook]: D. E. Knuth, *The TeX book*. Addison-Wesley Professional, 1986.


           [^texbook]: D. E. Knuth, *The TeX book*. Addison-Wesley Professional, 1986.
DEBUG   -  Reading: content/test1neu.md
DEBUG   -  Running `page_markdown` event from plugin 'bibtex'
DEBUG   -  Markdown:
           # Test 1 Raleway Font

           1234567890

           abcdefghijklmnopqrstuvwxyz

           ABCDEFGHIJKLMNOPQRSTUVWXYZ

           Literaturverweisversuch [^texbook]

           Literaturverweisversuch 2



           Non existing citation
           This should fail on --strict mode



           Citation with affix

           Citation with multiple affixes

           Bibliography
           [^texbook]: D. E. Knuth, *The TeX book*. Addison-Wesley Professional, 1986.


           [^texbook]: D. E. Knuth, *The TeX book*. Addison-Wesley Professional, 1986.
DEBUG   -  Copying static assets.
DEBUG   -  Copying media file: 'assets/css/style.css'
DEBUG   -  Copying media file: 'assets/font/ralewayLatinRegular100to900.woff2'
DEBUG   -  Copying media file: 'assets/refs/ieee-with-url_2024-01-11.csl'
DEBUG   -  Copying media file: 'assets/refs/refs.bib'
DEBUG   -  Copying media file: 'css/base.css'
DEBUG   -  Copying media file: 'css/bootstrap.min.css'
DEBUG   -  Copying media file: 'css/bootstrap.min.css.map'
DEBUG   -  Copying media file: 'css/brands.min.css'
DEBUG   -  Copying media file: 'css/fontawesome.min.css'
DEBUG   -  Copying media file: 'css/solid.min.css'
DEBUG   -  Copying media file: 'css/v4-font-face.min.css'
DEBUG   -  Copying media file: 'img/favicon.ico'
DEBUG   -  Copying media file: 'img/grid.png'
DEBUG   -  Copying media file: 'js/base.js'
DEBUG   -  Copying media file: 'js/bootstrap.bundle.min.js'
DEBUG   -  Copying media file: 'js/bootstrap.bundle.min.js.map'
DEBUG   -  Copying media file: 'js/darkmode.js'
DEBUG   -  Copying media file: 'search/lunr.js'
DEBUG   -  Copying media file: 'search/main.js'
DEBUG   -  Copying media file: 'search/worker.js'
DEBUG   -  Copying media file: 'webfonts/fa-brands-400.ttf'
DEBUG   -  Copying media file: 'webfonts/fa-brands-400.woff2'
DEBUG   -  Copying media file: 'webfonts/fa-regular-400.ttf'
DEBUG   -  Copying media file: 'webfonts/fa-regular-400.woff2'
DEBUG   -  Copying media file: 'webfonts/fa-solid-900.ttf'
DEBUG   -  Copying media file: 'webfonts/fa-solid-900.woff2'
DEBUG   -  Copying media file: 'webfonts/fa-v4compatibility.ttf'
DEBUG   -  Copying media file: 'webfonts/fa-v4compatibility.woff2'
DEBUG   -  Building theme template: sitemap.xml
DEBUG   -  Gzipping template: sitemap.xml
DEBUG   -  Building theme template: 404.html
DEBUG   -  Building markdown pages.
DEBUG   -  Building page index.md
DEBUG   -  Running `page_context` event from plugin 'search'
DEBUG   -  Building page content/test1neu.md
DEBUG   -  Running `page_context` event from plugin 'search'
DEBUG   -  Running `post_build` event from plugin 'search'
INFO    -  Documentation built in 0.40 seconds
DEBUG   -  [11:32:19] Watching '/home/engi/Desktop/docs.xyz.com/docsXYZ/docs'
DEBUG   -  [11:32:19] Watching '/home/engi/Desktop/docs.xyz.com/docsXYZ/mkdocs.yml'
INFO    -  [11:32:19] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [11:32:19] Serving on http://127.0.0.1:8000/
DEBUG   -  [11:32:20] "GET /livereload/5439286/5440261 HTTP/1.1" code 200
DEBUG   -  [11:32:20] "GET / HTTP/1.1" code 200
DEBUG   -  [11:32:20] "GET /css/brands.min.css HTTP/1.1" code 200
DEBUG   -  [11:32:20] "GET /css/bootstrap.min.css HTTP/1.1" code 200
DEBUG   -  [11:32:20] "GET /css/fontawesome.min.css HTTP/1.1" code 200
DEBUG   -  [11:32:20] "GET /css/solid.min.css HTTP/1.1" code 200
DEBUG   -  [11:32:20] "GET /css/v4-font-face.min.css HTTP/1.1" code 200
DEBUG   -  [11:32:20] "GET /css/base.css HTTP/1.1" code 200
DEBUG   -  [11:32:20] "GET /assets/css/style.css HTTP/1.1" code 200
DEBUG   -  [11:32:20] "GET /js/bootstrap.bundle.min.js HTTP/1.1" code 200
DEBUG   -  [11:32:20] "GET /js/base.js HTTP/1.1" code 200
DEBUG   -  [11:32:20] "GET /search/main.js HTTP/1.1" code 200
DEBUG   -  [11:32:20] "GET /img/grid.png HTTP/1.1" code 200
DEBUG   -  [11:32:20] "GET /search/worker.js HTTP/1.1" code 200
INFO    -  [11:32:20] Browser connected: http://127.0.0.1:8000/
DEBUG   -  [11:32:20] "GET /search/search_index.json HTTP/1.1" code 200
DEBUG   -  [11:32:20] "GET /search/lunr.js HTTP/1.1" code 200

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions