Se rendre au contenu

CTrack Docusaurus help

23 mars 2026 par
CTech Metrology, Luc Wens

CTrack Docusaurus Manual - Instructions

This document explains how to set up, develop, build, and deploy the CTrack documentation site built with Docusaurus 3.7.0, using Obsidian as the primary editor for documentation pages.

Prerequisites

  • Node.js version 18.0 or higher (check with node --version)
  • npm (comes bundled with Node.js)
  • Obsidian (obsidian.md) — free for personal use

If you don't have Node.js installed, download it from nodejs.org (LTS version recommended).

Initial Setup

Open a terminal, navigate to this Docusaurus folder, and install dependencies:

cd CTrack/Docusaurus
npm install

This reads package.json and downloads all required packages into a node_modules/ folder. This folder is local and should not be committed to git (it is already covered by .gitignore).

You only need to run npm install once, or again after pulling changes that update package.json.

Install Obsidian Compatibility Plugin

To let Docusaurus understand Obsidian-style wikilinks and embeds, install the remark plugin:

npm install remark-obsidian --save-dev

Then register it in docusaurus.config.js under the docs preset:

// At the top of docusaurus.config.js
import remarkObsidian from 'remark-obsidian';

// Inside the config, under presets → docs:
presets: [
  [
    'classic',
    {
      docs: {
        // ... existing settings ...
        remarkPlugins: [remarkObsidian],
      },
    },
  ],
],

Note: If remark-obsidian is not available or causes issues, an alternative is docusaurus-plugin-obsidian-bridge. Install with npm install docusaurus-plugin-obsidian-bridge --save-dev and add it to the plugins array instead.

Setting Up Obsidian as Editor

Open the Vault

  1. Open Obsidian
  2. Choose "Open folder as vault"
  3. Select the docs/ folder inside your Docusaurus project (e.g., CTrack/Docusaurus/docs)

This makes every markdown file in docs/ visible and editable in Obsidian's sidebar.

Required Obsidian Settings

Configure Obsidian so its output stays compatible with Docusaurus. Open Settings (gear icon, bottom-left):

Setting Location Setting Value Why
Files & Links New link format Path from current file Docusaurus needs relative paths (./image.png), not shortest-path or vault-absolute
Files & Links Use [[Wikilinks]] OFF Docusaurus uses standard [text](path.md) links. Turn this off so Obsidian generates markdown-style links. If you prefer wikilinks, keep it ON but make sure the remark-obsidian plugin is installed (see above)
Files & Links Show all file types ON Makes _category_.json and other non-markdown files visible in Obsidian's file explorer
Files & Links Default location for new attachments In subfolder under current folder Keeps images next to the markdown files that reference them
Files & Links Subfolder name images Convention: each section stores images in a local images/ folder
Editor Strict line breaks ON Matches Docusaurus markdown rendering

Recommended Obsidian Plugins

These community plugins improve the editing experience (install via Settings → Community plugins):

  • Linter — auto-formats markdown on save; can enforce YAML frontmatter order
  • Templater — create templates for new documentation pages with pre-filled frontmatter
  • Paste image rename — auto-renames pasted screenshots to meaningful filenames

Page Template for Templater

Create a Templater template (e.g., _templates/doc-page.md) outside the docs/ folder so Docusaurus ignores it:

---
sidebar_position: <% tp.system.prompt("Sidebar position?") %>
---

# <% tp.file.title %>

When creating a new page, invoke Templater to insert this skeleton.

Obsidian Workflow

Creating a New Page

  1. In Obsidian, navigate to the desired subfolder (e.g., user-guide/)
  2. Create a new file (Ctrl+N or right-click → New note)
  3. Name it with a URL-friendly slug (e.g., calibration.md) — lowercase, hyphens instead of spaces

  4. Add the YAML frontmatter at the top: 

    ---sidebar_position: 5---
  5. Write the content using standard markdown
  6. Register the page in sidebars.js (see Sidebar Registration below)

Editing Existing Pages

Simply open any .md file in Obsidian's file explorer and edit. The Docusaurus dev server (npm start) will hot-reload changes in the browser automatically.

Adding Images

Option A — Paste directly (recommended): With the "Paste image rename" plugin, just paste a screenshot (Ctrl+V). Obsidian saves it to the images/ subfolder and inserts a relative link automatically.

Option B — Manual:

  1. Save the image to the appropriate images/ folder next to the markdown file

  2. Insert a reference: 

    ![Calibration dialog](./images/calibration-dialog.png)

Linking Between Pages

With wikilinks disabled (recommended), link to other pages using relative markdown paths:

See [Alignments](./alignments.md) for details.

With wikilinks enabled (requires remark-obsidian plugin):

See [[alignments]] for details.

Both produce working links in Docusaurus. The first style is more portable and explicit.

Using Admonitions

Docusaurus admonitions (:::note, :::tip, etc.) render as plain text in Obsidian's editor but will look correct on the built site. You can install the Admonition Obsidian plugin to get a styled preview inside Obsidian as well.

Docusaurus syntax (works in both Obsidian and Docusaurus):

:::tip
Helpful advice or a best practice.
:::

Obsidian-native callout syntax (use only if remark-obsidian plugin is active):

> [!tip]
> Helpful advice or a best practice.

Stick with the ::: syntax for maximum compatibility unless you've verified the plugin converts callouts correctly.

Sidebar Registration

When you add a new page, you must tell Docusaurus where it appears in the navigation.

Option A: Auto-generated sidebar (simplest for Obsidian use)

Change sidebars.js to use auto-generation:

/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const sidebars = {
  docs: [
    {
      type: 'autogenerated',
      dirName: '.',
    },
  ],
};

module.exports = sidebars;

With this approach, the sidebar is built automatically from the folder structure and sidebar_position values in frontmatter. No manual editing of sidebars.js is needed — just set the position in frontmatter and put the file in the right folder.

This is the recommended approach when using Obsidian, since it means creating a page in Obsidian is all you need to do.

Option B: Manual sidebar (current setup)

Add the document ID to sidebars.js. The ID is the file path relative to docs/, without .md:

// Example: adding docs/user-guide/calibration.md
'user-guide/calibration',

Project Structure

Docusaurus/
├── docusaurus.config.js       # Main configuration (title, URL, navbar, footer, theme)
├── sidebars.js                # Sidebar navigation structure
├── package.json               # Node.js dependencies and scripts
├── instructions.md            # This file
│
├── docs/                      # ← Open this folder as Obsidian vault
│   ├── intro.md               # Homepage (served at /)
│   ├── whats-new.md           # Release notes
│   ├── .obsidian/             # Obsidian vault config (auto-created, gitignore it)
│   ├── introduction/          # Introduction section
│   │   ├── _category_.json    # Section label and position
│   │   ├── about.md
│   │   ├── terms.md
│   │   └── installation.md
│   ├── user-guide/            # User's Guide section
│   │   ├── _category_.json
│   │   ├── user-interface.md
│   │   ├── configurations.md
│   │   ├── alignments.md
│   │   ├── live.md
│   │   ├── recorded.md
│   │   └── database.md
│   ├── advanced/              # Advanced section
│   │   ├── _category_.json
│   │   ├── orientation-conventions.md
│   │   └── directory-structure.md
│   └── device-guides/         # Device Guides section
│       ├── _category_.json
│       ├── tcp.md
│       ├── analog-out.md
│       ├── cdaq.md
│       └── optotrak.md
│
├── src/
│   └── css/
│       └── custom.css         # CTech branded theme (colors, navbar, sidebar, etc.)
│
└── static/
    └── img/
        ├── logo.png           # CTech Metrology logo (navbar)
        └── favicon.ico        # Browser tab icon

Git Ignore Additions

Add these to .gitignore to keep the Obsidian vault config out of version control:

# Obsidian
docs/.obsidian/

Key Configuration Files

docusaurus.config.js

The main configuration file. Important settings:

Setting Current Value Purpose
title CTrack V5.0 Manual Site title shown in navbar and browser tab
tagline Dynamic 3D Measurement Software Subtitle
url https://ctechmetrology.com Production URL (update when deploying)
baseUrl / Base path (change if hosted in a subdirectory)
routeBasePath / Docs are served at root, not under /docs/
blog false Blog feature is disabled
remarkPlugins [remarkObsidian] Converts Obsidian syntax to Docusaurus-compatible output

sidebars.js

Defines the navigation sidebar. If using autogenerated mode, this file is minimal and the sidebar is driven by folder structure plus frontmatter. If using manual mode, add new pages by their document ID.

category.json

Each subfolder in docs/ has a _category_.json that controls how the section appears in the sidebar:

{
  "label": "User's Guide",
  "position": 3,
  "link": {
    "type": "generated-index"
  }
}
  • label: display name in the sidebar
  • position: ordering among sibling sections
  • link.type: "generated-index": auto-generates a landing page listing all pages in the section

These files are visible in Obsidian but should only be edited as raw JSON (Obsidian treats them as plain text).

custom.css

The CTech branded theme at src/css/custom.css. This file is shared with the LicenseManager documentation and provides consistent CTech branding across both projects. It defines:

  • CTech brand colors (Blue, Frame Blue, Gold, Cream, Sand, Beige, Brown tones)
  • Light and dark mode support
  • Styled navbar, sidebar, headings, tables, code blocks, and more

Writing Documentation

Markdown Files

Each documentation page is a markdown file in docs/. Every file should start with YAML frontmatter:

---
sidebar_position: 1
---

# Page Title

Content goes here...

The sidebar_position controls the order within its section. The first # heading becomes the page title.

Adding Images

Place images alongside markdown files in an images/ subfolder and use relative paths:

![Description](./images/my-screenshot.png)

For global images (logo, favicon), use static/img/ and reference from markdown as:

![Description](/img/my-image.png)

When pasting screenshots in Obsidian with the recommended settings, images are automatically saved to the images/ subfolder with a relative link inserted.

Admonitions

Docusaurus supports styled callout boxes:

:::note
General information or a neutral note.
:::

:::tip
Helpful advice or a best practice.
:::

:::warning
Something to be cautious about.
:::

:::danger
Critical warning — may cause data loss or errors.
:::

Code Blocks

Use fenced code blocks with language identifiers for syntax highlighting:

```cpp
// C++ code with syntax highlighting
double value = node->GetPropertyDB().GetNumeric("MaxDeviation", 0.0);
```

```bash
# Shell commands
npm run build
```

Writing Conventions

Follow the conventions from Manual/Conventions.txt:

  • Lists: start with a capital letter
  • Colonized items: Item: this item is an example.
  • Dialog references: use the exact UI term in double quotes (e.g., "Start Engine")
  • Screenshot sizing: dialogs at 50%, ribbon icons at 10%

Development Server

To preview the documentation site locally with live reload:

npm start

This starts a local development server at http://localhost:3000 and opens a browser window. Most changes to markdown files and CSS are reflected live without needing to restart.

Press Ctrl+C in the terminal to stop the server.

Typical workflow: keep npm start running in a terminal while editing in Obsidian. Every time you save a file in Obsidian, the browser auto-refreshes with the updated content.

Building for Production

To create an optimized production build:

npm run build

This generates static HTML, CSS, and JavaScript in the build/ folder. The build process will:

  • Report any broken links (configured to throw an error)
  • Warn about broken markdown links
  • Optimize all assets for production

Testing the Production Build

To preview the production build locally before deploying:

npm run serve

This serves the contents of build/ at http://localhost:3000.

Deployment

Option 1: Static File Hosting

The build/ folder contains a fully static site that can be deployed to any web server. Simply copy the contents of build/ to your web server's root directory.

Option 2: GitHub Pages

If deploying to GitHub Pages:

  1. Update docusaurus.config.js:

    • Set url to your GitHub Pages URL (e.g., https://lucwens.github.io)
    • Set baseUrl to your repo name (e.g., /CTrack/)
    • Add organizationName and projectName fields

  2. Deploy:

    npm run deploy

Option 3: Internal / Local Use

For distributing the manual with CTrack releases, the build/ folder can be bundled as a local help system. Users can open build/index.html directly in their browser.

Useful Commands

Command Description
npm install Install dependencies (first time or after package.json changes)
npm start Start development server with live reload
npm run build Create production build in build/ folder
npm run serve Preview production build locally
npm run clear Clear Docusaurus cache (useful if you see stale content)

Troubleshooting

Port already in use

If port 3000 is occupied, Docusaurus will ask to use another port. You can also specify one:

npm start -- --port 3001

Stale content after changes

If changes don't appear, clear the cache and restart:

npm run clear
npm start

Broken link errors during build

The build is configured to throw errors on broken links (onBrokenLinks: 'throw'). Check the error output for the specific broken link and fix it in the source markdown file or in sidebars.js.

Node.js version issues

Docusaurus 3.7.0 requires Node.js 18 or higher. If you see compatibility errors, update Node.js to the latest LTS version.

Obsidian Vault Not Showing All Files

If _category_.json or other non-.md files are not visible in Obsidian, go to Settings → Files & Links → Show all file types → ON.

Wikilinks Not Resolving in Docusaurus

Make sure remark-obsidian is installed and registered in docusaurus.config.js. Alternatively, disable wikilinks in Obsidian settings and use standard markdown links.

Images Not Showing in Docusaurus

Check that image paths are relative (starting with ./) and that the image files are committed to git. Obsidian may use vault-relative paths if the link format setting is wrong — verify it is set to "Path from current file".

Quick-Start Checklist

  1. ☐ Clone the repo and run npm install in the Docusaurus/ folder
  2. ☐ Install remark-obsidian and register it in docusaurus.config.js
  3. ☐ Open docs/ as an Obsidian vault
  4. ☐ Configure Obsidian settings (link format → "Path from current file", wikilinks off, attachments in subfolder)
  5. ☐ Add docs/.obsidian/ to .gitignore
  6. ☐ (Optional) Switch sidebars.js to autogenerated mode
  7. ☐ Run npm start and start editing in Obsidian
VPS servers comparison