Skip to content

Latest commit

 

History

History
68 lines (47 loc) · 5.54 KB

README.md

File metadata and controls

68 lines (47 loc) · 5.54 KB
Raw

eSSIF-Lab Framework

This repo contains files that are used to generate the eSSIF-Lab framework website.

How To Contribute

In order to contribute, you need to

Contributions can be made by creating new, or modifying existing files in the repo, that live in the /docs directory of the framework repo. This includes files that define and describe the terms and mental models of the framework. That's where contributions can be made to (definitions and descriptions of) terms that we use, as well as the mental models. The corresponding files live in the /docs/terms directory of the repo.

The easiest way to start is to look at existing files so that you get an idea of how things are done. You'll quickly find out that they are markdown files that consist of two parts:

  • a 'header', i.e. a block of text at the top of the file that starts with three dashes (---), then has multiple lines that consists of fields (keywords and associated values (texts)), and concludes with another three dashes (---). Headers like this are not usual in markdown files, but they are in this repo.
  • a 'body', i.e. all the text that follows the header, which uses the typical basic markdown syntax. However, you can also use additional markdown features.

The Header (or Front Matter)

The header serves two purposes:

  1. it contains fields that are necessary to turn the files into a nice website. This is done by Docusaurus 2. Docusaurus calls this header data 'markdown front matter'.
  2. it also contains fields that are used by the TEv2, that allows you to enhance the terms in your text that have been properly defined (this is what makes the terms stand out on the website, and produces the popups when readers hover over them).

The easiest way to go about header fields is to look at existing files as examples that work.

Header fields that are used by Docusaurus are documented here.

Header fields that are specific for the Terminology Engine are defined for so-called curated texts.

The Body

This is where you put your documentation texts, that will show up in the static website.

Writing Docusaurus Documents

Docusaurus requires documentation content to appear in .md files inside the docs folder. Each file defines the following attributes at its very beginning:

  • id, by which the file is referred to across the project
  • title, appearing at the top of the file's display
  • sidebar_label, the file's name appearing in the sidebar

Documentation on these and other header fields can be found here.

The Terminology Engine v2 (TEv2) uses additional header fields. These are defined here.

The sidebars.js file contains the basic mechanism for distributing content among sections and is self-explanatory (compare with the sidebar appearing here). Subsections within the .md file (that is, tagged with ##) will appear at the right part of the page (see for example here).

Inserting Images in docs

If you want to add an image, say example.png, here is what you do:

  • first, add the image to the /static/images directory (or /static/images/subdir-path/)
  • then, in your document, add a line behind the docusaurus header that says: import useBaseUrl from '@docusaurus/useBaseUrl';
  • next, in your document, at the place where you want the image to be presented, insert the following snippet:
<img
  alt="text-that-shows-if-the-image-cannot-be-found"
  src={useBaseUrl('images/example.png')}
/>

(or src={useBaseUrl('images/subdir-path/example.png')} if you added the image file there).