User:Kim/Prototyping 2nd year/GitPub Cite

Objective

inline cite my own metadata

1. metadata record formatted as yaml bibliography
2. custom csl (defining inline citation style)
3. pandoc citeproc for rendering

regular citation using .bib file works like this [@coombs1987] and is then rendered (pandoc) into the format defined in csl (Coombs, DeRose and Renear, 1987). see VS Codium - Zotero - BibTex

GitPub cite now enables to inline reference a commit hash [@7ddda5e] which will then be rendered into the metadata it refers to (7ddda5e - commit message - date).

• 

to make this work, two main steps had to be taken:

Yaml Metadata

Git log output (metadata) formatted as yaml bibliogrpahy.

in order to be legible for CSL, yaml has to comply to:

1. specific terms (e.g. 'id', 'categories', 'note', 'language') these are predefined in the fixed vocabulary of csl
2. csl required term: 'type'
3. which relate to specified object types (e.g. id = string or number, categories = array of string)
4. cant have too nested structure but must follow object types above

example

---
references:
- id: 0ed2ae3
  type: dataset
  status: 2026-01-28
  publisher: Kim Kleinert
  note: >-
    small changes and tests csl nothing chnaged so far, rendering metadata references the correct id and outputs status content
  locator: 
- id: 7812e56
  type: dataset
  status: 2026-01-27
  publisher: Kim Kleinert
  note: >-
    metadata taxonomy change pomerantz to gartner
  locator:  (origin/main, main)
bibliography: ['./references.bib', 'chapter_1.yaml']
supress-bibliography: true
csl: harvard-meta.csl
---

the gitlog output is listed under references, where each log entry is one reference. below i define the bibliography files: the .bib file for regular citation and this current file for metadata (yes, it references itself). Lastly, I link to my custom csl file.

resources

• yaml/json and yaml examples for bibliographic formatting
• documentation for cls specific terms and object types in yaml / json

CSL

Citation Style Language

is an xml based markup language for formatting references, bibliographies and inline citations using standard citation styles such as APA, Harvard etc.

CSL is divided in dependent (linked/ based on an independent style, usually linked in the head, less metadata needs to be defined bc the actual citation formatting is only linked to) and independent (defines citation format, relies on locale files specifying languages dates, terms and grammar) styles.

changes made

getting a value from a yaml object in csl using <macro>. Where variable="note" refers to the yaml object name and the name="note" can be reused later to get the value of this macro, such as in the citation layout (see below).

<macro name="note">
  <choose>
    <if type="dataset">
      <text variable="note" />
    </if>
  </choose>
</macro>

in a csl file, the <citation> tag defines how the inline citation will be rendered. Adding a specific output for type="dataset" inserts metadata in the text.

<citation et-al-min="4" et-al-use-first="1" disambiguate-add-year-suffix="true" disambiguate-add-names="true" disambiguate-add-givenname="true" collapse="year">
   <sort>
     <key macro="year-date"/>
   </sort>
   <layout prefix="(" suffix=")" delimiter="; ">
     <choose>
       <if type="dataset">
         <group delimiter=" ">
           <text macro="status"/>
           <text macro="publisher"/>
           <text macro="note"/>
           <text macro="locator"/>
         </group>
       </if>
       <else>
         <group delimiter=", ">
           <text macro="author-short"/>
           <text macro="year-date"/>
         </group>
       </else>
     </choose>
   </layout>
</citation>

resources

• repository of citation styles and their csl files.
• csl introduction
• csl specs

To Do

1. add linebreaks after text elements. (specification states formatting options for tags, as well as affixes or display options for groups)
2. add a default stylesheet that makes more sense than the current one (especially metacontainer)
3. reference rendering is broken (but works in gitpub v4) > exclude references.md from loops ?

metadata citation workflow: rn, in order to cite a git commit by its short has, the user has to do git log --pretty=format:%h or check the remote repository on a platform

think about

windowing hypertext in ted nelsons literary machines (1/16) via https://archive.org/details/literarymachines00nels

• styling of the inline citation (is it breaking the text or is it inline? is it distinguishable from the 'regular' citations?)
• what is its relation to the regular citations?
  • a regular citation contains descriptive metadata (such as author, year) of an external resource/ document that it points to
  • a gitpub citation contains technical and structural metadata of itself. it does not point to an external file but to itself.

fixed

ted nelson in literary machines about literature 'as a system of interconnected writings'. in print we dont see these links and other writings...

issue: reference rendering

should do: output only one global reference list, instead of one per file

why did it break?: in gitpub v 0.4 ++ the reference rendering works with a combination of supress bibliography: true (for individual files) and a separate reference.md file that renders all citations using nocite: '@*'. In cite-meta this broke when I added a custom csl file, which did not correspond / listen to supress bibliography true... (and lacking documentation did not help)

fix: (not the most elegant solution but works)

1. references.md file is provided with slightly different metadata: "---\nreferences:" + file_commits + "\nbibliography: ./references.bib\ncsl: harvard-meta-bib.csl\nnocite: '@*'\n---"
2. it has a specific cls file that conatains <bibliography>, which is removed from the standard csl file to omit bibliography output
3. adding the option nnocite: '@*' includes all references contained in the linked .bib file
4. removed self referential .yaml file (references.yaml) from bibliography list to avoid confusion