Frontmatter

Frontmatter is a way to add metadata to a Pluto.jl notebook, such as the title, description, authors, cover image, license, date and more. This data is used when sharing notebooks online, using Pluto HTML exports, PlutoUI.NotebookCard, PlutoSliderServer, PlutoPages or pluto.land.

For example, the featured notebooks use frontmatter. When you see the list of all featured notebooks, notice how they all have a title, description, cover image and authors. And they are

The frontmatter GUI

When editing a Pluto notebook, you can open the frontmatter editor by clicking the โ€œShare buttonโ€ in the top right.

Screenshot of the Share button

In the share menu, click the ๐Ÿ“ฐ icon to open the frontmatter editor.

Here is a screenshot of the frontmatter editor. Scroll down to see more.

Screenshot of the frontmatter editor

In this editor, you can edit fields and add new fields. You are free to enter any data that you want (which you might want to use in your custom scripts), but some frontmatter entries have special meaning in the Pluto ecosystem.

Special frontmatter entries

The following keys have special meaning:

  • title โ€“ the title of the document. When not used, the notebook filename is used as title. This is used in Pluto.jl HTML exports as the <title> tag.
  • description โ€“ the description of the document. This is used in Pluto.jl HTML exports as the <meta name="description" content="..."> tag.
  • image โ€“ the URL of the cover image of the document.
  • date โ€“ the date of the document.
  • license โ€“ the license of the document.
  • tags โ€“ a vector of tags for the document, used by the PlutoPages.jl sidebar and search, and PlutoSliderServer.jl.
  • layout โ€“ the PlutoPages.jl layout file of the document.
  • order โ€“ the order of the document within its category.

Open Graph (OG) tags

The following keys are used as Open Graph (OG) tags in Pluto.jl HTML exports (using <meta property="og:...">):

title, type, description, image, article:tag, url, audio, video, site_name, locale, locale:alternate, determiner.

Setting these values helps with sharing notebooks on social media and search engine optimization.

The author field

There is also a vector author that is used to provide the authors of the notebook. The following fields have special meaning in the Pluto ecosystem:

  • name โ€“ the name of the author.
  • url โ€“ the URL of the authorโ€™s website. If this is a github user/organization URL, the authorโ€™s avatar will be shown in the notebook.
  • image - the URL of the authorโ€™s avatar. This is not needed if the url is a github URL.

PlutoPages.jl

If you are using PlutoPages.jl to write your website, you should at least set the following frontmatter entries for every page: layout and tags. (layout is the name of the layout file in the src/_includes/ directory.)

If you are writing a featured notebook, check out other featured notebook files to see which frontmatter entries are required.

Accessing frontmatter from Julia

If you are writing a script to process Pluto notebooks, you can access the frontmatter data using the Pluto.frontmatter function. This function takes a notebook path as an argument, and returns a Dict with the frontmatter data.

path = "/path/to/notebook.jl"
frontmatter = Pluto.frontmatter(path)
@info "Written by" frontmatter["author"]