Cite a paper using github markdown syntax

Question

I am coding a readme for a repo in github, and I want to add a reference to a paper. What is the most adequate way to code in the citation? e.g. As a blockquote, as code, as simple text, etc?

Suggestions?

Perpetuity

Answer 1

I agree with Horizon_Net that it depends on personal preference. I like to have something which looks similar to LaTeX. An example is provided below. Note that it demonstrates a numeric citation style. Alphabetic or reading style are possible too. For numeric citation style, higher numbers should appear later in the text, and this can make satisfying numeric citation style cumbersome. To avoid this problem, I typically use an alphabetic citation style.

"...the **go to** statement should be abolished..." [[1]](#1).

## References
<a id="1">[1]</a> 
Dijkstra, E. W. (1968). 
Go to statement considered harmful. 
Communications of the ACM, 11(3), 147-148.

"...the go to statement should be abolished..." [1].

References

[1] Dijkstra, E. W. (1968). Go to statement considered harmful. Communications of the ACM, 11(3), 147-148.

On GitHub flavored Markdown and most other Markdown flavors, you can actually click on [1] to jump to the reference. Apologies for taking Dijkstra his sentence out of context. The full sentence would make this example more difficult to read.

EDIT: If the references all have a stable link, it is also possible to use those:

The field of natural language processing (NLP) has become mostly dominated by deep learning approaches
(Young et al., [2018](https://doi.org/10.1109/MCI.2018.2840738)).
Some are based on transformer neural networks
(e.g., Devlin et al, [2018](https://arxiv.org/abs/1810.04805)).

The field of natural language processing (NLP) has become mostly dominated by deep learning approaches (Young et al., 2018). Some are based on transformer neural networks (e.g., Devlin et al, 2018).

Hy

Can you explain how [[1]](#1) work? I didn't find this usage in the markdown syntax. Thank you. – Mukden

It is just a link in the usual syntax, that is, [link text](link). However, the link text is [1], which might look confusing. – Hy

Great thanks. Is there any way to make the references list more like a numbered list? (i.e. first line indent and indented text wrapping). – Showman

Do you mean something like this: ``` 1. <a id="1"></a> Dijkstra, E. W. (1968). Go to statement considered harmful. Communications of the ACM, 11(3), 147-148. ``` or this: ``` 1. <a id="1"></a> Dijkstra, E. W. (1968). <br> Go to statement considered harmful.<br> Communications of the ACM, 11(3), 147-148. ``` – Cyclohexane

Answer 2

I just came across a citation in a github comment. They're calling them "footnotes" as of 2021.

The syntax is link to the footnote in your text using [^1], and then include the expanded reference on a separate line beginning with that same link.

Here is a simple footnote[^1]. With some additional text after it.

[^1]: My reference, with further explanation and a [supporting link](https://website.com).

Here is another footnote[^2].

[^2]: Another reference.

Important that you can include the reference source anywhere within the text (conveniently closer to where the reference is actually mentioned), and it will still be rendered at the bottom with all footnotes.

Tonnie

Answer 3

From what I know, there is no built-in mechanism for this. This leads to more subjective opinions, depending on personal preference. I personally like to have a separate section called references. An example would look like the following

References

• some reference
• another reference

Update

Another way would be to use simple HTML embedded in your Markdown.

Rascal

Seems fair enough. Thanks for your feedback : ) – Perpetuity

Answer 4

The alternative (to pure markdown) is to use the new GitHub integration from Aug. 2021:

Enhanced support for citations on GitHub

GitHub now has built-in support for CITATION.cff files.

This new feature enables academics and researchers to let people know how to correctly cite their work, especially in academic publications/materials.

Originally proposed by the research software engineering community, CITATION.cff files are plain text files with human- and machine-readable citation information.
When we detect a CITATION.cff file in a repository, we use this information to create convenient APA or BibTeX style citation links that can be referenced by others.

How this works

Under the hood, we’re using the ruby-cff RubyGem to parse the contents of the CITATION.cff file and build a citation string that is then shown in GitHub when someone browses a repository with one of those files1.

Now, that is helping others making your Github paper easily citable.

But, as documented, to "add a reference to a paper":

Citing something other than software

If you would prefer the GitHub citation information to link to another resource such as a research article, then you can use the preferred-citation override in CFF with the following types.

Resource	Type
Research article	article
Conference paper	conference-paper
Book	book

Extract

preferred-citation:
  type: article
  authors:
  - family-names: "Lisa"
    given-names: "Mona"
    orcid: "https://orcid.org/0000-0000-0000-0000"

Shapely

The question is about how to "add a reference to a paper" and not "make my paper easily citable". – Hy

@Hy Agreed. I have edited the answer to include the syntax allowing to reference another resource, such as a research article. – Shapely