Skip to content

Latest commit

 

History

History
186 lines (120 loc) · 6.47 KB

documentation.md

File metadata and controls

186 lines (120 loc) · 6.47 KB

Documentation

Content

This application is a static site generator. This means that each time content is changed, a build process must run to generate the final web site.

There are three content types in this application. markdown, standard and object. Developers can look in gatsby-config.ts and gatsby-node.ts to see how these are loaded. Content editors can look in the content folder to see how content is structured.

  • The markdown content type uses the Markdown language to generate text and image content such as blog articles and about pages. See content/markdown.
  • The standard content type is used for complex layouts such as the home page. It is defined in YAML and requires understanding of HTML to edit. See content/standard.
  • The object content type is generated by the build process using data from the Fitzwilliam Miniatures Directus to generate object pages.

Markdown

Markdown is a language that uses simple syntax to apply formatting. It is written in plain text and is used in the build process to generate pages with simple layouts. This document is written in markdown, if you are reading it on GitHub it has been rendered in to HTML.

Useful reading

To create a page, create a file inside content/markdown. The folder structure and filename does not impact the final website, it is purely organisational. The file must have the extension .md.

Markdown can be written in any text editor, some will provide a preview of the rendered HTML. There are many popular markdown editors that you can search for online. stackedit will work in the browser and provides useful shortcuts.

This project is hosted on GitHub which grants a few options for editing. The project can be cloned and edited locally, for which an understanding of Git it recomended.

GitHub also includes two workflows for editing markdown in the browser. There is more information at the followig links.

The following is the most common syntax, for more see https://www.markdownguide.org/basic-syntax/

Headings

# Heading 1

## Heading 2

### Heading 3

Paragraphs are created by adding a new line.

Paragraph 1

Paragraph 2

Links

[Our Research Explained](/research)

[The Fitzwilliam Museum](https://fitzmuseum.cam.ac.uk/)

Images included in the project. Notice that the link url is relative to the location of the markdown file and the image file. Where you save the image does not matter eg. inside content/assets/blog as long as you give the correct path. The left hand side is used as alt text.

![Figure 1](../assets/ABOUT_figure_1_1920_1280.JPG)

![Figure 1](../../assets/blog/a-roundtable-workshop/Figure_1_1920_1280.JPG)

Images on the web

![Ludovick Stuart](https://data.fitzmuseum.cam.ac.uk/imagestore/pdp/pdp78/3869_1_201805_kly25_dc2.jpg)

Unordered Lists

- First item
- Second item
- Third item

Ordered Lists

1. First item
2. Second item
3. Third item

Emphasis

*This text is italic*

**This text is bold**

To describe the page we use frontmatter, which is formatted in YAML in the leading --- at the top of every markdown content file. This includes the following fields:

  • slug - This is the url path you would like. For example /about, /blog/a-roundtable-workshop.
  • date - The content created or edited date. This is used in the blog listing page.
  • title - The title of the page, used in the template to add a title to the final HTML page.

The following example is the about page which can be found in content/markdown/about.md.

---
slug: "/about"
date: "2022-09-05"
title: "ABOUT THE PROJECT"
---
The ‘Unlocking the English Portrait Miniature’ web resource...

Standard page

Create new file inside content/standard/. The file name should match the title of the page with alphanumeric characters only. The filename must end in .md

For example, see content/standard/home.md.

The file format is markdown. The data structure inside the frontmatter (within the leading ---) is YAML.

Required fields:

title: "Home"
date: "2022-06-01"
slug: "home"
sections:
  - type: paragraph
    content: "Example paragraph"

Optional fields:

displayLogo: true
displayTitle: true
dark: true

Sections:

Sections are repeatable blocks on content, for example paragraphs.

Section types:

Type Fields
banner image_src: string, image_alt: string, title: string, logo: boolean, link: { url: string, title: string }, content: string
feature_box fb_type: 'single' or 'double', items: [ title: string, image_src: string, image_alt: string, content: string, link: { url: string, title: string }]
supporters items: [ image_src: string, link: { url: string, title: string }]
paragraph content: string

Objects

Object pages are generated at build time. Object information is pulled from directus. See gatsby-node.ts and src/tamplates/object.tsx.

Gatsby

Static site built with Gatsby with a Directus backend.

The static site is hosted on GitHub. There are three ways to trigger the Gatsby app to build:

  • When ever changes are made to the main branch.
  • Automatically, once every 24 hours.
  • Manually in the GitHub workflows interface.

The iiif manifest generator, also hosted on GitHub uses the same GitHub workflow rules. Therefore any changes on Directus will be reflected automatically within 24 hours and visible in the Mirador viewer.

Menus

Menus are configurable in gatsby-config.ts. See GatsbyConfig.siteMetadata.mainMenu.

Layouts are in src/components/header.tsx, src/components/footer.tsx and src/components/mainMenu.tsx.

Note: The header and footer are replicated in the Mirador Viewer app.