About

This is the source repository for an LDaCA based website.

NEW DESIGN

Prerequisites

• Node
  • Follow instructions on how to download on the page above
  • This was tested using MacOS
  • Verify installation with packages that you have npm and node commands
  • TODO: check what are the node versions this requires

Notes on specs

• This site is being built using vitepress version 2. See package.json for details
• A .vitepress folder is used to theme the website
• Running a production build will generate static html files that can be served in .vitepress/dist

How to use

• Clone the repository
• Change directory into the repository
• Run npm install

For development

• Run npm run dev
• See the Local address of where it is being served. Normally it would be
  • Local: http://localhost:5173 but if that port is being used it will push to another port

For QA - Very important! Do not skip

• See what actually will be produced for production
• Run npm run test:production - this will run vitepress build and preview
• See the Built address of where it is being served. Normally it would be
  • Built site served at http://localhost:4173/ but if that port is being used it will push to another port

How to run in production and do updates

• TODO

Configuration

Configuring the website is using the .vitepress/config.ts file and develop the LDaCA theme in .vitepress/theme

Documentation

Styling

Default styling is handled in .vitepress/theme/style.css. Components may also have additional styling within their own .vue files, generally in the Tailwind CSS class="" sections.

General Tips

• Do not use _index.md for root list pages. Instead use index.md with layout: root_list in the frontmatter. See RootList below for more details.

Page Layouts

All layouts are stored in /theme/layouts. To use these, add layout: layout_name to the frontmatter of the .md file.

Doc

layout: doc

Use this layout as the default for .md pages.

Event

layout: event

Use this layout for events pages, currently stored in /training-events/events/YYYY. This layout has two sections:

• left side: standard Markdown text for event description, videos, etc. taken from the content of the .md file
• right side: an event details box taken from the frontmatter of the .md file

Use the following frontmatter template:

---
title: ""
description: ""
layout: event
image: /path/to/image.png
link: ""
eventDate: ""
eventTime: ""
location: ""
cost: ""
organiser: ""
pastEvent: false
---

NOTE: change pastEvent to true if this event has finished. This will update the link button from displaying 'Register' to 'More information' instead.

See ## Referencing Images for more detail on adding images to frontmatter.

Post

layout: post

Use this layout for blog posts, currently stored in /news/posts. This layout is identical to the doc layout, but adds the author to the SimpleHero section and contains a link back to 'All Posts' at the top of the page content, as well as the date published.

Use the following frontmatter template:

---
title: 
date: YYYY-MM-DD
description: ""
image: /path/to/image.png
layout: post
type: 
author:  <Profile id="smith" />
---

If the blog is a presentation, add type: presentation to the frontmatter. This will categorise it as a presentation and display it in the 'Latest Presentations' section on the Resources page, and in the carousel on the Presentations page.

If the blog is a interview, add type: interview to the frontmatter. This will categorise it as an interview and display it in the 'Latest Interviews' section on the Resources page, and in the carousel on the Interviews page.

Project

layout: project

Use this layout for project pages, currently stored in /projects-case-studies/projects. This layout has two sections:

• left side: standard Markdown text for project description, outcomes, further reading, etc. taken from the content of the .md file
• right side: image, project details and information boxes taken from the frontmatter of the .md file

Use the following frontmatter template:

---
title: 
description: 
collaborator: 
projectTeam: 
link: "[howlinkwilldisplay.com](https://url.com)"
outcomes: "[Project report](https://pdf.pdf) and [online database](https://url.com)"
information: ""
image: /path/to/image.png
---

RootList

layout: root_list

Use this layout for index pages linking to multiple .md files. This supercedes the older _index.md format for these pages.

Referencing Images

Images are either:

• stored in the same folder they relate to, e.g. images for a blog post appear in the same folder as the blog's .md file, or
• stored in /content/public/images and its subfolders, if the images are more general use.

To reference an image in an .md file, use the format:

<figure>
	<img src="./image.png" alt="Alt text goes here" title="Image title goes here" style="height: 400px;" />
	<figcaption>Figure 1: The caption displayed beneath the image goes here. (Photo credit goes here)</figcaption>
</figure>

NOTE: if using an image from /content/public/images, use the path /images/... instead.

Adjust the height after style as needed. This will maintain the aspect ratio of the image while resizing it.

For setting thumbnail/preview images to be used on other components and pages, add these to the image field in the related .md file's frontmatter, and use the full file path after content (don't include content in the path). For example:

image: "/news/posts/example-blog/blog-image.png"

Pull Quotes

Use the following syntax to create pull quotes in an .md file:

<p class="pull-quote">
    Quotation goes here. This will be styled as a pull quote.
    <cite>Citation information</cite>
</p>

Referencing Glossary Items

To reference glossary terms, use the format:

<GlossaryLink display="LDaCA" id="ldaca" />

To add or edit glossary terms, see the .yml files in data/glossary. To search an .md file for possible glossary terms, see _glossarySearch/glossarySearch.py.

Referencing Profile Items

To reference a profile item, use the format:

<Profile id="smith" />

If writing a blog post, add the author in the following format in teh frontmatter:

author: '<Profile id="smith" />'

To add or edit profiles, see the .yml files in data/profiles.

List of Currently Available Components

All components are stored in /theme/components. To use components, add <ComponentName /> to the relevant section of your .md file, with any properties you need for that component (e.g. heading, description, items). These include:

Component	Options
BlogPostsList.vue	N/A
BlogPostsPage.vue	N/A
Carousel.vue	heading: text description: text items: array OR type: presentation/interview image: filepath (default: '/images/Petroglyph_Pattern.svg') backgroundColor: colour opacity: number (default: 100) shade: light (default: dark) buttonText: text (default: 'View more') viewAll: link yearFilter: boolean (default: false) tileView: boolean (default: false) threeTiles: boolean (default: false)
CarouselLarge.vue	heading: text description: text items: array image: filepath (default: '/images/Petroglyph_Pattern.svg') backgroundColor: colour (default: '#f3f0e8') opacity: number (default: 100) buttonText: text (default: 'Try it out') tileView: boolean (default: false)
Collaborators.vue	heading: text description: text items: array backgroundColor: colour opacity: number (default: 100)
CollectionsGrid.vue	heading: text description: text backgroundColor: colour (default: '#79a38d') backgroundImage: filepath (default: '/images/Collections_BG.png') opacity: number (default: 100) buttonText: text (default: 'Learn more')
Contact.vue	image: filepath
ContactBox.vue	heading: text description: text buttonText: text buttonLink: link
DataPortalBox.vue	heading: text description: text buttonText: text buttonLink: link
DocTiles.vue	heading: text items: array image: filepath (default: '/images/Petroglyph_Pattern.svg') title: text link: link description: text
Features.vue	N/A
FeaturesBanner.vue	N/A
Footer.vue	N/A
GlossaryLink.vue	N/A
GlossaryList.vue	N/A
GuideCarousel.vue	heading: text description: text items: array image: filepath (default: '/images/Petroglyph_Pattern.svg') backgroundColor: colour opacity: number (default: 100) viewAll: link
Header.vue	N/A
HomeHero.vue
LatestBlog.vue	N/A
Menu.vue	N/A
PartnerLogos.vue	logos: array
People.vue	heading: text description: text items: array image: filepath (default: '/images/Petroglyph_Pattern.svg') name: text affiliation: text link: link
Profile.vue	id: string
Sidebar.vue	N/A
SimpleHero.vue	title: text description: text backgroundImage: filepath (default: '/images/GreenBackground.png') breadcrumb: text
SimpleNavigation.vue	title: text description: text contents: array
TagsList.vue	N/A
ThreeTiles.vue	heading: textitems: array image: filepath (default: '/images/Petroglyph_Pattern.svg') backgroundColor: colour opacity: number (default: 100) shade: light (default: dark)
ToolsGrid.vue	heading: text description: text backgroundColor: colour (default: '#79a38d') backgroundImage: filepath (default: '/images/Collections_BG.png') opacity: number (default: 100) buttonText: text (default: 'Learn more') crateUrl: filepath or url to ro-crate-metadata.json
TwoTiles.vue	heading: textitems: array OR type: presentation image: filepath (default: '/images/Petroglyph_Pattern.svg') buttonText: text (default: 'View all') viewAll: link
VerticalTabs.vue	heading: text description: text background: colour items: array
VerticalTabsBanner.vue	heading: text description: text background: colour items: array buttonText: text (default: 'Find out more')

• How to use Tailwind /CSS in place
• Blog Post

TODO Development

• Tags
• Footer
• Search
• Analytics Page
• Menu filter by tag? Resources menu

TODO Cleanups

• Remove old Hugo Files
• How to run updates/production
• Configure .github/workflows
• about/sample-collections.md