From fcd567b8b2f3fd59e86d85e9d0648cb9953107a8 Mon Sep 17 00:00:00 2001 From: bits-bytes-nn Date: Tue, 17 Nov 2026 22:08:54 +0900 Subject: [PATCH] feat: print citation counts at build time Paper posts showed their Semantic Scholar citation count only after each reader's browser asked the keyless API, which answered 429 to 21 of 34 papers in a test. CI now fetches every count in one batch request before the build and the layout prints it, so it shows on a first view and without JavaScript. - script/fetch-citations.rb: one batch POST, retried with backoff within a deadline; on failure keeps the counts the live site published last (/citations.json); a refused SEMANTIC_SCHOLAR_API_KEY fails the run. - _plugins/citations.rb: the Semantic Scholar id per post and its count. - _data/citation_ids.yml: the record for a DOI whose arXiv id finds none or a zero-count duplicate (DeepSeek-V3); keyed by DOI, so a regenerated post keeps it. - js/citations.js: shows the newer of the build's and the browser's count and asks only when both are a day old. - jekyll.yml: the fetch step and a daily run to refresh the counts. - check-plugin-output.rb: the field is on each paper page as fetched. --- .github/workflows/jekyll.yml | 17 +++++ .gitignore | 3 + _data/citation_ids.yml | 9 +++ _includes/footer.html | 2 +- _layouts/post.html | 16 +++-- _plugins/citations.rb | 94 +++++++++++++++++++++++++ citations.json | 9 +++ docs/architecture.md | 43 +++++++++--- docs/operations.md | 25 ++++++- docs/writing.md | 2 +- js/citations.js | 92 ++++++++++++++++--------- script/check-plugin-output.rb | 15 ++++ script/fetch-citations.rb | 125 ++++++++++++++++++++++++++++++++++ script/lint-posts.rb | 4 +- test/test_citations.rb | 93 +++++++++++++++++++++++++ test/test_fetch_citations.rb | 112 ++++++++++++++++++++++++++++++ 16 files changed, 609 insertions(+), 52 deletions(-) create mode 100644 _data/citation_ids.yml create mode 100644 _plugins/citations.rb create mode 100644 citations.json create mode 100644 script/fetch-citations.rb create mode 100644 test/test_citations.rb create mode 100644 test/test_fetch_citations.rb diff --git a/.github/workflows/jekyll.yml b/.github/workflows/jekyll.yml index b4aacc7..49c0e2c 100644 --- a/.github/workflows/jekyll.yml +++ b/.github/workflows/jekyll.yml @@ -9,6 +9,10 @@ on: # reached main and merely failed to deploy, leaving main red. pull_request: branches: [ "main" ] + # Daily, so the citation counts printed into the paper posts are at most a + # day old (script/fetch-citations.rb); the browser refreshes older ones. + schedule: + - cron: "41 20 * * *" # 20:41 UTC, 05:41 KST workflow_dispatch: # Read-only by default. Only `deploy` gets the Pages and OIDC grants, so a PR @@ -56,6 +60,19 @@ jobs: - name: Setup Pages id: pages uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0 + - name: Fetch citation counts + # One batch request to Semantic Scholar, written to _data/citations.json + # for the build to print. When it fails, the counts the live site + # published last are kept; with neither, it warns and the site builds + # without counts, which the browser then asks for. Run on PRs too, so + # the gates below check the pages as they will be published. It fails + # only on a refused SEMANTIC_SCHOLAR_API_KEY; its own timeouts and + # retries end it in about six minutes at worst. + run: bundle exec ruby script/fetch-citations.rb + timeout-minutes: 8 + env: + SEMANTIC_SCHOLAR_API_KEY: ${{ secrets.SEMANTIC_SCHOLAR_API_KEY }} + BASE_PATH: ${{ steps.pages.outputs.base_path }} - name: Build with Jekyll run: bundle exec jekyll build --baseurl "$BASE_PATH" --strict-front-matter env: diff --git a/.gitignore b/.gitignore index 0ec5881..770a198 100644 --- a/.gitignore +++ b/.gitignore @@ -45,3 +45,6 @@ _posts_bak/ # Editor and toolchain leftovers node_modules/ .vscode/ + +# Citation counts, fetched before each build (script/fetch-citations.rb) +_data/citations.json diff --git a/_data/citation_ids.yml b/_data/citation_ids.yml new file mode 100644 index 0000000..8e8afc0 --- /dev/null +++ b/_data/citation_ids.yml @@ -0,0 +1,9 @@ +# The Semantic Scholar record (paperId) of a paper_doi whose usual id +# (arXiv:, DOI:) finds no record there, or a duplicate with no +# citations. Keyed by paper_doi, so a regenerated post keeps it. +# _plugins/citations.rb fails the build on a key no post gives or a value that +# is not a paperId. The paperId is the hex string at the end of a paper's +# semanticscholar.org URL. + +# DeepSeek-V3: arXiv:2412.19437 leads to a duplicate record with 0 citations. +10.48550/arXiv.2412.19437: 5b6fdb2aea424d02c141da81d62b04d739d62b96 diff --git a/_includes/footer.html b/_includes/footer.html index 9b34741..e2a12ba 100644 --- a/_includes/footer.html +++ b/_includes/footer.html @@ -69,7 +69,7 @@ {% endif %} -{% if page.paper_doi %}{% endif %} +{% if page.citation_id %}{% endif %}