Front matter can be set in a markdown (md
) or notebook (ipynb
) file (described as a “page” below) or in the project:
section of a curvenote.yml
file. When set in a curvenote.yml
file, those settings will be applied to all content in that same folder and subfolders (apart from “page only” fields).
Where to set frontmatter¶
In a markdown file¶
A frontmatter section can be added at the top of any md
file using ---
delimiters.
---
title: My First Article
date: 2022-05-11
authors:
- name: Jane Bloggs
affiliations:
- University of Europe
---
In a Jupyter Notebook¶
Front matter can be added to the first cell of a Jupyter Notebook, that cell should be a Markdown cell and use ---
delimiters as above.
In a markdown-based notebook¶
If your Jupyter Notebook is described as a markdown file (e.g. using jupytext, or MyST), then this should be included in the frontmatter section as usual in addition to the jupyter
key that defines the kernel and jupytext metadata.
In a curvenote.yml
file¶
Front matter fields can be added directly to any project:
section within a curvenote.yml
file. If your root curvenote.yml
file only contains a site:
section, and you want to add front matter, add a project:
section at the top level and add the fields there. e.g.
version:1
site:
...
project:
license: CC-BY-4.0
open_access: true
Available frontmatter fields¶
The following table lists the available front matter fields, a brief description and a note on how the field behaves depending on whether it is set on a page or at the project level. Where a field itself is an object with sub-fields, see the relevant description on the page below.
Table: 1A list of available front matter fields and their behaviour across projects and pages
field | description | field behaviour |
---|---|---|
| a string (max 500 chars) | page & project |
| a string (max 500 chars) | page & project |
| a string (max 40 chars) | page & project |
| a string (max 500 chars) | page & project |
| a list of strings | page only |
| a link to a local or remote image | page only |
| a string (max 500 chars) | page only |
| a valid date formatted string | page can override project |
| a list of author objects | page can override project |
| a valid DOI, either URL or id | page can override project |
| a valid arXiv reference, either URL or id | page can override project |
| boolean (true/false) | page can override project |
| a license object or a string | page can override project |
| a valid GitHub URL or | page can override project |
| any valid URL | page can override project |
| a string (max 40 chars) | page can override project |
| a venue object | page can override project |
| a biblio object with various fields | page can override project |
Field Behaviour¶
Frontmatter can be attached to a “page”, meaning a local .md
or .ipynb
or an Article or Notebook on curvenote.com, or a “project”. However, individual frontmatter fields are not uniformly available at both levels, and behaviour of certain fields are different between project and page levels. There are three field behaviours to be aware of:
page & project
- the field is available on both the page & project but they are independentpage only
- the field is only available on pages, and not present on projects and it will be ignored if set there.page can override project
- the field is available on both page & project but the value of the field on the page will override any set of the project. Note that the page field must be omitted or undefined, for the project value to be used, value ofnull
(or[]
in the case ofauthors
) will still override the project value but clear the field for that page.
Thumbnail¶
The thumbnail is used in previews for your site in applications like Twitter, Slack, or any other link preview service. When you clone a project from Curvenote, the thumbnail gets downloaded in a thumbnails
folder next to your content, if you do not want this thumbnail, you can explicitly set it to another image on your local file system or a remote URL to an image. This image will get copied over to your public folder when you build your project.
thumbnail: thumbnails/myThumbnail.png
If you do not specify an image the first image in the content of a page will be selected. If you explicitly do not want an image, set thumbnail
to null
.
Authors¶
The authors
field is a list of author
objects. Available fields in the author object are:
field | description |
---|---|
| a string - a system field, when present this should not be modified. |
| a string - the author’s full name |
| a string - a valid ORCID identifier |
| boolean (true/false) - flags any corresponding authors |
| a string - email of the author, required if |
| a list of strings - must be valid CRT Contributor Roles
|
| a list of strings - freeform affiliation names, e.g.
|
Date¶
The date field is a string and should conform to a valid Javascript data format. Examples of acceptable date formats are:
2021-12-14T10:43:51.777Z
- an ISO 8601 calendar date extended format, or14 Dec 2021
14 December 2021
2021, December 14
2021 December 14
12/14/2021
-MM/DD/YYYY
12-14-2021
-MM-DD-YYYY
2022/12/14
-YYYY/MM/14
2022-12-14
-YYYY-MM-DD
Where the latter example in that list are valid IETF timestamps
Licenses¶
This field can be set to a string value directly or to a License object.
Available fields in the License object are content
and code
allowing licenses to be set separately for these two forms of content, as often different subsets of licenses are applicable to each. If you only wish to apply a single license to your page or project use the string form rather than an object.
String values for licenses should be a valid “Identifier” string from the SPDX License List. Identifiers for well-known licenses are easily recognizable, but can be more specific than you are used to, for example:
Common Content Licenses | Common Code Licenses |
---|---|
|
|
By using the correct SPDX Identifier, your website will automatically use the appropriate icon for the license and link to the license definition.
Venue¶
The term venue
is borrowed from the OpenAlex API definition:
Venues are where works are hosted.
Available fields in the venue
object are title
and url
.
Some typical venue
values may be:
venue:
title: Journal of Geophysics
url: https://journal.geophysicsjournal.com
or
venue:
title: EuroSciPy 2022
url: https://www.euroscipy.org/2022
Biblio¶
The term biblio
is borrowed from the OpenAlex API definition:
Old-timey bibliographic info for this work. This is mostly useful only in citation/reference contexts. These are all strings because sometimes you'll get fun values like "Spring" and "Inside cover."
Available fields in the biblio
object are volume
, issue
, first_page
and last_page
.
Some example biblio
values may be:
biblio:
volume: "42"
issue: "3"
first_page: "1" # can be a number or string
last_page: "99" # can be a number or string
OR
biblio:
volume: "2022"
issue: Winter
first_page: Inside cover # can be a number or string