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 README.
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.
- use .mdx as filename ending in GitHub
- Insert at the top of every page:
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.
- After you have inserted a new page, add its
idfrom the metadata section at the top of the file to the TOC (table of contents) so that it will be visible on the page.
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 here: https://fontawesome.com/ and import them in the page, too. The color palette is from the Infima library.
For example following code snippet...
To create a button diffrent from the regular one, e. g. with a different size, you need to use a React button with
You can change the size of a button in its style attribute with values in
%, pixel (
em. Common icon sizes inside buttons are
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 Downlaod Button with the filepath(s) - separated by comma - in
files and the button text in
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.
Images can be inserted as Markdown or as HTML for special configurations (resizing etc.) or if the image is inside an HTML tag:
There should be no /static in src.
Insert two white spaces at the end of the line.
link to another page in the docu with the
slug or if not available the
id as anchor:
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
random number with a dot
highlight elements, e. g. UI elements
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 here.
Currently versioning is not enabled for the 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/eln directory follow these steps:
- Pull the GitHub repo of chemotion_saurus locally. This is necessary, because a lot of files and folders through npm will be added.
docusaurus.config.js: Change the
currentversion to the new version and add the former current version to the other versions below.
sidebarsELN.js: Add the new version to the
- 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.9The version number should be the last version, but not the latest/current. The latest version will be stored in
docs/elnfolder 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/elnand 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
versionskeys to the
"@docusaurus/plugin-content-docs"plugin with the
docusaurus.config.jsand follow the steps above.
- If versioning is enabled, you have to use two different TOCs for each part of the documenation, instead of one TOC. Use sidebarsELN.js for the 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.