Contributing to Mechanism Examples

The mechanism examples pages are the ones that would benefit the most from outside contribution. You can add examples from other teams, of course, but adding your own mechanism and going behind the design and performance on it will be ideal. If adding an example from another team, try to interview them for their input and more accurate information.

Criteria for Mechanism Examples:

• It must have been actually built and used at a competition
• You must show both the good parts and the bad parts. What was it designed for? Why were certain decisions made? How easy was it to build and manufacture? How did it actually perform? What went well and what would be changed if it was redesigned?
• Go into detail about specific parts of the design, such as the materials and parts used and why, any specific mechanisms or processes, etc.
• Detailed pictures of the CAD and/or the actual robot. Preferably public CAD made in or uploaded to Onshape.
• Extra media and links if available and applicable.

Adding Mechanism Examples

As was described in methods of contributing, there are two methods:

1. Writing the contribution on a separate platform (such as Google Docs) and getting an internal contributor to add it to the website
2. Forking and making a pull request on GitHub

The first method is pretty self explanatory, but if you choose to fork and make a pull request on GitHub, refer to the Adding a Page guide for the technical setup, then follow the structure below.

Adding a Mechanism Example

If you only have an image and a CAD link, you don’t need a dedicated page! You can add the example directly to the category’s index.mdx. A full page is worthwhile when you have enough content to write a “Behind the Design” section.

Adding to the Category Index (Advanced)

To add a CAD reference without a full page, add an entry to the exampleCards array in the category’s index.mdx. First, import your thumbnail at the top of the file (after the other imports), then add the card object:

import myMechImage from './img/your-image.webp';

export const exampleCards = [
  // ...existing entries...
  {
    title: "Team XXXX Mechanism Name",
    href: 'https://cad.onshape.com/...',
    image: myMechImage,
    imageAlt: 'Brief description of the image',
    description: 'One or two sentences about the design.',
  },
];

If exampleCards doesn’t exist in the index yet, add the export and a ## CAD References section with <MechanismCardGrid cards={exampleCards} /> below the existing writeup grid.

Creating a Full Page

Create a new .mdx file in the appropriate category folder. Use this template as a starting point:

---
title: Team XXXX Mechanism Name
description: Brief description of the mechanism.
template: splash
---

<ContentFigure src="./img/thumb/main-image.webp" alt="Mechanism name CAD render" width="80%" />

<LinkButton href="https://cad.onshape.com/...">
  CAD Document
</LinkButton>

## Behind the Design

Content about the design decisions, tradeoffs, performance, and lessons learned.

Images

Images for a mechanism example page go in an img/ folder next to the .mdx file. Thumbnail images used by the mechanism examples landing page go in img/thumb/.

Use .webp format, compress with squoosh before adding.

For thumbnail images, use a 1:1.545 or 1.545:1 aspect ratio. This matches the aspect ratio of Onshape’s “print” output using tabloid paper size (landscape for wide, portrait for tall).

Tip

To crop an existing image to the right aspect ratio, use GIMP (or any image editor) to find the pixel dimensions from your image’s shorter side and add pixels to reach the target ratio.

Adding a Mechanism Category (Optional)

If the mechanism type you’re adding doesn’t have a category yet, you’ll need to create one first. Adding a category involves two parts: the MDX content files, and updating an Astro component that powers the landing page. The content files are straightforward; the component edit requires some TypeScript familiarity.

Note

If you’re not comfortable editing Astro components, you can skip the landing page step and note in your pull request or Google Doc that an internal contributor should handle it.

Content Files

1. Create a new folder under src/content/docs/mechanism-examples/ named after the mechanism type. If there are multiple subtypes (like elevators having cascade and continuous), create subfolders for each.

2. Create an index.mdx landing page in the folder using this template:

---
title: Category Name
description: Description of the mechanism category.
template: splash
---

# Category Name

Description of the mechanism category and what examples are included.

3. Add the category and its pages to src/config/sidebarConfig.ts under the mechanism examples section.

Landing Page Component (Advanced)

The mechanism examples landing page is powered by src/components/content/MechanismExamplesLanding.astro. To make the new category appear as a card on that page, find the categories array in the component and add a new entry:

{
  title: 'Category Name',
  href: '/mechanism-examples/your-category/',
  imageAlt: 'Brief image description',
  description: 'One or two sentences describing the category.',
  links: [
    { label: 'Subcategory name', href: '/mechanism-examples/your-category/subtype/' },
  ],
},

The links array determines which img/thumb/ images are pulled in for the card. If the category has no subtypes, use the category’s own path. The card image is automatically taken from the first thumbnail found under that path, with no extra configuration needed.

Setting a Featured In-Depth Example (Advanced)

The landing page has a featured section that highlights a small number of particularly detailed, well-documented examples. Getting added there requires editing src/components/content/MechanismExamplesLanding.astro, specifically the inDepthExamples array near the top of the frontmatter:

{
  title: "Team XXXX Mechanism Name",
  href: '/mechanism-examples/your-category/your-page/',
  image: imageByLabel('your thumb image filename without extension'),
  imageAlt: 'Brief image description',
  category: 'Category label shown on the card',
  description: 'Two to three sentences summarizing what makes this example worth featuring.',
},

The imageByLabel call does a loose match on thumbnail filenames. Use a distinctive word from your thumbnail’s filename. This is a component edit, so the same note applies: flag it in your pull request if you’d prefer an internal contributor to handle it.

Thanks for your contribution!