Skip to main content

Use Docusaurus

info

This page contains information how to edit a page in the Docusaurus instance for the Chemotion ELN hosted at KIT. If the content is seen in a more general manner, it can also be used for the editing of other Docusaurus instances. For that replace special links, references etc. with the counterpart of your instance.

This website is based on the Docusaurus framework , that uses Markdown with JavaScript (MDX). Therefore the content is stored as a mixture mainly containing Markdown with elements from HTML and from the JavaScript Framework React. The most important and used components are explained below. More information about Markdown in docusaurus can be found in the official Docusaurus Documentation

Editing#

To ensure consistent style and naming throughout the documentation, please make sure to have a look at our styleguide while editing. For changing the documentation you need a GitHub Account and then you can use the Edit this page button at the left bottom of every page. This will leads you to an Editor on GitHub, where you can directly edit the page and make a Pull Request afterwards or commit your changes directly, if you have write access. For advanced usage of chemotion_saurus, you can also clone the repository and push to it, if you have write access. Therefore follow the instructions in the set up chapter. Succesfull changes are directly deployed and went online. You can check GitHub Actions, to see if your changes are succesfully merged in the web page. More information about GitHub Actions (in general and for the Chemotion ELN) are in the testing chapter. The landing (start) page can be edited on GitHub.

New Page#

  • use .mdx as filename ending in GitHub
  • Insert at the top of every page:
---
id: videos_eln
sidebar_label: Videos
slug: videos_eln
title: Introduction Videos
---

id: The unique document id. By default, a document id is the name of the document (without the extension) relative to the root docs directory. It can be used in the left TOC.
sidebar_label: Name displayed in the table of content (TOC).
slug: Optional. Defines the last part of the URL.
title: Optional. Prompted on the page.

Markdown#

Assets#

images, gifs, videos, files#

Images can be inserted as Markdown or as HTML for special configurations (optional width and height etc.) or if the image is inside an HTML tag. The ![...] in Markdown or alt={...} in HTML/React creates an alt tag for an additional title, if the image loading failures. Keep in mind, that the image paths for Markdown and HTML differs, which is caused by different treatment of Markdown and React (which creates the HTML) in Docusaurus.

Inserting an image in Markdown:

![Export Menu](/img/export_menu.png)

Inserting an image in HTML (React):

<img src={require('@site/static/img/export_menu.png').default} width={"30px"} height={"30px"} alt={"replacement_title"} />

SVG#

SVGs need a special treatment. First import them as React component and then insert them in your text with className="logo":

import Sample from '@site/static/img/sample.svg'
// more content here
<Sample title="Sample" className="logo" width={"30px"} height={"30px"} />

Buttons and Icons#

regular buttons with text and icon content#

For creating buttons use a button function and import it in the page. Every button gets a color and can have multiple text elements and icons mixed in its content. For icon buttons the library Font Awesome is used. Get icons from https://fontawesome.com and import them in the page, too. The color palette is from the Infima library. For example following code snippet...

import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'
import { faChartBar, faCheck } from '@fortawesome/free-solid-svg-icons'
import { Btn } from '@site/docs/btn.js'
<Btn mixed={[faChartBar, " 1", faCheck]} color={"secondary"}/>

...produces

special buttons#

To create a button diffrent from the regular one, e. g. with a different size, you need to use a React button with <button></button> tags. You can change the size of a button in its style attribute with values in %, pixel (px), rem or em. Common icon sizes inside buttons are xs, sm and lg.

import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'
import { faPlus, faShareAlt } from '@fortawesome/free-solid-svg-icons'
<button className={"button button--sm button--success"} style={{padding:"2px", height: "50%", width: "50%"}}>
<FontAwesomeIcon icon={faPlus} size="lg"/>
</button>
<button className={"button button--sm button--success"} style={{padding:"2px", height: "40px", width: "40px"}}>
<FontAwesomeIcon icon={faPlus} size="sm"/>
</button>

Downloadable Files#

If you want to provide one or multiple file(s) to download directly form the manual, then upload them to the files folder in GitHub and insert a Download Button with the filepath(s) - separated by comma - in files and the button text in text :

import { DownloadBtn } from '@site/docs/download_files.js'
<p><DownloadBtn files={['/chemotionsaurus/files/template%20_sample_import.xlsx, docker-compose.yml']} text={"Download XLSX Template here "}/></p>

Escape signs#

To show signs, that are specified in the Markdown syntax, escape them with \.

Formatting#

Color#

colored letters:

<span style={{color:"yellow"}}>some text</span>

colored background:

<span style={{background:"yellow"}}>some text</span>

Strikethrough#

<del>deleted text</del>

Headings#

To create a heading, add number signs # in front of a word or phrase. The number of # you use should correspond to the heading level. A lot of # indicates a low level.

Info Boxes#

Highlighted info boxes (like in the eln intro page) with further informations are called Admonitions in Docusaurus.

Line Breaks#

Insert two white spaces at the end of the line.

Links#

Links can be created via Markdown or React:

The link structure in Markdown:

[title](slug)

... and in React:

import Link from '@docusaurus/Link';
<Link to="/path">Title</Link>

extern#

In Markdown:

[www.chemotion.net](https://www.chemotion.net)

In React:

<Link to="https://www.chemotion.net">www.chemotion.net</Link>

intern#

In Markdown link to another page in the docu with the slug or if not available the id as anchor:

[contact](specific_contact)

link to another chapter in the same page with the last segement of the URL: e. g. URL: eln.chemotion.net/chemotionsaurus/docs/instructions #toc

[link to TOC](#toc)

In React insert link to another with a the relative path after the base url /chemotionsaurus/:

<Link to="/docs/eln/structure">Structure of the Chemotion ELN</Link>
Recommendation

For links to intern pages it is not recommended to use https links from the server, where the website stays. It is better to use Markdown syntax with relative intern linking. For example: better use: [contact](specific_contact) instead of: [contact](https://www.chemotion.net/chemotionsaurus/docs/eln/specific_contact)

Lists#

ordered#

random number with a dot

1. text
1. text1
1. text2
  1. text
  2. text1
  3. text2

unordered#

* text
- text1
  • text
  • text1

Table#

| header 1 | header 2 |
|---|---|
| field 1 | field 2 |

Text Formatting#

bold
<b>bold</b>

highlight elements, e. g. UI elements

`Collection Bar`

Hints & Errors#

Links or insertion of images or files are not resolved in Markdown#

For writing content in the Docusaurus framework it is generally recommended to use Markdown for the most content instead of pure HTML/CSS or React. Some things are easier to style in React than in Markdown (e. g. buttons) and some things can be done in Markdown or in React (e. g. links, images). If you write a paragraph in Markdown and mix it with some React elements and then insert some Markdown links, it could be the case that the Markdown links are not resolved on the web page. Replace them wirth React elements.

TOC#

The TOC on the left of every documentation page must be manually updated via sidebars.js on GitHub. If you have inserted a new page or want to change the order, change it there.

Versioning#

Currently versioning is not enabled for the Chemotion ELN part of the documentation, but this could be quickly changed in the future. To create a new documentation version based on the latest content in the docs Chemotion ELN directory follow these steps:

  1. Pull the GitHub repo of chemotion_saurus locally. This is necessary, because a lot of files and folders through npm will be added.
  2. In docusaurus.config.js: Change the current version to the new version and add the former current version to the other versions below.
  3. in sideba Chemotion ELN.js: Add the new version to the Versions category.
  4. After the first three steps, you can create a new version with npm run docusaurus docs:version:elnID <former version number>, e. g. npm run docusaurus docs:version:elnID 0.9 The version number should be the last version, but not the latest/current. The latest version will be stored in docs/eln folder and should be the version, that is currently under construction. The npm run docusaurus docs:version ... creates a new folder with the version number, that should not be edited anymore. Nevertheless it is possible to edit it. For example: you are planning a new version 0.10, that is already the current version of the code. Then you probably have a version 0.8 and a current version with the label 0.9 (but not with a versioned folder 0.9) in docusaurus. Now you create a version 0.9 through the npm command. Your current version gets 0.10 and is stored in docs Chemotion ELN and you will have one more versioned folders: 0.9 and 0.8. If you want to version the repository part of the documenation, then add the lastVersion and versions keys to the "@docusaurus/plugin-content-docs" plugin with the id: "repoID" in docusaurus.config.js and follow the steps above.
  5. If versioning is enabled, you have to use two different TOCs for each part of the documenation, instead of one TOC. Use sidebarELN.js for the Chemotion ELN part and sidebarsREPO.js for the Repository part instead of sidebars.js for all parts. Before that, the different TOCs needs probably been updated.
  6. After enabling versioning it is important to change your relative imports - if this was used before - to absolut iports, because with versioning a lot more roots will be added to your Docusaurus:
- import Foo from '../src/components/Foo';
+ import Foo from '@site/src/components/Foo';
Last updated on by maipy