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.

🚀 Setup

1. Install Visual Studio Code. (Download here)

2. Install the following VSCode extensions:

   • Astro
   • Prettier
   • Code Spell Checker

   

3. Clone this repository.

4. Run the install script to setup the dev environment.

   Linux

   ./install.sh

   Windows

   Run the following command in an elevated command line:

   ./install.bat

   Or

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

5. If not windows, run ./install.sh in the terminal.

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 astro ...	Run CLI commands like astro add, astro check
pnpm astro -- --help	Get help using the Astro CLI

📂 Folder Structure

• Directorypublic

  • …
• Directorysrc

  • assets
  • Directorycontent

    • Directorydocs

      • …
    • config.ts
  • …
• astro.config.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 files, are placed in the public/ directory.

While the content folder structure and file names is 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.
• 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.

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/bar/foo

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

2. Create a file called foo.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.

🏗️ 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/.

The image assets are automatically optimized by Astro at build time.

However the image assets should be optimized manually before committing, to reduce the size of the repository.

TinyPNG can be used to optimize the images.

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