Getting Started

This documentation is intended to serve as the place to record the processes, preferences, and code conventions used by the organization.

You can explore the documentation from the sidebar.

✍️ Contributing

The docs use Astro Starlight for documentation.

This doc will only cover the specifics of the WiMetrix docs, and not how Starlight works.

Read the Starlight docs to learn about how to use it.

The documents are written in MDX, an extension of markdown that supports JSX syntax and breaking files into logical chunks.

Learn markdown here.

There are 2 ways to contribute new content to the docs:

1. Recommended

   Use Visual Studio Code. - Live preview - Automatic formatting - Autocomplete and AI suggestions - Syntax highlighting - Spellcheck

2. Use a markdown GUI to create the document and then copy the contents to the src/content/docs folder.

   StackEdit is a web based markdown editor that can be used for this.

✅ Prerequisites

Before setting up:

• make sure you have access to the WiMetrix docs repository on GitHub. The install script handles everything else.

🚀 Setup

1. Clone or download the git repository.

   git clone https://github.com/WiMetrixDev/docs.git
   cd docs

   Or download the repo from GitHub.

2. Run the install script to set up Git, Node.js, and pnpm.

   Linux

   Run the following command in the terminal:

   ./install.sh

   Windows

   Run the following command in an elevated command line:

   ./install.bat

   Or

   Right click on ./install.bat and Run as Administrator.

3. Install Visual Studio Code. (Download here)

4. Install the following VSCode extensions:

   • Astro
   • Prettier
   • Code Spell Checker

   

5. Install project dependencies.

   pnpm install

6. Start the development server.

   pnpm dev

7. Open the site in your browser at localhost:4321. Adding or updating documents should automatically show the changes in the browser.

🧞 Commands

All commands are run from the root of the project, from a terminal:

Command	Action
pnpm install	Installs dependencies
pnpm dev	Starts local dev server at localhost:4321
pnpm build	Build your production site to ./dist/
pnpm preview	Preview your build locally, before deploying
pnpm format	Format all files with Prettier
pnpm spellcheck	Run spellcheck on the repo
pnpm optimize-images	Convert and optimize all images in assets/ folders to WebP
pnpm lint	Run format, spellcheck, astro validations, and image optimization
pnpm astro ...	Run CLI commands like astro add, astro check
pnpm astro -- --help	Get help using the Astro CLI

📂 Folder Structure

• Directorypublic

  • …
• Directorysrc

  • assets
  • components
  • styles
  • content.config.ts
  • Directorycontent

    • Directorydocs

      • …
  • …
• astro.config.mjs
• sidebar.mjs
• package.json
• tsconfig.json
• …

Starlight picks up .md or .mdx files in the src/content/docs/ directory.

Images and other assets can be colocated in the same folder as the .md or .mdx file, and linked using a relative path.

Shared assets (used by multiple docs) can be added to src/assets/.

Static assets, like favicons or pdf files, are placed in the public/ directory.

While the content folder structure and file names are not enforced, consistent structure makes content easier to navigate and find.

📄 Naming conventions

It is recommended to follow the following conventions:

• Use kebab-case for file and folder names
  • Use lowercase alphabet.
  • Use dashes - to separate words in file names.
• Folder structure should correspond to the content hierarchy.
• Create a folder for each page, to colocate assets.
• Store page assets in the assets folder inside the page folder.
• File names should match the page’s url slug.
  • Exception: section index files (file name = parent folder name, e.g. products/spts/spts.mdx) use the parent folder path as the slug (products/spts), not the full file path.
• Add the page to the sidebar by updating the ./sidebar.mjs file

📝 Adding Content

Content is stored in the src/content/docs directory as markdown files.

Each mdx has metadata at the top of the file, which is used to generate the page.

Common metadata includes:

• title: The title of the page.
• description: A short description of the page.
• slug: The URL of the page.
• sidebar (optional): Overrides the default sidebar setting for the page.
  • sidebar.label: The label to display in the sidebar. title is used by default. Only pass if the label is different from the title

For example, when creating reference for a module named Bar of the Foo product, do the following:

1. Create a folder at src/content/docs/products/foo/bar

   (Create any folder in the path that doesn’t exist).

2. Create a file called bar.mdx in the new folder.

   Note

   While Starlight supports both .md and .mdx files, it is recommended to use .mdx files.

   MDX files are a superset of markdown, and can be used to import components, and reuse markdown content.

3. Add the metadata to the top of the file.

   ---
   title: "Bar Module"
   description: Overview of the Bar module of the Foo Product
   sidebar: { label: "Bar" }
   slug: products/foo/bar
   ---

4. Add the page to the sidebar in ./sidebar.mjs

   Sidebar entries can be route path strings, or detailed config objects. Check the starlight docs for more info.

   export const sidebar = [
       ...
      {
        label: "Products",
        collapsed: true,
        items: [
         ...
          {
            label: "Foo",
            collapsed: true,
            items: [
             "products/foo",
            "products/foo/bar",
           ],
          },
        ],
      },
   ];

5. The page should show in the sidebar. You can now add content to the page.

🔤 Spell Checking

The Code Spell Checker VSCode extension will underline words it doesn’t recognize.

If the flagged word is a valid technical term, product name, or acronym used by WiMetrix, add it to the words array in cspell.json at the root of the repository.

This can also be done via suggest edits in VSCode.

{
  "words": [
    ...
   "YourNewWord"
  ]
}

Caution

Only add words that are genuinely valid. Do not add words to suppress typos — fix the typo instead.

🏗️ Assets

Like stated above, images and other assets should be colocated in the same folder as the content file, and linked using a relative path.

If an asset needs to be referenced from multiple places, it should be added to src/assets/.

Before committing images, run the optimize script to convert them to WebP and reduce size:

pnpm optimize-images

This will:

• Convert all images in assets/ folders (PNG, JPG, JPEG, GIF, AVIF) to WebP at 60% quality
• Scale any image wider than 1800px down to 1800px, preserving aspect ratio
• Update all MDX references to the converted filenames automatically

To also convert existing WebP files (e.g. to re-optimize them), pass --include-webp:

pnpm optimize-images --include-webp

Note

pnpm lint also runs optimize-images automatically.

It might be simpler to just run the lint script instead of the optimize script, since it also checks for other issues.

Mermaid Diagrams

Mermaid diagrams are supported natively, and can be added in a markdown codeblock directly.

Example:

```mermaid
%%{ init: {"theme": "forest"} }%%

flowchart TD
    A[Node A] -->|A to B| B{Node B}
```

This will be rendered as:

Theming in Mermaid diagrams

Please add %%{ init: {"theme": "forest"} }%% at the top of each Mermaid codeblock to ensure consistent colors in all diagrams.

Generating Mermaid ERD from DB

Mermerd is used to automatically generate ERDs from DB tables.

ERD is generated as a Mermaid diagram in a markdown file.

The script at db/gen-erd.sh is used to generate the file.

While complex and large ERD diagrams may not be suitable for automatic generation due to the size of the diagram, simpler diagrams can be generated automatically.

1. Create a config file in the db folder.

   The config file should be named after the ERD file, and end with .yaml.

   For example, if the ERD file is named carton-audit.md, the config file should be named carton-audit.yaml.

   Refer to the Mermerd config file docs.

2. Add a script to package.json that invokes the gen-erd.sh script.

   • Generate the erd file in the same folder as the content file.
   • The generated .md filename should be prefixed with and underscore (_). This will make sure Starlight will not pick it up as a content file.

   {
     ...
     "scripts": {
       ...
      "gen:erd:<name>": "./db/gen-erd.sh ./db/<name>.yaml <output-path>.md",
     }
   }

3. Run the script to generate the file.

   pnpm gen:erd:<name>

4. Link the generated file in the content file.

   The file must be an .mdx file, and not a .md file.

   import Erd from "<path>.md";
   
   <Erd />

Creating Screenshots and Diagrams

Screenshots and diagrams can be created using Figma.

Use this figma file to create diagrams and screenshots.

📥 Generating PDF

Starlight to PDF is used to generate PDF files from the content pages.

1. Add a script file to the pdf folder.

   The script is a mjs file.

   Use the generatePdf function from the pdf/pdf.mjs file.

   The function takes the following parameters:

   • path: The base route path of the docs website.

     (products means https://docs.wimetrix.com/products will be the base path)

   • fileName: The path of the output pdf file.

   • depth: An optional number of levels to include in the PDF.

     Using depth of 2 with path products for example means products, and products/pack-and-ship will be included, but products/spts/sewing will be excluded.

     All matched routes are included if not provided.

   • routes: An optional array of route paths to include in the PDF.

     ["guides", "guides/odoo"] will only include the routes guides and guides/odoo. All other routes will be excluded.

     All matched routes are included if not provided.

   import { generatePdf } from "./pdf.mjs";
   
   generatePdf({
     baseUrl: "https://docs.wimetrix.com",
     path: "products/foo",
     fileName: "foo",
     routes: ["products/foo", "products/foo/bar"],
   });

   Caution

   The PDF is generated using the live website, not the local files.

   To use the local files, you need to run the dev server and use the local url and port in the script.

   generatePdf({
     baseUrl: "https://docs.wimetrix.com",
     baseUrl: "https://localhost:4321",
   path: "products/foo",
     fileName: "foo",
     routes: ["products/foo", "products/foo/bar"],
   });

2. Add a script to the package.json file.

   {
     ...
     "scripts": {
       ...
      "gen:pdf:foo": "node ./pdf/gen-foo.mjs",
     }
   }

3. Run the script to generate the PDF.

   pnpm gen:pdf:foo

🌿 Git Workflow

All changes must go through a pull request. Never commit directly to main.

Creating a branch

Create a new branch from main before making any changes.

git checkout main
git pull
git checkout -b feat-add-spts-sewing

Branch naming:

• feat-<description> — new content or new feature
• fix-<description> — corrections, typos, broken links
• Use lowercase kebab-case throughout.

Committing changes

Stage and commit your changes with a short, descriptive message.

git add .
git commit -m "Add SPTS sewing module docs"

Pushing changes to remote branch

If this is your first time pushing to the remote branch, use the -u flag to set the upstream branch:

git push origin -u feat-add-spts-sewing

If you have already pushed, or the remote branch is already set:

git push

Linting for potential issues

Run the lint script before creating a pull request.

This will check for formatting, spelling, and incorrect link issues, and also convert images to WebP and optimize them.

pnpm lint

If the script reports any issue, resolve them.

If there are no issues reported, you can proceed with the pull request

Opening a pull request

Then go to the repository on GitHub and open a pull request against the main branch on GitHub.

For more information on how to open a pull request, see the GitHub docs.

Keep PRs focused

One topic per pull request. Avoid bundling unrelated changes — it makes review harder and slows things down.

Review process

All pull requests are reviewed by the tech lead. Address any requested changes by pushing additional commits to the same branch. Once approved, the tech lead will merge the PR.