Tech Tip: How to Use Markdown in Onshape Document Notes

Onshape already provides a natural home for most kinds of information. A question or a quick heads-up belongs in a comment. Revision changes belong as release notes. A single value, such as a part number or material, belongs in a property. Each of these tools is built with a purpose, and you should lean on them.

However, one kind of information falls outside their scope: The standing reference that explains a design, that is, how it works, and how to drive it when it is parametric. That knowledge typically lives in someone’s head, or is buried in a file nobody can locate. Document notes, the markdown workspace attached to your Onshape document, is where it belongs.

Markdown is simply text with a thin layer of structure. A handful of symbols yield headings, tables, lists, and formula blocks, and the source stays legible even as raw text. Below are the patterns that earn their place in document notes, the ones the other tools cannot accommodate, with examples you can copy and adapt.

Markdown Supported in Onshape Document Notes

A Quick Way to Decide What Goes Where

If it is a question or a quick note to a teammate, use a comment. If it is what changed in a release, use release notes. If it is a single metadata field, use a property. If it is a reference that explains the design, how to use it, or the data behind it, use document notes. Everything below sits firmly in that final category.

Pattern 1: Theory of Operation

The geometry shows what the design is. It says nothing about how it works or why it took that form. That standing explanation has no native field in Onshape, and it is precisely what markdown excels at.

A teammate who reads this grasps the design’s logic before touching it. Without it, the slotted hole reads as sloppy tolerancing, and someone “fixes” it into a plain round hole.

Pattern 2: How to Drive the Parametrics

If your document is heavily parametric, the single most valuable thing you can document is how to operate it: which variables to change, what they drive, and what to leave alone. No other tool holds operating instructions for the model itself.

This transforms a model that only its author can operate into one that anyone on the team can use correctly.

Pattern 3: Reference Data That Informs the Design

Lookup data you relied on while designing, but that never appears in the geometry, belongs here. For example, a property holds a single value, so a table of related values is markdown’s domain.

Torque values and thread-locker notes are exactly the sort of detail that gets passed around verbally and then lost. A small table beside the model preserves it with the design permanently.

Pattern 4: The Method and Assumptions Behind Your Numbers

When a dimension derives from a calculation or a standard, record the method and the assumptions, not merely the result. This is a reference, not a change record, so it has no business in release notes. Markdown’s formula block keeps it legible.

The last line is the payoff. It stops a future engineer from “optimizing” a wall that was never load-driven in the first place.

Pattern 5: Requirements and Intent

Properties capture the values the design landed on. They do not capture what the design was trying to achieve. A short requirements table with a “why it matters” column gives the geometry its context.

When someone proposes a change, this table tells them instantly whether it breaks a requirement or just a preference.

Use Multiple Markdown Tabs for Bigger Designs

Here is something many people overlook: Onshape can render an entire tab as a markdown file. The formatting does not display, but the full text sits right there in the document, so you are not confined to a single notes field. On a larger project, you can maintain several markdown documents as tabs: theory of operation in one, a parametric user guide in another, and reference data in a third. Each lives alongside the model and stays as plain text.

Because it is all plain text, it travels well. You can export it, search it, or hand it to an AI assistant that can ingest your reference and help you reason about the design.

A Few Habits That Keep Notes Useful

Write for the reader with zero context, because eventually that reader will be you. Confine it to a standing reference, and let comments, release notes, and properties carry conversation, change history, and metadata. Update the notes in the same motion as the model so the two never drift apart. Keep it lean. A clear theory of operation and one solid reference table outweigh three pages that nobody reads.

This Tech Tip provides the markdown patterns that belong in document notes. If you want to go deeper into parametric design, check out our resources on FeatureScript custom features.