Kladde documentation

User documentation for Kladde, the electronic lab notebook (ELN) used at Friedrich Schiller University Jena. Kladde is built on the open-source cheminfo platform. These pages are written for Bachelor chemistry students in their first synthetic-chemistry lab practical, and for researchers at the university, and combine step-by-step guides, annotated screenshots and short screen recordings.

• Site: https://kladde.uni-jena.de (custom domain, currently not assigned; see Known gaps)
• GitHub Pages project URL: https://steinbeck-lab.github.io/kladde_Digifellows/
• Repository: https://github.com/Steinbeck-Lab/kladde_Digifellows

The site is a static Docusaurus 3 (React) site in English and German. Its visual design, the Laborkladde theme, is documented in DESIGN.md.

Contents

Navigation	Source	What it covers
Welcome	docs/index.mdx	What Kladde is, then the numbered index of the workflow, and credits
How to start › 01 New Entry	docs/new-entry.md	The main walkthrough in six steps: open an entry, title it, add reagents and the reaction, calculate amounts (Ansatzberechnung), look up GHS hazard data, set the status
How to start › 02 Reaction Scheme	docs/reaction-scheme.md	Toolbar reference for the OpenChemLib structure editor
How to start › 03 Snippets	docs/snippets.md	Shortcuts for the reaction description: predefined sentences, _metainfo keys, reagent references
04 Sample Analysis	docs/sample-analysis.md	The sample page tab by tab: overview, stock, safety, physical data, spectra, images, molecule
Sample Analysis › IR	docs/ir.md	Exporting the spectrum, auto peak picking from either route, and the IR prediction tool
Sample Analysis › NMR, MS	docs/nmr.md, docs/ms.md	Not written yet; pages of entry 04, not numbered steps
05 Report	docs/report.md	Not written yet
About › What is ELN?	docs/what-is-eln.md	ELNs, the FAIR principles, what Kladde is
About › Meet our team	docs/christoph.md, docs/kevin.md, docs/kohulan.md, docs/soyee.md	One page per team member: role, photo, bio
About › License	docs/license.md	The licensing terms in plain language

The numbered entries and their order come from sidebars.js. Pages that are not written yet, including the Soyee Chan bio, show the line brewing in progress... ☕. Old URLs from the MkDocs site redirect: /how-to-start/ → /new-entry/, /chemicaleditor/ and /adding-chemical-equation/ → /reaction-scheme/, /scheme/ → /snippets/, /eln/ → /what-is-eln/.

Local development

Requires Node.js 20 or newer. Dependencies are pinned in package.json and package-lock.json:

npm ci                 # install exactly the locked versions
npm start              # English preview at http://localhost:3000, reloads on change
npm run start:de       # German preview (the dev server serves one language at a time)
npm run build          # production build of both languages into build/
npm run serve          # serve build/ locally to check the result, including search
npm run check-media    # every picture and recording a page points at still exists

• The build stops on broken links between pages. Links to anchors only warn.
• The build does not check src and poster paths inside raw HTML, which is how screenshots and videos are embedded. Run npm run check-media after moving or renaming a picture: it lists references that point at nothing, and files under static/assets/ that no page uses.
• The search index is generated by npm run build; test search with npm run serve.
• build/, .docusaurus/ and node_modules/ are ignored by git.

Deployment

Every push to main builds the site and publishes it to GitHub Pages; the workflow is .github/workflows/deploy.yml. Nothing built is committed — the build runs on GitHub's machine and is handed straight to Pages. The Actions tab shows each run and can start one by hand.

The gh-pages branch is no longer used. It still holds the old MkDocs site and is kept as a record.

Three settings have to agree, under Settings → Pages:

• Source: GitHub Actions. With "Deploy from a branch", GitHub serves the repository files as they are and shows README.md instead of the site, because build/ is never committed.

• Custom domain: kladde.uni-jena.de. It needs a DNS CNAME record pointing at steinbeck-lab.github.io; static/CNAME (one line, no trailing newline) carries the domain into every build. Once the domain is assigned, https://steinbeck-lab.github.io/kladde_Digifellows/ redirects to it.

• url and baseUrl in docusaurus.config.js belong to the custom domain (baseUrl: '/'). Serving from the project URL instead needs baseUrl: '/kladde_Digifellows/', or the pages load without their styles and scripts.

• Renaming or deleting a page changes a public URL. Add a redirect for the old address to the @docusaurus/plugin-client-redirects entry in docusaurus.config.js.

• After a deployment, open the pages you changed on the live site.

Repository layout

docusaurus.config.js     Site config: URL, languages, plugins, redirects, search, navbar, footer
sidebars.js              Navigation order; entry('id') marks a numbered workflow entry
docs/                    One file per page (see Contents)
static/
  CNAME                  Custom domain for GitHub Pages
  assets/<page>/         One folder per page: its screenshots, recordings (*.mp4) and posters
  assets/chemical-editor/  Toolbar icons of the structure editor, used by two pages
  assets/images/         Team photos
  img/favicon.svg        Site icon
i18n/de/                 German interface strings, and German page translations once they exist
src/css/custom.css       The Laborkladde theme: tokens and styles
src/theme/               Docusaurus theme overrides (see Theme and components)
src/components/          EntryIndex, Gloss, MdxVideo, OpenKladde, Icons
src/lib/                 Numbered entries and sidebar classes, read from the sidebar
src/plugins/             rehypeTapedMedia, translationStatus
src/clientModules/       Self-hosted fonts; timestamp links into videos
DESIGN.md                The design system
PRODUCT.md               Product facts behind the design
LICENSE                  CC BY 4.0 for the content, MIT for the site code

Writing content

Pages are Markdown. .md files are read as plain CommonMark, so the raw HTML the guides use (inline icons, <video>, inline SVG) renders as written. Use .mdx only when a page needs a React component, as the home page does for its index.

A new page

1. Create docs/<kebab-case-name>.md with title and description in the front matter; the home index shows the description under the entry.
2. Add it to sidebars.js. Use entry('<name>') if it is a numbered step of the workflow; the numbers in the sidebar, on the home index and on the page follow that order.
3. Run npm run build to check the links.

Front matter used on this site

---
title: New Entry                    # the page title, the sidebar label and the link labels
description: Start your entry and prepare for the synthesis.   # shown on the home index
---

Every page carries those two keys and nothing else. The previous and next links follow the sidebar order; a page ends the chain with pagination_next: null (Report does), and pages under About have no links at all. pagination_next_label and pagination_prev_label relabel a link and are specific to this site (src/theme/DocItem/Paginator).

Screenshots and recordings: every page has its own folder, static/assets/<page>/, holding its pictures, recordings and poster images. Icons shared by more than one page live in static/assets/chemical-editor/, team photos in static/assets/images/. Reference a file relative to the page, as the guides do, and run npm run check-media afterwards:

<img alt="Customized entry title" src="../assets/new-entry/img_new-entry-title1.png"/>

<video controls muted poster="../assets/new-entry/thumbnail_how-to-start-3-4.png">
  <source src="../assets/new-entry/how-to-start-3-4.mp4" type="video/mp4">
</video>

Every <img> and every <video> is framed as a taped-in print automatically, and a percentage width becomes the width of that frame; a print never grows wider than the text. Two kinds of image stay inline instead: anything with class="function-icon" (a button or key shown inside a sentence) and anything carrying an inline style. Team photos use class="kl-portrait" and the person's name as alt. Short silent clips use autoplay muted loop playsinline instead of controls.

A tip that opens in place: a plain <details> with a <summary> title becomes a fold box. A <strong> title followed by text makes that text a teaser, visible while the box is closed.

A word that explains itself: <gloss note="…">word</gloss> marks the word and opens the note above it on hover, focus or tap; screen readers get the note through aria-describedby.

A link to a moment in a video: give the <video> an id; the link names the video and the time in seconds, and still jumps to the video without JavaScript:

<a href="#snippets-preset" data-video="snippets-preset" data-time="172" class="kl-timestamp">Jump to 02:52</a>

House style

• The title lives in the front matter, ## for numbered steps, ### for alternatives.
• Imperative voice: "Click", "Enter", "Add".
• UI labels in single quotes ('Prefs', 'Save Data'); column names, fields and typed keys in backticks (mmoles, r1, _metainfo).
• > blockquotes for tips and warnings.
• German lab terms (Ansatzberechnung, Versuchsanleitung, H- & P-Sätze) are intentional.
• A page that isn't written yet contains only brewing in progress... ☕.

Translations

• Interface strings (navigation, footer, notices, labels) live in i18n/de/. After adding or changing a <Translate> string in src/, run npm run write-translations -- --locale de and translate the new entries in i18n/de/code.json. The German interface strings were drafted during the redesign and should be checked by a German speaker on the team.
• Pages: copy docs/<page>.md to i18n/de/docusaurus-plugin-content-docs/current/<page>.md and translate it, keeping the front matter keys. Until that file exists, the German page shows the English text with a notice, and the condition line at the top of every page says whether the German text exists yet (src/plugins/translationStatus.js).
• Sidebar category labels are translated in i18n/de/docusaurus-plugin-content-docs/current.json.

Theme and components

The Laborkladde theme treats the documentation as the squared-paper lab notebook Kladde replaces. DESIGN.md records the system; the tokens are the --kl-* custom properties at the top of src/css/custom.css.

Token	Value	Source and use
--kl-ink	#002350	FSU blue; text (15.5:1 on white) and the navbar
--kl-green	#4E7F0A	Faculty green #74A740 darkened for text (4.8:1); links, entry numbers, Open Kladde
--kl-gold	#887440	FSU gold (4.55:1); margin rule, sidebar numbers, section labels
--kl-ink-soft	#3A5F91	Secondary text (6.5:1)
--kl-paper	#FCFDFE	Page ground with a faint 5 mm grid

Type is self-hosted from npm (no Google Fonts): Atkinson Hyperlegible Next for text and Barlow Semi Condensed for titles, labels and numbers.

Customized parts of Docusaurus:

• src/theme/MDXComponents.js extends the Markdown components (native <details>, <gloss>, video anchors), the extension point the Docusaurus docs describe.
• src/theme/DocItem/Content, src/theme/DocItem/Paginator and src/theme/PaginatorNavLink are not on Docusaurus's list of components that are safe to customize, and the language link in DocItem/Content uses useAlternatePageUtils from @docusaurus/theme-common/internal. Check them after every Docusaurus upgrade against the new versions in node_modules/@docusaurus/theme-classic/lib/theme/.
• src/plugins/rehypeTapedMedia.js adds the print frames at build time and picks one of three tape arrangements per print; the tape strips are rendered images, static/img/tape-1.png to tape-3.png, with their origin embedded; src/plugins/translationStatus.js records which pages are translated.
• The search is @easyops-cn/docusaurus-search-local, pinned at 0.55.3. Its optional AI widget dependency is not installed.

Known gaps

• Custom domain: kladde.uni-jena.de is not assigned in the repository's GitHub Pages settings, and its DNS record still points at soyeechan230126.github.io, the personal account the repository came from. GitHub checks that record against the repository claiming the domain, so it has to name steinbeck-lab.github.io first. Until then the site has no working public address: baseUrl is /, which fits the custom domain only. Clones made before the move can update their remote with git remote set-url origin https://github.com/Steinbeck-Lab/kladde_Digifellows.git.
• German text: no page is translated yet, and the German interface strings need review.
• Unwritten pages: NMR, MS, Report and the Soyee Chan bio.
• Media: the largest videos are 27 MB (snippets-preset.mp4), 17 MB, 13 MB, 13 MB and 11 MB; every file under static/ is copied into both language builds. kevin-jablonka.jpg is a 1.5 MB, 3024×3024 photo shown 240 px wide. The three autoplay clips have no poster.
• Unused files: static/assets/chemical-editor/img_chemicaleditor_topright.png.
• Copy and markup: "ammendment" in new-entry.md; playinline instead of playsinline in snippets.md; <font> tags, removed from HTML years ago, in snippets.md and sample-analysis.md.
• License attribution: LICENSE still names the work "ELN Documentation".

License

The documentation content (text, screenshots, videos) is licensed under CC BY 4.0, the site code under MIT. Screenshots and videos show third-party software (the ELN and OpenChemLib) whose interfaces and trademarks remain with their owners. The full terms are in LICENSE and on the site's License page.