Skip to content

Editing

Jump to bottom
Henry Babbage edited this page Jul 11, 2024 · 14 revisions

Markdown and MDX

The content on this website is managed using Markdown and MDX. MDX is a superset of Markdown that allows for React components to imported and inserted alongside Markdown text content. Read more about MDX here.

Markdown is a lightweight markup language that you can use to add formatting elements to plaintext text documents. Find a reference guide for using Markdown syntax here.

MDX Page Files

For the FCP Documentation website, each page is separate page.mdx file. Find the page you want to edit by matching the slug for the page with the folder name in the project codebase. For example, to edit the /background page (www.docs.forestrycatchmentplanner.nz/background) you would open the forestry-catchment-planner-docs GitHub repository and navigate to src > app where you will find the full list of directories that represent all of the project's routes (pages on the website). Inside the app directory, you would open the folder titled background and click on the page.mdx file there to edit its content.

Images

Inside each route directory you will find a page.mdx file and if the page imports image files, you will also find an _images folder containing images that are imported into the page.mdx file. You can add any new images that you need to use on the page into this _images folder. Each route directory should have its own folder for images and that folder should always be labelled _images. The underscore prefix is important so that the codebase does not recognise that folder as a new nested route.

editing

Importing Images

When importing images into a page.mdx file you need to provide the route to that image. For any image in the _images folder, the import string should look like: import image1 from './_images/image1'.

Displaying Images

To then use that image on the page, there are React image components that can be imported to display the image. For a simple single image display, or for .gifs, use Image: import Image from 'next-export-optimize-images/image'. For either an image with a caption, or an image that has a dark mode version and a light mode version, use Figure: import { Figure } from '@/components/Figure'. For more than one image displayed together in a group, such as a gallery of images, use Gallery: import { Gallery } from '@/components/Gallery'. All of the image components accept a string for the alternative text for the image, for accessibility standards; simply add a string of text between quotation marks on the alt prop like so: alt="Alternative text for the image".

Image

To provide the imported image to the simple Image component, use the following as an example:

import Image from 'next-export-optimize-images/image'

import kaingaroaForest from './_images/kaingaroa_forest.jpg'

<Image src={kaingaroaForest} alt="Kaingaroa Forest" />

Please note that for gifs, you must use the Image component. The Figure and Gallery components cannot be used with .gifs.

Figure

import { Figure } from '@/components/Figure'

import ageClassProcess from './_images/indufor_classification_process_light.png'
import ageClassProcessDark from './_images/indufor_classification_process_dark.png'

<Figure src={ageClassProcess} srcDark={ageClassProcessDark} alt="Age class process." caption="Age class process diagram." />

Please note that the caption for the image is provided to the caption prop on the Figure component as a string between quotation marks.

You can provide an image for the light mode display setting to the Figure component's src prop, and an image for the dark mode display setting to the Figure components' srcDark prop. You do not have to provide a dark mode image, you can provide just provide a light mode image and it will be used for both modes. But you must provide a light mode image.

Images displayed with Figure are automatically displayed with a zoom option and when clicked are expanded to view at a larger size.

Figure example

Gallery

import { Gallery } from '@/components/Gallery'

import before from './_images/map_graph_assets_before.png'
import after from './_images/map_graph_assets_after.png'
import detection from './_images/map_graph_assets_harvest_detection.png'

<Gallery
  images={[
    {
      src: before,
      alt: 'Before',
      caption: 'Before harvesting.',
    },
    {
      src: after,
      alt: 'After',
      caption: 'After clearfelling.',
    },
    {
      src: detection,
      alt: 'Detection',
      caption: 'Detection of harvest.',
    },
  ]}
/>

For the Gallery component you can provide a set of images to be displayed in a grid from left to right. You can provide as many images as you like, but for the best display, most likely three to six images will be ideal, or up to nine at the upper limit. The gallery component does not currently support separate dark and light mode images, so simply provide an image that works well on a light background and a dark background. As with the other image components, the image should be imported from the route directory where it is placed, given a variable name, and then provided the the src field within an object within the array passed to the Gallery component's image prop.

Gallery example

Clone this wiki locally