Skip to main content

Adding documentation

How to add and edit pages on this site, classify them by build target, and preview your changes.

This site is built with Docusaurus. Every page is a Markdown (or MDX) file in the docs/ folder of the repository.

Add a page

  1. Create a Markdown file anywhere under docs/, for example docs/getting-started.md:

    ---
    title: Getting started
    description: A one-line summary of the page, shown under the title.
    sidebar_position: 3
    compat:
    snapchat:
    status: supported
    specs:
    status: supported
    ck_web:
    status: supported
    ck_mobile:
    status: supported
    ---

    Your content here.

    The page header—title, description, and the platform compatibility strip—is rendered for you from front matter. Don't repeat the title as an # H1 in the body: a body heading replaces the whole generated header, so the description disappears with it. Start the body at ##.

    A landing that opens on a tagline sets display_title for the visible heading; title still names the page in the browser tab, search results, and the sidebar.

    description doubles as the page's search-engine summary, so write one sentence that reads well on its own. Quote it if it contains a colon (description: 'Reference: physics').

  2. The sidebar is generated automatically from the folder structure. Use sidebar_position in the front matter to control ordering, and a _category_.json file to configure how the folder appears in the sidebar:

    {
    "label": "Building Lenses",
    "position": 4,
    "customProps": { "icon": "cube" }
    }

    Folders are categories, never pages. Don't add a link to _category_.json—the build rejects it. Docusaurus' index conventions are switched off here, so index.md, README.md, or a page named like its folder (physics/physics.md) is just an ordinary page, never the folder's link. If a section needs an overview, make it a regular page inside the folder (for example, overview.md with sidebar_position: 1). Categories can declare an icon via customProps.icon; available names: rocket, cube, book, layers, wrench.

    Single-page sub-folders flatten per platform. If a folder nested inside a group has only one page visible on a build target, the sidebar generator lists that page directly in the group for that target and hides the folder there; on targets where the folder has several pages it stays a folder. This is computed at build time from the pages' targets front matter, using a Docusaurus ref to the same document, so nothing is duplicated or moved and the page keeps one URL. Nothing to configure: add a second page for that target and the folder reappears.

    Each tab opens a landing page per build target. docs/<tab>/snapchat.mdx, docs/<tab>/specs.mdx, and docs/<tab>/camera-kit.mdx (served at /<tab>/<target>) are the pages the tab at the top of the page opens for that target's readers; they are hidden from the sidebar. Each needs targets: [<target>] and compat: none, and the build fails if a tab is missing one. A tab can serve only some targets (targets in src/core/tabs.ts): Design is for SPECS only, so it has only docs/design/specs.mdx, and its tab isn't shown to Snapchat or Camera Kit readers.

    A landing orients its reader in the tab and routes them on. It's built only from the landing components, all written as Markdown so the links are checked like any other. Landing components renders every one, with its role, its limits, and its authoring shape; start there. In short:

    • Build top to bottom: <Steps> or one or more <Banner>s; the main topics as <LinkDirectory variant="featured"> (or <Showcase> / <MediaGrid>); choices as <LinkDirectory> boxes or <LinkGrid compact>; the tab's map as <LinkDirectory variant="index">, under a ### per sidebar group; and a <HelpList> to close.
    • Alternate boxed and unboxed sections, and don't open with a paragraph that repeats the description.
    • Grids pick their columns from their item count; give an item its own icon with <CardIcon name="…" /> when the automatic one is wrong or repeated.
    • The build enforces the rest: a known <LinkDirectory> variant, no index-row descriptions, descriptions on all of a section's cards or none, one <Showcase> a page, and no landing links to pages hidden from its target. See "Enforced by the build" on the reference page.

    Link only pages the landing's target can see. When you add an important page to a tab, add it to that tab's landings too.

  3. Preview your change locally:

    npm start

    This runs the Docusaurus development server with hot reload. It is a local authoring convenience only—the deployed site is served as static files by the custom web server in server/.

Images and other assets

Put assets in static/ and reference them with an absolute path. For example, static/img/lens-studio-logo.png is available at /img/lens-studio-logo.png:

![Lens Studio logo](/img/lens-studio-logo.png)

Media for a SPECS-only page goes under static/img/specs/<area>/. Don't add new files under the older static/img/spectacles/ folder.

Screenshots and clips of Lens Studio

Declare a screenshot or clip of Lens Studio with the global <Capture> component instead of a Markdown image. It carries the file's final path, what the reader should notice, and the spec for taking it, so a page can ship before its media exists:

<Capture
src="/img/specs/interaction-kit/get-started-prefab.png"
alt="The InteractionKit prefab selected in the Scene Hierarchy"
show="Scene Hierarchy with the InteractionKit prefab selected and expanded; crop to the panel"
ui="scene-hierarchy"
/>

src, alt, and show are required; a missing one fails the build. While the file is absent from static/, the page renders the show spec as a placeholder and the build prints a [captures] … line. npm run captures-todo lists every pending capture by page, or by Lens Studio panel with -- --by-ui. CAPTURES_STRICT=1 npm run build-docs fails on any pending capture, as a release gate. Use .webm for a clip. Examples: docs/develop/dev/capture-demo.mdx.

Link to other docs pages with relative file paths ([text](./other-page.md)). They follow the file if its URL changes and work when the docs are read on GitHub or in an editor. Absolute URL paths ([text](/other-page)) still build, but prefer the file path. Broken links of either kind fail the production build, so they are caught in CI.

Link a Lens Scripting symbol with an @ls/ target, never a URL: not the symbol's page here (/api/…, which the build rejects) and not the old developers.snap.com reference (npm run api:links rewrites those). The build resolves it to the symbol's page in the API reference:

Create the request with [InternetModule](@ls/InternetModule).
Choose a camera with [CameraId](@ls/CameraModule.CameraId).
Open it with [createWebView](@ls/InternetModule#createWebView).

Namespaced symbols use a dot (Physics.ForceMode); a member goes after #, in any case. An unknown symbol fails the build, so a typo never ships as a dead link. To find a symbol's exact name, search src/data/lsApiIndex.json (generated by npm run api:build, which npm start runs first). Link a symbol on its first mention in a section; later mentions stay plain code.

Editor Scripting symbols use @ed/ the same way: [SceneObject](@ed/Editor.Model.SceneObject), or a module's class as [CheckBox](@ed/LensStudio:Ui.CheckBox); their names are in src/data/edApiIndex.json. Package typings (Interaction Kit, UI Kit) have no reference on this site: link those to developers.snap.com.

Formatting UI labels

Anything you see in Lens Studio's interface—panels, buttons, menu items, components, assets, fields, options—is written in bold, exactly as it's labelled: the Asset Browser panel, click Import, the Segmentation Texture asset, its Mask Type field. Menu paths bold each step: Scene Hierarchy > + > Sphere.

Inline code is only for things that are code or that you type: identifiers and API names (SceneObject, getComponent()), file names and paths (.ONNX, Scripts/Main.ts), values, keys, and commands. Formatting a panel name as code makes it look like something to type, and dilutes code formatting where it matters.

The build enforces the clear-cut cases: inline code that is a multi-word Title Case label (`Asset Browser`) or a menu path of them fails with the bold version to use (src/plugins/remarkUiLabelsNotCode.ts). Single words can't be checked automatically—Texture may be a type name—so for those the rule is yours to follow: a panel, button or option is bold.

Dividers

Headings already separate sections, so don't put a --- rule before one—or at the end of a page, where there's nothing left to separate, or beside a <details> expander, which is already its own panel. All three fail the build (src/plugins/remarkNoRedundantRules.ts). A rule is only for a break between two runs of content that have no heading between them, and even then, a heading is usually the better choice.

Expandable sections

Use the standard HTML expander for content most readers can skip—a long prompt, a full script, background detail:

<details>
<summary>Lens Studio TypeScript Agent System Prompt</summary>

…content…

</details>

Write the title plainly: no "Click to expand" (the Show button says that) and no <strong> around it (the panel sets its weight). To give a title a one-line description, bold just the title and follow it with the description: <summary><strong>Tables</strong> — Read and write structured data</summary>. The description is set quieter than the title.

Build targets

Readers pick a build target—Snapchat, SPECS, or Camera Kit—and the site personalizes navigation and content to it. Docs are classified with targets front matter:

---
title: Building for SPECS
targets: [specs]
---

Allowed values are snapchat, specs, camera-kit, and all. Omitting targets means all: the page appears for every build target. Unknown values fail the build.

Classification controls visibility, not access: off-target pages disappear from the sidebar, but they keep their URL, stay crawlable, and render normally when opened directly—with a notice offering to switch build targets.

Page URLs carry the build target being viewed as ?target=, for example /develop/some-page?target=specs. Tab landings such as /get-started/specs don't get one, because their path already names the target. Copying a link from the address bar or a heading's copy-link button keeps it, so the person you share it with sees the same content. Their own build target doesn't change: the page tells them they're viewing it from a shared link and offers to switch.

To send readers to one target's version of a page, add ?target= to a Markdown link, before any #anchor:

See [hand tracking on SPECS](./hand-tracking.md?target=specs#set-up).

Use the ids from front matter: snapchat, specs, or camera-kit. Pin a target only when the destination's content differs by target and the reader needs one particular version. Most links should leave it out so readers stay on their own build target.

Inline differences

When a page is shared but a detail differs per target—a preview image, a GIF, a paragraph—use <TargetBlock> (available in every doc, no import needed):

<TargetBlock targets="specs">
![Preview on SPECS](/img/preview-specs.gif)
</TargetBlock>

<TargetBlock targets="snapchat camera-kit">
![Preview on mobile](/img/preview-mobile.gif)
</TargetBlock>

Only the block matching the reader's build target is visible. A live example:

You are reading the docs as a Snapchat developer.

You are reading the docs as a SPECS developer.

You are reading the docs as a Camera Kit developer.

How to write a block:

  • Each block stands on its own. Readers see one platform's content, so a block can't contrast itself with text they never see (avoid phrases like instead of Creative Kit or unlike Snapchat). Say what this reader does.
  • A caveat goes in an admonition inside the block. If the block tells readers that something on the page doesn't apply to them or behaves differently on their platform, wrap it in :::note or :::caution so it isn't missed. A platform's version of an ordinary step, such as how to preview or upload, stays plain text.
  • Name the platform when the block states a constraint or a required step. Open with "When building for Camera Kit, …" or "When building for Snapchat, …", matching the build target picker. Every block is in the page's HTML, so copied or scraped text keeps its context. Avoid "In Snapchat, …", which reads as "inside the Snapchat app".
  • Tabs are for variants inside one platform, such as iOS, Android and Web within Camera Kit. Never use tabs to switch between Snapchat, SPECS and Camera Kit; the build target picker does that.
  • Don't scope what every reader needs. If a feature only runs on one platform, its steps apply to everyone who can use it; the compatibility strip already says where it runs. If a whole page only describes one platform's app flows, change its targets instead of adding a "this page doesn't apply" note.

Shared page or separate pages?

Prefer a single shared page, and split only when a target genuinely needs substantially different documentation:

  • Small differences (an image, a callout, a short paragraph) → keep one shared page and use <TargetBlock>.
  • Substantial differences → keep the shared overview as all and add real child pages classified per target, with descriptive titles. For example: a shared "Physics" overview with a targets: [specs] child called "Physics on SPECS"—a SPECS reader's sidebar shows both, other readers see neither the child nor a gap.

Do not maintain duplicate copies of whole documents across targets.

Platform compatibility

Every page declares compat front matter: either how its feature behaves on each platform—which drives the chip strip under the title and the expandable "Platform details" panel—or compat: none, which shows no strip. Never hand-write compatibility badges, banners, or "only available on …" sentences in the body; the strip replaces them.

When a page shows the strip

The strip answers one question: can I use this in my Lens, on my platform? Therefore it belongs on pages that document a Lens capability—a feature, component, API, framework, or template whose availability differs by platform. Everywhere else, declare compat: none:

  • A single platform's SDK or integration guide (Camera Kit iOS, Android, Web): the page is the platform. A strip there can only be wrong ("Partial mobile support" on the iOS guide).
  • The Lens Studio editor itself—panels, shortcuts, plugins, importers and exporters, packages, pairing, project settings. Lens components and runtime assets documented in the workflow section (Scene Set-up, Adding Interactivity, image/video/animation assets) keep it.
  • Process and reference—getting started, publishing and review, FAQs, release notes, programs, support, migration guides.
  • Design guidance and navigation pages—the home page and the tab Overview pages, whose content switches with the selected platform.

When in doubt: if a reader on one platform could build the thing and a reader on another couldn't, show the strip. compat: none is still a decision you write down—leaving compat out fails the build.

compat:
snapchat:
status: supported # supported | degraded | not_supported
notes:
- text: Session size capped at 8 participants on mobile
severity: info # info (default) | degraded
restrictions:
sponsored: not_permitted # id and state must exist in the registry
specs:
status: supported
ck_web:
status: supported
ck_mobile:
status: not_supported
reason: requires the Snapchat app # optional, shown after "Not supported —"
global: # optional: applies to every platform that supports the page
restrictions:
age_gating: "Requires 13+ audience setting when session chat is enabled"
notes:
- ref: internet_required # a registered note — see "Wording" below

The rules that matter when authoring:

  • All four platforms, always. A missing platform key fails the build—absence is never a state. A fully supported page collapses the bar to "Available on all platforms" and, with no notes, shows no details button; that silence is a promise to the reader, so don't add filler notes.
  • severity is a policy, not a mood. degraded means a mainstream use case is broken or meaningfully worse on that platform, and turns its chip amber. Parameter caps and edge cases are info, which never changes chip color. Restrictions never change chip color either.
  • Restrictions are registry-controlled. Pages reference them by id only; labels and icons come from docs/compat/registry.yaml at build time. Unknown ids or states fail the build. A new restriction is a PR to the registry, reviewed by the owner listed there.
  • Page-wide (global) entries need two supporting platforms. They render under "Applies to all platforms"; with a single supporting platform that can only mean that platform, so the build sends you to put them on its entry instead.

Wording

Notes and reasons are the one free-text part, and they're held to rules the build enforces:

  • Say what the status can't. A note is a limit ("Supports up to two faces"), a version floor ("Requires Camera Kit SDK 1.28 or later"), a permission, or a behaviour difference ("English-only transcription on mobile"). Never restate the status—"Partial support", "Limited compatibility", "Only supported on SPECS", "Not supported"—and never hedge ("may not work / perform"). If you can't name the difference, leave the note out: an amber status with no note is honest; filler isn't.
  • A reason gives the cause, not the platform. It's shown after "Not supported" on that platform's own row, so "not available on mobile" on Camera Kit Mobile says nothing. Write a cause such as "requires the Snapchat app" or "requires hand tracking" instead.
  • One fact, one wording. Caveats that recur are registered once in docs/compat/registry.yaml (notes:) and referenced by id—- ref: internet_required—so every page phrases them identically. A free-text note that nearly matches a registered one fails the build and names the ref to use. Before writing a new note, check the registry; if it will recur, register it.

Point readers to another page

When a platform can't use the page's feature but another page covers the same need for it, add see to that platform's entry. UI Widgets doesn't run on SPECS, but Spectacles UI Kit does the same job there:

compat:
specs:
status: not_supported
see:
doc: ../../frameworks/ui-kit/get-started.mdx
label: Spectacles UI Kit

When the page covers two needs, give a list of up to two, most relevant first:

specs:
status: not_supported
see:
- doc: ../networking/internet-access.mdx
label: Internet Access
- doc: ../networking/remoteservice-gateway.mdx
label: Remote Service Gateway

The platform's row in the details panel gains a "See Spectacles UI Kit" link (one row per link). When a reader whose build target is that platform opens the page, the off-target notice adds a "Go to Spectacles UI Kit" action, using the first link.

  • doc is a relative path to a .md or .mdx file, like any doc link, optionally with a #heading. The build fails when it matches no doc, or when that doc is hidden from the platform's readers (its targets leave out their build target).
  • label is the page name only. The row already reads "See …".
  • For Snap docs outside this site, use url instead of doc. For example, Snapchat's multiplayer kit lives in the Games docs: url: https://developers.snap.com/games/connected-framework/overview. Only https://developers.snap.com pages outside Lens Studio are allowed. The build can't check them, so prefer doc whenever the page is here.
  • Only on a platform that isn't fully supported. The status stays honest: a different tool for the same job is not_supported, not degraded. The status follows what the page was designed for: a template built for phones is not_supported on SPECS even if its API runs there; the see link is how SPECS readers find their version.
  • Only when the other page meets the same need. A partial overlap sends readers to a page that doesn't answer their question; explain it in the body instead, or leave it out.

Examples

The common case—works everywhere, nothing to add. The bar collapses to a single "Available on all platforms" line and no details control renders:

compat:
snapchat:
status: supported
specs:
status: supported
ck_web:
status: supported
ck_mobile:
status: supported

Fully supported with nuances—the bar stays green and gains "· 2 platform notes"; the notes live in the details panel. This is the right shape for version floors, parameter caps, and edge cases (severity: info is the default, shown here only for clarity):

compat:
snapchat:
status: supported
notes:
- text: Session size capped at 8 participants on mobile
severity: info
specs:
status: supported
ck_web:
status: supported
ck_mobile:
status: supported
notes:
- text: Requires Camera Kit SDK 1.28 or later

Genuinely degraded—a mainstream use case is meaningfully worse, so the platform's entry goes amber. Either author status: degraded, or let a severity: degraded note force it:

compat:
snapchat:
status: supported
notes:
- text: Tracking quality reduced on low-end devices
severity: degraded
specs:
status: supported
ck_web:
status: supported
ck_mobile:
status: supported

Platform-exclusive feature—unsupported platforms stay declared, quiet gray, optionally with a reason. With a single supporting platform there is no "page-wide": its restrictions and notes go on its own entry:

compat:
snapchat:
status: supported
notes:
- ref: internet_required
restrictions:
sponsored: review_required
specs:
status: not_supported
reason: requires the Snapchat app
ck_web:
status: not_supported
ck_mobile:
status: not_supported

A live example of every state: Platform compatibility sample. Component internals and semantics: src/components/PlatformCompat/README.md.