Skip to content

Revise Citation section of GH repo guide#69

Open
egrace479 wants to merge 9 commits intomainfrom
cite-clarify
Open

Revise Citation section of GH repo guide#69
egrace479 wants to merge 9 commits intomainfrom
cite-clarify

Conversation

@egrace479
Copy link
Copy Markdown
Member

I endeavored to simplify the CITATION.cff template as follows:

  • Created two "content tabs" to default to the standard template (Recommended) and include an extended option.
    • This required adding one more markdown_extension config in the mkdocs.yaml.
  • Admonitions are in the content tabs to encourage the use of a .zenodo.json paired with the citation file.
  • All content about the extended option is within its tab.
  • Removed the validator tool link, replacing it with a note to check the formatting on the branch. That tool just checks it's valid yaml; it doesn't guarantee citation formatting.
    • This further supports @hlapp's suggestion of a "student project to stand up a single-page serverless web app that asks for the metadata and outputs the CFF file the way we want it".

I also added the "references" key to the .zenodo.json template for completeness.

Closes #64.

set up a standard vs extended citation
also adds references as a key in Zenodo metadata template, with citation pointer recommending use there
used for citation CFF templates
include examples and exlanations for keys
Move preferred-citation notes to tab where it's included
…ranch

validator tool checks yaml, not citation cff format
@egrace479 egrace479 requested a review from hlapp April 28, 2026 01:54
@egrace479 egrace479 added enhancement New feature or request structure Refactoring or architecture, general code organization labels Apr 28, 2026
Copy link
Copy Markdown
Member

@hlapp hlapp left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM.

One comment re: wording to perhaps consider: That we generally want to ask people to cite both software and paper (if there is a paper) is an institutional practice we chose. But prioritizing the paper citation can also be a choice, which can result in actually wanting the paper citation to show up on the sidebar on GitHub (and perhaps including the code citation BibTeX in the README instead).

I don't have a good suggestion for how to convey this being a choice when instantiating the template, and of course there are a variety of reasons why code as a first-class citizen in citation networks should be promoted. So maybe this is best deferred to considering at a later time.

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

Labels

enhancement New feature or request structure Refactoring or architecture, general code organization

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Citation guidance in GitHub section may need more clarification

2 participants