Citations

The Citation component cites sources held in a central Bibliography collection. Each source is recorded once, and every topic that cites it refers to it by a citation key. Correcting a publisher's name or a publication date updates every citation of that source across the doc set.

Bibliographic data follows the Citation Style Language (CSL) standard, the same format reference managers such as Zotero and Mendeley export. There is no importer yet, so a source from one of those is moved across by pasting its CSL-JSON into Raw CSL-JSON override.

Managing the bibliography

Sources live in one collection, separate from the topics that cite them.

1. Select Bibliography from the collection list.
2. Add a reference to the list.
3. Give it a Citation key. This is how topics refer to the source, so keep it short and stable—for example smith2020.
4. Choose a Type. Only the fields relevant to that type are shown, so a journal article offers an ISSN while a book offers an ISBN.
5. Fill in the remaining fields and save.

Note

Changing a citation key breaks every citation that uses it. Treat keys as permanent once a topic cites them.

A citation pointing at a key that no longer exists says so in place, the way a glossary term or a variable does:

typo-here NOT FOUND

The build still succeeds and every other citation on the page is unaffected, so one mistyped key does not stop you previewing the site. The build also lists them, in case the page is one you were not looking at.

Fields the form does not show

The form covers the fields documentation sources need, not every field the standard defines. Two categories are deliberately absent:

• Values the formatter works out for itself, such as citation numbers and the letters that separate two works by one author in the same year.
• Fields belonging to source types the Type list does not offer.

For a source the form cannot express, use Raw CSL-JSON override. Anything valid entered there replaces the fields above it, with the citation key kept.

Citing a source

1. Select Citation from the Embed list.
2. Add a source to the citation.
3. Choose a Source from the list of citation keys.
4. Optionally, give a Locator and a Locator type to point at part of the source.

Enter the locator as a bare value—14, or 14-16. Do not type p., because the citation style supplies that itself and styles disagree about what it should be.

One citation can cite several sources. Add more than one item rather than placing two citations side by side, so that the citation style can combine them.

Example

The following citation refers to a single source:

<Cite items={[{ key: "smith2020" }]} />

This one points at a specific page:

<Cite items={[{ key: "smith2020", locator: "14", label: "page" }]} />

This one cites two sources together, each with its own page reference:

<Cite items={[
  { key: "smith2020", locator: "14", label: "page" },
  { key: "jones2019", locator: "3-5", label: "page" }
]} />

Note

Citing the same source twice does not reuse the first citation. Each gets its own place, and the style decides how to shorten the later ones.

When changes appear

Editing a source in the Bibliography collection updates every citation of it straight away—correct a publisher's name and the change reaches the page while you watch, with no restart.

Three things behave differently, and it is worth knowing which is which:

Change	When it appears
Editing a source	Immediately
Adding a citation to a topic	Next build
Changing the citation style	After restarting the CMS

A new citation shows nothing at all until the next build—not a placeholder, not an error. It has no formatted text yet, and showing a half-formatted citation would be worse than showing none.

The citation style is the one setting that needs a restart, because it decides whether citations sit in the running text or in footnotes. That reshapes the page rather than just its wording, so the pages have to be rebuilt.

Note

Citations work in topics, not blog posts. Footnotes work in both. A citation placed in a blog post produces no output.

Choosing a style

A citation style controls how citations and the reference list are formatted. Styles differ in substance rather than decoration: some put a superscript number in the text and the source in a note, others put the author and year in brackets in the running text.

The style is set once for the whole site rather than per topic. Mixing styles within one doc set is a style error, because readers cannot tell what a given marker means.

Select Settings from the collection list, open Citations, and choose a Citation style:

Style	Where the citation goes	Example reference
Chicago (author-date)	In the text	Smith, Jane. 2020. The Art of Documentation. Oxford University Press.
Chicago (notes and bibliography)	In a footnote	Smith, Jane. The Art of Documentation. Oxford University Press, 2020.
Harvard (Cite Them Right)	In the text	Smith, J. (2020) The Art of Documentation. Oxford: Oxford University Press.
IEEE	In the text, numbered	[1] J. Smith, The Art of Documentation. Oxford: Oxford University Press, 2020.
Oxford (Guide to Style, notes)	In a footnote	Smith, J., The Art of Documentation (Oxford, 2020).

English variant

Only the Oxford style states which English it is written for. The others leave it to the site and fall back to American English, so a style that expects day-first dates—Cite Them Right, for one—dates a source August 18, 2026 unless told otherwise.

Set English variant to Global English to correct this. It affects date order, quotation marks and spelling on English pages only; the other languages take their conventions from their own locale.

Adding a language

The five languages docStatic ships with are ready to use. Adding another needs one file: the CSL locale that supplies its quotation marks, date order and terms like accessed.

Without it a page in the new language still builds, but its citations come out in English. The build says so and names the file to add:

! No CSL locale for "it": its citations will use the style's default (English).
  Add csl/locales/locales-it-IT.xml to fix.

Take that file from the CSL locales project and put it in csl/locales/. Nothing else is needed—the language is matched to its locale by name.

Set a title for the new language under References page title as well, or the sources page keeps its English heading.

Citations in a note style

Under Chicago (notes and bibliography) or Oxford, a citation is a footnote. The same <Cite> you already authored becomes a numbered note; nothing in the topic changes.

Citations and your own footnotes share one numbered sequence, in the order they appear on the page. Both Oxford and Chicago number notes consecutively throughout, and a reader cannot tell two sequences apart.

Because the numbering is worked out when the site is built, the style can shorten a repeat citation correctly rather than repeating it in full.

A note holding both comment and a citation

Chicago allows one note to carry a source and your own remark together. Put the citation inside a footnote and it renders within that note instead of creating a second one:

<Footnote summary="1"><Cite items={[{ key: "jones2019" }]} /> This argues the opposite.</Footnote>

Put the citation first and your remark after it. A note style ends a citation with a full stop, so a remark written around the citation rather than after it reads oddly.

For a remark of only a few words, use the citation's Suffix field instead—it stays with the citation under every style, including the in-text ones.

Example

Reuse is not free^[1], whatever the tooling promises^[2].

Under a note style both markers above are notes, numbered in sequence with every other note on this page—the first holding a source and a remark together, the second holding a citation alone. Under an in-text style the second appears in the sentence itself, and only the footnote is numbered.

A worked example

The paragraph below is live. Its citations are rendered in whichever style this site is currently set to, from the sources in the Bibliography collection.

Example

Documentation is best written once and reused^[3]. The idea predates the tooling^[4], and the same source returns to it later^[5]. Not everyone agrees^[6]. Two sources can be cited together in one citation^[7].

What to look at depends on the style in Settings:

• Under a note style—Oxford, or Chicago (notes and bibliography)—the markers above are footnotes, and the notes themselves are at the foot of this page. The author's own notes and the citations run in one sequence. The second citation of The Art of Documentation is shortened, because another note came between it and the first.
• Under an in-text style—Harvard, IEEE, or Chicago (author-date)—the citations appear in the sentence itself, and only this paragraph's two author footnotes are numbered.

The source of that paragraph is unchanged either way:

Documentation is best written once and reused<Cite items={[{ key: "smith2020", locator: "14", label: "page" }]} />.
The idea predates the tooling<Footnote summary="...">Technical writers were reusing content...</Footnote>,
and the same source returns to it later<Cite items={[{ key: "smith2020", locator: "22", label: "page" }]} />.
Not everyone agrees<Footnote summary="..."><Cite items={[{ key: "jones2019" }]} /> This argues that reuse...</Footnote>.
Two sources can be cited together in one citation<Cite items={[{ key: "smith2020" }, { key: "csl-spec" }]} />.

The sources page

A generated page lists your sources, formatted in the chosen style. It is separate from the citations in your topics: the note or in-text form of a source and its reference-list form deliberately differ.

To publish it, select Settings from the collection list, open Citations, and turn on Generate a sources page.

Bibliography or references

List every source, including uncited ones decides what the page contains, and what it is called:

Setting	Contains	Default title
On	Every source in the Bibliography collection	Bibliography
Off	Only sources your topics cite	References

The names are not interchangeable. A bibliography may include works you have not cited—background reading, further sources. A reference list, by convention, lists only what the text actually cites, so a reader who finds an entry there can expect to meet it somewhere in the documentation.

Cited means cited anywhere in the doc set, in any language. A source cited only on a page that has not been translated yet still appears in every language's list, so the lists do not shrink when a translation lags behind.

Naming the page

References page title sets the heading and the table-of-contents label, one entry per language, and overrides the default title above. Add a language and give it a title; leave a language out and it keeps its built-in title.

Placing the page

The page is published at /docs/references, but it is not added to the table of contents for you—only you know where it belongs in your reading order.

1. Select Table of Contents from the collection list.
2. Add a document entry pointing at docs/references.mdx, wherever you want it.

Leave the entry in place even if you later switch the page off: an entry whose page does not exist is ignored rather than breaking the build.

Note

The page is rebuilt from the bibliography on every build, in each of your site languages, so it is never out of date. Do not edit it by hand—your changes are overwritten. Correct the source in the Bibliography collection instead.

Note

Changing this setting renames the page, which changes its URL label in the sidebar but not its address: it stays at /docs/references.

Related topics

• Hosted CMS – Using docStatic with cloud-hosted or self-hosted TinaCMS.
• CALS Tables – Using CALS tables in docStatic, including merged cells, column widths and border control.
• Figures – Images with captions and lightbox zoom.
• Footnotes – Automatically numbered and back-linked footnotes.
• Tabs – Using tabs in docStatic.
• Adding the CMS to an iPad home screen – Adding the CMS to an iPad home screen
• Related Topics – Automatically generate links to related content based on shared taxonomy tags.

---

Footnotes

1. Alex Jones, ‘Single-Sourcing in Technical Communication’, Journal of Documentation Practice, 42/3 (2019), 112–34, https://doi.org/10.0000/jdp.2019.42.3.112. This argues the costs outweigh the savings. ↩
2. Citation Style Language Project, ‘Citation Style Language Specification’ (2024), https://docs.citationstyles.org/, accessed 18 Aug. 2026. ↩
3. Jane Smith, The Art of Documentation (Oxford, 2020), 14. ↩
4. Technical writers were reusing content through conditional text long before single-sourcing had a name. ↩
5. Smith, The Art of Documentation, 22. ↩
6. Jones, ‘Single-Sourcing in Technical Communication’. This argues that reuse costs more than it saves. ↩
7. Smith, The Art of Documentation; Citation Style Language Project, ‘Citation Style Language Specification’. ↩